REST API 레퍼런스#

Ultralytics Platform은(는) 데이터셋, 이미지, 프로젝트, 모델, 학습, 내보내기 및 배포에 프로그래밍 방식으로 접근할 수 있는 REST API를 제공합니다.

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

API 개요#

API는 핵심 Platform 리소스를 중심으로 구성되어 있습니다:

graph LR
    A[API Key]:::start --> B[Datasets]:::proc
    A --> C[Projects]:::proc
    B -->|images| G[Images]:::proc
    C -->|contains| D[Models]:::proc
    B -->|train on| D
    D -->|deploy| E[Deployments]:::proc
    D -->|export| F[Exports]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

인증#

대부분의 엔드포인트에는 API 키가 필요합니다. 공개 데이터셋, 프로젝트 또는 모델 읽기, 공개 데이터셋 이미지 목록 조회, 공개 모델에서 추론 실행, Explore 검색과 같이 공개 콘텐츠를 노출하는 엔드포인트는 익명 요청도 허용하며, API 키가 제공될 경우 더 많은 정보를 반환합니다.

API 키 발급받기#

1. Settings > API Keys(으)로 이동합니다.
2. Create Key 클릭
3. 생성된 키를 복사합니다.

자세한 지침은 API Keys를 참조하세요.

인증 헤더#

API 키를 Bearer 토큰으로 포함합니다:

Authorization: Bearer YOUR_API_KEY

예시#

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/account/summary

기본 URL#

모든 API 엔드포인트는 다음을 사용합니다:

https://platform.ultralytics.com/api

리소스 경로#

리소스는 데이터베이스 ID가 아니라 Platform URL에 나타나는 읽기 쉬운 이름을 통해 지정됩니다:

• {owner}은(는) 개인 사용자 이름 또는 팀 워크스페이스 핸들입니다: 4~32자, 세그먼트 사이에 단일 하이픈이 포함된 소문자 영숫자.
• {dataset}, {project}, {model}, {deployment}은(는) 최대 128자의 동일한 소문자 하이픈 패턴을 따릅니다.
• {imageId} 및 {exportId}은(는) API가 반환하는 24자리의 16진수 ID입니다.
• PATCH을(를) 통해 리소스 이름을 변경하면 표시되는 name과 URL 이름이 함께 변경되며, 응답에는 계속해서 접근할 수 있도록 현재 URL 이름이 반환됩니다.

속도 제한(Rate Limits)#

API는 API 키당 슬라이딩 윈도우 제한을 적용합니다. 각 경로는 하나의 카테고리에 속하며 각 카테고리는 독립된 카운터를 가지므로, 20회의 예측 요청이 기본 허용량을 소모하지 않습니다.

결제 체크아웃 및 팀 관리와 같은 브라우저 전용 Platform 경로는 API 키 트래픽에 적용되지 않는 별도의 제한을 가집니다.

속도가 제한될 경우, API는 헤더와 JSON 본문이 모두 포함된 429을(를) 반환합니다:

Retry-After: 12
X-RateLimit-Reset: 2026-02-21T12:34:56.000Z

{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

전용 엔드포인트 (무제한)#

배포의 고유한 serviceUrl을(를) 직접 호출할 때(예: https://predict-abc123.run.app/predict), 전용 엔드포인트는 Platform API 키 요청 제한의 적용을 받지 않습니다. 이 경우 처리량은 배포된 서비스 구성에 따라 달라집니다.

응답 형식#

성공 응답#

응답은 리소스별 필드를 포함하는 JSON 객체입니다. 일반적인 엔벨로프(envelope)는 존재하지 않습니다. 목록 엔드포인트는 개수와 함께 이름이 지정된 컬렉션을 반환하고, 변경 요청(mutation)은 변경된 식별자를 반환합니다.

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

데이터를 포함하는 응답에는 해당 워크스페이스의 스토리지 지역인 region (us, eu 또는 ap)도 포함됩니다.

오류 응답#

모든 오류 응답은 error 메시지를 포함하는 JSON 객체입니다:

{
    "error": "Dataset not found"
}

페이지네이션#

페이지네이션 방식은 컬렉션에 따라 다릅니다:

데이터셋 API#

YOLO 모델 학습을 위해 라벨이 지정된 이미지 데이터셋을 생성, 탐색 및 관리합니다. Datasets documentation을(를) 참조하세요.

데이터셋 목록 조회#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

소유자의 공개 데이터셋을 반환하며, 키로 해당 워크스페이스를 볼 수 있는 경우 비공개 데이터셋도 함께 반환합니다.

쿼리 매개변수:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets/acme-vision?limit=10&includeSamples=false"

응답:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

데이터셋 가져오기#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

dataset 키 아래에 전체 dataset 객체를 반환하며, 여기에는 classNames, splits, versions, source 및 사용자가 정의한 metadata 객체가 포함됩니다.

데이터셋 생성#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

본문:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

응답 (201):

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

데이터셋 업데이트#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

본문 (부분 업데이트):

{
    "name": "Warehouse Safety",
    "description": "New description",
    "visibility": "public",
    "metadata": { "location": "factory-2", "reviewed": true }
}

허용되는 필드: name, description, visibility, metadata, tags, classNames, classColors, format, task, license, iconColor, iconLetter, starred. 커스텀 메타데이터를 지우려면 빈 metadata 객체({})를 전송하세요. 메타데이터 키는 128자로, 직렬화된 객체는 500,000자로 제한됩니다.

응답:

{
    "success": true,
    "dataset": "warehouse-safety"
}

이름을 변경하면 URL 이름도 바뀌므로, 이후 요청에서는 반환된 dataset 값을 사용하세요.

데이터셋 삭제#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

데이터셋을 trash(휴지통)로 이동하며, 이곳에서 30일 동안 복원할 수 있습니다.

데이터셋 복제#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

접근 가능한 데이터셋을 이미지 및 라벨과 함께 개인 워크스페이스 또는 팀 워크스페이스로 복사합니다.

선택적 본문 (모든 필드 선택 사항):

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

응답 (201): id, owner, dataset, name, imageCount, classCount, region. 연결된 스토리지 소스를 기반으로 하는 데이터셋은 파일이 복사되지 않으므로 409을(를) 반환합니다.

데이터셋 내보내기 다운로드#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

서명된 NDJSON 다운로드 URL을 반환합니다. 데이터셋의 현재 상태를 내보내려면 v을(를) 생략하세요. 생성된 이후 변경된 사항이 없는 경우 캐시된 내보내기를 재사용합니다.

쿼리 매개변수:

응답:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

특정 버전을 요청하면 cached 대신 downloadUrl 및 version이 반환됩니다.

데이터셋 버전 생성#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

데이터셋의 수정 불가능한 번호가 지정된 스냅샷을 생성하고 NDJSON 내보내기를 저장합니다. 편집자 권한이 필요합니다.

본문 (선택 사항):

{
    "description": "Added 500 training images"
}

응답:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

이전 버전 이후 데이터셋이 변경되지 않아 해당 스냅샷이 대신 반환된 경우, reused은 true입니다.

버전 설명 업데이트#

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

본문:

{
    "version": 2,
    "description": "Fixed mislabeled classes"
}

응답: {"ok": true}

데이터셋 버전 복원#

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

이미지 바이트를 복사하지 않고 저장된 버전에서 이미지, 주석, 클래스를 다시 빌드합니다.

본문:

{
    "version": 2
}

응답: {"version": 2, "imageCount": 1000}

데이터셋 통계 가져오기#

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

클래스별 주석 개수, 이미지 및 주석 히스토그램, 히트맵을 반환합니다. 대규모 데이터셋은 샘플링되며, 이 경우 sampleSize은 기여한 이미지의 수를 보고합니다.

응답 (요약):

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "locationHeatmap": {
        "bins": [
            [5, 10],
            [8, 3]
        ],
        "maxCount": 50
    },
    "dimensionHeatmap": {
        "bins": [
            [2, 5],
            [3, 1]
        ],
        "maxCount": 12,
        "minWidth": 10,
        "maxWidth": 1920,
        "minHeight": 10,
        "maxHeight": 1080
    },
    "classNames": ["person", "forklift"],
    "cached": true,
    "sampleSize": null
}

클래스 관리#

클래스 병합 (주석을 대상 클래스로 재할당한 후 소스 제거):

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

클래스 삭제 (해당 주석이 삭제되고 남은 클래스 ID가 아래로 이동):

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

두 작업 모두 success, 업데이트된 classNames 및 classColors, 그리고 변경 사항 요약(mergedClassIds 및 targetClassId, 또는 deletedClassIds 및 deletedAnnotations)을 반환합니다.

데이터 분할 재배포#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

분할 간에 이미지를 무작위로 재할당합니다. 세 백분율의 합은 반드시 100이어야 합니다.

{
    "train": 80,
    "val": 20,
    "test": 0
}

응답: success, 결과 splits 개수, 및 modified(이동된 이미지 수).

데이터셋 임베딩#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset), client.datasets.create_embeddings(owner, dataset), client.datasets.delete_embeddings(owner, dataset)

GET은 분석 요약(analyzedAt, embeddingsCount, latestImageAt, activeJob)을 반환합니다. POST는 임베딩 분석을 대기열에 추가하고 jobId이 포함된 202을 반환합니다. DELETE은 활성 작업을 취소하고 취소된 작업 ID 또는 null를 반환합니다.

이미지 클러스터링#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

완료된 분석에서 UMAP 2D 레이아웃을 반환하며, offset 및 limit(기본값 및 최대 50,000)으로 페이지가 매겨집니다. 각 항목에는 id, umapX, umapY, split, classIds, width, height, bytes, labelCount, missing이 포함됩니다.

데이터셋으로 학습된 모델 목록#

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

응답:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

데이터셋 이미지 목록#

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

쿼리 매개변수:

응답:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

선택한 이미지 가져오기#

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

제공된 최대 1,000개의 이미지 ID에 대해 동일한 이미지 모양을 반환하며, 목록 작업과 동일한 필터 및 URL 쿼리 파라미터를 허용합니다.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

데이터셋 데이터 수집#

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

완료된 업로드, 원격 아카이브 또는 연결된 스토리지 소스를 기존 데이터셋으로 처리합니다. 정확히 하나의 소스를 제공하세요:

업로드 세션은 POST /api/upload/signed-url에 전달된 assetId에 의해 데이터셋에 바인딩되며, 수집은 다른 데이터셋에 속한 세션을 거부합니다.

본문 (업로드된 아카이브):

{
    "sessionId": "session_abc123",
    "targetSplit": "train"
}

본문 (원격 아카이브 또는 NDJSON):

{
    "sourceUrl": "https://example.com/my-dataset.zip"
}

본문 (이후 수집 시 라벨 가져오기):

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

본문 (이미지별 메타데이터 연결):

{
    "sessionId": "session_abc123",
    "imageMetadata": {
        "airbus-wing.jpg": { "aircraft": { "family": "A350" }, "inspectionStatus": "reviewed" },
        "images/tail.jpg": { "aircraft": { "family": "A320" }, "inspectionSeverity": 2 }
    }
}

메타데이터 키는 폴더를 포함하여 아카이브 내의 정규화된 경로와 일치해야 합니다. NDJSON 가져오기의 경우, 각 레코드는 자체 metadata 객체를 가질 수 있으며, 이는 일치하는 imageMetadata 항목보다 우선합니다. 아카이브 경로는 1,024자, 최상위 메타데이터 키는 128자, 각 메타데이터 객체 및 전체 imageMetadata 맵은 500,000자의 직렬화된 문자로 제한됩니다.

응답 (201):

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/ingest"]:::proc
    E --> F[Process archive]:::proc
    F --> G[Dataset ready]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
image_path = Path("airbus-wing.jpg")

archive = io.BytesIO()
with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
    zf.write(image_path, image_path.name)
data = archive.getvalue()

signed = requests.post(
    f"{api}/upload/signed-url",
    headers=headers,
    json={
        "assetType": "datasets",
        "assetId": dataset_id,
        "filename": "images.zip",
        "contentType": "application/zip",
        "totalBytes": len(data),
    },
)
signed.raise_for_status()
upload = signed.json()

requests.put(upload["uploadUrl"], headers={"Content-Type": "application/zip"}, data=data).raise_for_status()
requests.post(
    f"{api}/upload/complete",
    headers=headers,
    json={"sessionId": upload["sessionId"]},
).raise_for_status()

ingest = requests.post(
    f"{api}/datasets/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

이미지 API#

24자 이미지 ID로 데이터셋 이미지를 검사, 주석 달기, 이동 및 삭제합니다. 주석 문서를 참조하세요.

이미지 가져오기#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

metadata(사용자 정의, 사용자 정의), properties(파일명, 해시, 크기, 분할, 개수, 타임스탬프), labels 및 데이터셋의 classNames을 반환합니다.

이미지 업데이트#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

주석 또는 사용자 정의 메타데이터 중 하나를 교체합니다. 두 가지 형태 중 하나만 보내고 둘 다 보내지 마세요.

본문 (주석):

{
    "labels": [
        { "classId": 0, "bbox": [0.5, 0.5, 0.2, 0.3] },
        { "classId": 1, "segments": [0.1, 0.2, 0.3, 0.2, 0.2, 0.4] }
    ]
}

본문 (메타데이터):

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

이미지 삭제#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

하나의 이미지와 해당 주석을 영구적으로 삭제합니다.

이미지 자동 주석#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

이미지에서 YOLO 추론을 실행하고 예측된 주석을 반환합니다. 저장하지는 않습니다. 결과가 마음에 들면 PATCH /api/images/{imageId}으로 결과를 다시 작성하세요.

응답: success, predictions(주석 객체), modelUsed, 및 inferenceTime. 클래스가 데이터셋과 일치하지 않는 모델은 422를 반환합니다.

이미지 일괄 이동#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

최대 1,000개의 이미지를 한 데이터셋에서 다른 분할로 이동합니다.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

파일명 또는 콘텐츠 충돌이 발생하면 바스켓 전체의 conflictPolicy로 skip, keep_both 또는 replace를 선택할 때까지 409을 반환합니다. 응답은 modifiedCount, skippedCount 및 targetSplit을 보고합니다.

이미지 일괄 삭제#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

단일 데이터셋에서 최대 1,000개의 이미지를 삭제하고 deletedCount 및 deletedImageIds을 반환합니다.

서명된 이미지 URL 가져오기#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

하나의 데이터셋에서 최대 100개의 이미지 ID에 대한 임시 서명된 URL을 반환합니다.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

응답: 둘 다 이미지 ID로 키가 지정된 urls 및 thumbnails.

프로젝트 API#

모델을 프로젝트별로 정리합니다. 각 모델은 하나의 프로젝트에 속합니다. 프로젝트 문서를 참조하세요.

프로젝트 목록 조회#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

쿼리 매개변수:

프로젝트 가져오기#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

project 객체, 모델별 요약(상태, 지표, 에포크, 가중치, 학습 인자)의 models 배열, 및 isOwner를 반환합니다.

프로젝트 생성#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "inspection",
    "name": "Inspection",
    "description": "Detection experiments",
    "metadata": {"department": "manufacturing", "cost_center": "cv-01"}
  }' \
  https://platform.ultralytics.com/api/projects

응답 (201): id, owner, project, region.

프로젝트 업데이트#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

허용되는 필드: name, description, visibility, metadata, tags, license, archived, iconColor, iconLetter, viewPreferences, 및 starred.

{
    "metadata": { "department": "research", "program": "inspection" }
}

지우려면 빈 metadata 객체({})를 보냅니다. 프로젝트 메타데이터는 데이터셋 메타데이터와 동일한 128자 키 및 500,000자 직렬화된 객체 제한을 사용합니다.

프로젝트 삭제#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

프로젝트와 해당 모델을 휴지통으로 이동하고 cascadedModels을 반환합니다.

프로젝트 복제#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

액세스 가능한 프로젝트와 완료된 모델을 복제합니다. 선택적 본문은 project, name, description, visibility, license 및 대상 owner를 허용합니다.

모델 API#

학습된 YOLO 모델 관리 — 지표 보기, 가중치 다운로드, 추론 실행 및 학습 모니터링. 모델 문서를 참조하세요.

프로젝트의 모델 목록#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

쿼리 매개변수:

모델 조회#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

쿼리 매개변수:

기본 응답에는 model 객체(상태, 작업, 지표, trainArgs, trainResults, classNames, computeCost, metadata 등)와 isOwner이 포함됩니다.

모델 생성#

POST /api/models

Python SDK: client.models.create(body=...)

가중치를 연결하거나 학습할 수 있는 학습되지 않은 모델 레코드를 생성합니다.

응답 (201): id, owner, project, model, region.

모델 업데이트#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

허용되는 필드에는 name, description, color, metadata, status, license, datasetSlug, trainArgs, trainResults, epochs, bestEpoch, bestFitness, version, trainingError, starred가 포함됩니다.

{
    "metadata": { "release": "candidate-3", "reviewed": true }
}

사용자 정의 metadata은 trainArgs, environment, trainResults과 같은 학습 소유 필드와 분리되어 있으며, 데이터셋 메타데이터와 동일한 크기 제한을 사용합니다.

모델 삭제#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

모델을 30일 동안 휴지통으로 이동합니다.

모델 파일 다운로드#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

모델 가중치에 대한 만료 기간이 짧은 서명된 URL을 반환합니다.

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

모델 복제#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

접근 가능한 모델을 기존 프로젝트에 복사합니다.

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

추론 실행#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

공개 모델은 인증 없이 예측을 수행할 수 있습니다. 비공개 및 공유 모델에는 상위 프로젝트에 대한 접근 권한이 있는 API 키가 필요합니다.

멀티파트 폼:

file 또는 source을 제공하세요. 깊이 모델은 깊이 맵의 PNG 양자화를 선택하기 위해 bits (8, 12, 또는 16)도 허용합니다. 서비스의 입력 제한을 초과하는 요청은 413을 반환합니다.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.5" \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/predict

응답:

images의 각 항목에는 shape, speed, results, 그리고 조밀 예측 작업의 경우 semantic_mask 또는 depth PNG 페이로드(bits이 12 또는 16일 때 기본 8비트 맵의 경우 제수 255, 65535인 깊이 값은 pixel × max / divisor)가 포함됩니다. metadata 객체는 이미지 수, 함수 타이밍, 작업 및 서비스 버전을 보고합니다. 내부 모델 경로는 절대 반환되지 않습니다.

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

학습 진행 상황 확인#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

상태, 에포크 진행 상황, 타이밍, 컴퓨팅 세부 정보, 학습 인수, 에포크 메트릭, 안전한 오류 세부 정보가 포함된 job을 반환하거나, 모델이 한 번도 학습되지 않은 경우 null을 반환합니다. 공개 프로젝트의 모델은 인증 없이 읽을 수 있습니다.

학습 취소#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

실행 중인 컴퓨팅 인스턴스를 종료하고 작업이 취소된 것으로 표시합니다. 학습이 더 이상 활성 상태가 아닐 때 409을 반환합니다.

학습 API#

클라우드 GPU에서 YOLO 학습을 시작하고 실시간으로 진행 상황을 모니터링하세요. 클라우드 학습 문서를 참조하세요.

graph LR
    A[POST /api/training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET .../training]:::proc
    C -->|cancel| E[DELETE .../training]:::error
    C -->|complete| F[Model Ready]:::out
    F --> G[Deploy or Export]:::proc

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef decide fill:#FF9800,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff

GPU 가용성 확인#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

GPU ID별로 키가 지정된 현재 재고 상태를 반환합니다. 공개 및 인증되지 않은 상태이며; API 키가 필요한 관리형 학습 용량을 포함하려면 managed=true을 전달하세요.

학습 시작#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://acme-vision/datasets/warehouse",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

응답:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

크레딧 잔액이 너무 낮으면 학습이 402을 반환하고, 요청된 GPU에 사용할 수 있는 용량이 없으면 503을 반환합니다.

내보내기 API#

엣지 배포를 위해 모델을 ONNX, TensorRT, CoreML, LiteRT와 같은 최적화된 형식으로 변환합니다. 배포 문서를 참조하세요.

내보내기 목록#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

쿼리 매개변수:

내보내기 생성#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

응답 (201): id, format, status (queued 또는 running), gpuType, region. 이미 진행 중인 동일한 내보내기는 409을 반환합니다.

지원되는 형식:

아래의 공유 내보내기 표에서 format 인수를 사용하세요. PyTorch는 소스 형식이므로 API 내보내기 대상이 아닙니다.

내보내기 상태 가져오기#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

status, format, args, gpuType, 타임스탬프, 그리고 완료되면 size, downloadUrl, downloadFilename을 포함하는 file 객체가 포함된 export 객체를 반환합니다.

내보내기 취소 또는 삭제#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

활성 내보내기를 취소하거나 완료된 내보내기 및 해당 파일을 삭제합니다. 응답은 수행된 작업을 보고합니다:

{
    "success": true,
    "action": "cancelled"
}

배포 API#

상태 확인 및 모니터링이 포함된 전용 추론 엔드포인트에 모델을 배포합니다. 엔드포인트 문서를 참조하세요.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|action stop| D[Stopped]:::extern
    C -->|action replace| B
    D -->|action start| C
    C -->|delete| E[Deleted]:::error
    D -->|delete| E
    C -->|predict| F[Inference Results]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

배포 목록 조회#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

쿼리 매개변수:

익명 호출자는 하나의 공개 모델로 필터링해야 합니다. 전체 워크스페이스를 나열하려면 인증이 필요합니다.

배포 생성#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

본문:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

응답 (201): id, deployment, status (creating), message, 및 region.

배포 조회#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

status, statusMessage, region, serviceUrl, 및 resources가 포함된 deployment 객체를 반환합니다.

배포 시작, 중지 또는 교체#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

단일 action 필드가 작업을 선택합니다:

{ "action": "start" }

교체하면 배포 ID, 리전 및 엔드포인트 URL을 유지하면서 새 리비전이 롤아웃됩니다. 롤아웃이 실패하면 기존 리비전은 라이브 상태로 유지됩니다. 교체 모델은 키가 접근할 수 있는 가중치를 가진 완료된 모델이어야 합니다. 완료된 작업은 status ready 또는 stopped과 함께 200을 반환하고, 여전히 롤아웃 중인 작업은 deploying 또는 stopping과 함께 202를 반환합니다.

배포 삭제#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

추론 엔드포인트를 영구적으로 제거합니다.

상태 확인#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

엔드포인트를 핑하고 예열하여 healthy, latencyMs, 및 업스트림 status 코드를 반환합니다.

배포에서 추론 실행#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

전용 엔드포인트를 통해 이미지나 동영상을 라우팅합니다. 요청 및 응답 계약은 모델 추론과 일치합니다.

멀티파트 폼:

지표 가져오기#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

쿼리 매개변수:

전체 응답에는 summary(요청 총계, 오류율, 평균 및 p50/p95/p99 지연 시간)과 timeSeries(요청, 오류, 지연 시간, CPU, 메모리, 인스턴스 수)이 포함됩니다. 스파크라인 응답은 requests24h, totalRequests, errorRate, 및 avgLatencyMs를 반환합니다.

로그 가져오기#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

쿼리 매개변수:

휴지통 API#

소프트 삭제된 프로젝트, 데이터셋 및 모델을 조회, 복원 및 영구 삭제합니다. 항목은 30일 후에 자동으로 영구 삭제됩니다. 휴지통 문서를 참조하세요.

휴지통 목록#

GET /api/trash

Python SDK: client.lifecycle.trash()

쿼리 매개변수:

응답에는 items(각각 daysRemaining 포함), total, page, limit, totalPages, 및 유형별 총계가 포함된 summary이 포함됩니다.

항목 복원#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

프로젝트를 복원하면 해당 프로젝트와 함께 휴지통으로 이동된 모델도 복원되며, restoredModels으로 보고됩니다.

영구 삭제#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

단일 항목 삭제:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

또는 전체 휴지통 비우기:

{
    "all": true
}

응답은 deletedCount과 함께 관련 있는 경우 cascadedModels 및 survivingDeployments를 보고합니다.

업로드 API#

서명된 URL을 사용하여 클라우드 스토리지에 파일을 직접 업로드합니다. 모델 업로드를 완료하면 가중치가 첨부되며, 데이터셋 아카이브 업로드를 완료하면 세션이 기록되며, 이를 데이터셋 인제스트에 전달합니다. 데이터 문서를 참조하세요.

서명된 업로드 URL 가져오기#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

본문:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

응답:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.googleapis.com/...&signature=...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

선언한 동일한 Content-Type를 사용하여 uploadUrl에 PUT 요청으로 파일을 업로드하세요.

업로드 완료#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

{
    "sessionId": "session_abc123",
    "checksum": "<optional sha-256 hex>"
}

응답: success 및 size와 contentType이 포함된 file 객체. 모델의 경우 가중치가 첨부되며, 데이터셋 아카이브의 경우 처리를 시작하려면 다음에 인제스트를 호출하세요.

스토리지 통합 API#

읽기 전용 Google Cloud Storage, Amazon S3 또는 Azure Blob Storage 계정을 연결하고 데이터셋 소스로 탐색합니다. 통합 문서를 참조하세요.

통합 목록 조회#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

id, provider, credentialIdentity, targets, 및 createdAt가 각각 포함된 integrations을 반환합니다. 자격 증명은 절대 반환되지 않습니다.

위치 검색#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

저장하지 않고 제공된 자격 증명으로 읽을 수 있는 버킷 또는 컨테이너를 나열합니다.

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

응답: {"targets": ["my-bucket", "another-bucket"]}

스토리지 연결#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

검색과 동일한 자격 증명 형태에 더해 1-50개의 버킷 또는 컨테이너 이름으로 구성된 필수 targets 배열이 필요합니다. 저장된 통합 정보와 함께 201을 반환합니다. 임시 S3 자격 증명(ASIA 액세스 키)은 거부됩니다.

객체 탐색#

GET /api/integrations/buckets/{id}/objects

Python SDK: client.storage_integrations.objects(id, target=...)

쿼리 매개변수:

entries(각 kind은 folder 또는 file임)과 다음 페이지를 위한 선택적 cursor를 반환합니다.

스토리지 연결 해제#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

공급자 데이터를 삭제하지 않고 저장된 자격 증명을 제거합니다. 연결된 데이터셋은 계속 표시되지만, 동일한 스토리지 계정이 다시 연결될 때까지 해당 파일은 사용할 수 없습니다. 워크스페이스 관리자 권한이 필요합니다.

데이터셋 가져오기 API#

타사 서비스에서 데이터셋을 가져옵니다. Roboflow 통합을 참조하세요.

Roboflow 가져오기 미리보기#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

Roboflow API 키를 가져오기 계획으로 확인합니다. 워크스페이스 세부 정보, 가져올 newDatasets, 건너뛴 항목, 지원되지 않는 항목, 확인되지 않은 프로젝트 수, bytesTotal, 및 사용자 storage 여유 공간입니다. Roboflow API 키는 본문에서 읽어오며 지속적으로 저장되지 않습니다.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Roboflow에서 가져오기#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

미리보기에서 반환된 항목을 사용하여 최대 500개의 선택된 Roboflow 프로젝트 버전에 대한 수집 작업을 대기열에 추가합니다.

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

응답 (201): imported, failed, 및 skipped 배열. 가져오기에는 스토리지 여유 공간이 필요하며, 각 데이터셋은 요금제의 가져오기당 크기 제한을 충족해야 합니다.

계정 API#

Platform 계정, 키, 스토리지 및 공개 프로필을 검사합니다. 설정 문서를 참조하세요.

계정 요약#

GET /api/account/summary

Python SDK: client.account.summary()

키를 발급한 워크스페이스의 요금제, 크레딧 잔액 및 리소스 개수를 반환합니다.

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

API 키 목록#

GET /api/api-keys

Python SDK: client.account.api_keys()

키의 워크스페이스에 대한 keyId, name, keyPrefix, createdAt와 함께 keys을 반환합니다. API 키로 인증된 요청은 메타데이터만 수신하며, 전체 키 값은 Platform UI의 설정 > API 키에서 워크스페이스 소유자에게 표시됩니다. 키를 생성하고 취소하는 곳도 여기입니다.

스토리지 사용량 확인#

GET /api/storage

Python SDK: client.account.storage()

쿼리 매개변수:

응답:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

공개 사용자 프로필 가져오기#

GET /api/users

Python SDK: client.account.profile(username=...)

쿼리 매개변수:

followerCount 및 인증된 호출자의 경우 isFollowed가 포함된 공개 user 프로필을 반환합니다.

사용자 팔로우 또는 언팔로우#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

{
    "username": "target-user",
    "followed": true
}

응답: followed 및 업데이트된 followerCount.

결제 API#

요금제 사용량 및 크레딧 장부를 확인합니다. 청구 문서를 참조하세요.

요금제 및 사용량 보기#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

plan (ID, 상태, 청구 주기, 주기 종료), metrics (스토리지 한도 및 사용량), trainingCredit, features, creditsCents 및 시트 수를 반환합니다.

거래 내역 보기#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

쿼리 매개변수:

각 거래에는 id, type (purchase, training, monthly_grant 또는 refund 등), amountCents, balanceAfter, createdAt, 선택적 receiptUrl, 및 학습 비용에 대한 모델 컨텍스트가 포함됩니다. 내부 청구 세부 정보는 절대 반환되지 않습니다.

탐색(Explore) API#

커뮤니티가 공유한 공개 프로젝트와 데이터셋을 검색합니다. 탐색 문서를 참조하세요.

공개 콘텐츠 검색#

GET /api/explore/search

Python SDK: client.explore.search()

쿼리 매개변수:

응답: projects, datasets, 및 hasMore.

curl "https://platform.ultralytics.com/api/explore/search?type=datasets&task=detect&sort=stars&limit=20"

Python SDK#

ultralytics-platform은 OpenAPI 계약에서 생성된 타입 지정(typed) Python 클라이언트로, 엔드포인트당 하나의 메서드(client.datasets.list, client.models.predict, client.exports.create, ...)를 제공합니다. 모든 메서드는 경로 매개변수를 위치 인자로, 기타 입력을 키워드 인자로 허용하며, 선택적으로 요청별 timeout 및 extra_headers을 허용합니다.

pip install "ultralytics-platform>=0.1.5" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform은 async/await 코드에 대해 동일한 리소스 트리를 노출하며, 실패한 응답은 status_code, body 및 구문 분석된 json과 함께 APIError을 발생시키고, 연결 실패는 APIConnectionError을 발생시킵니다. 전체 README는 SDK 저장소를 참조하십시오.

Python 통합#

학습 및 추론 워크플로의 경우 인증, 업로드, 실시간 메트릭 스트리밍을 자동으로 처리하는 Ultralytics Python 패키지를 사용하십시오.

설치 및 설정#

pip install "ultralytics>=8.4.120"

설치 확인:

yolo check

인증#

yolo login YOUR_API_KEY

플랫폼 데이터셋 사용#

ul:// URI로 데이터셋 참조:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

URI 형식:

플랫폼으로 푸시#

플랫폼 프로젝트로 결과 전송:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

동기화 대상:

• 학습 메트릭 (실시간)
• 최종 모델 가중치
• 검증 플롯
• 콘솔 출력
• 시스템 메트릭

API 예제#

플랫폼에서 모델 로드:

# Your own model
model = YOLO("ul://username/project/model-name")

# Official model
model = YOLO("ul://ultralytics/yolo26/yolo26n")

추론 실행:

results = model("image.jpg")

# Access results
for r in results:
    boxes = r.boxes  # Detection boxes
    masks = r.masks  # Segmentation masks
    keypoints = r.keypoints  # Pose keypoints
    probs = r.probs  # Classification probabilities

모델 내보내기:

# Export to ONNX
model.export(format="onnx", imgsz=640, quantize=16)

# Export to TensorRT
model.export(format="engine", imgsz=640, quantize=16)

# Export to CoreML
model.export(format="coreml", imgsz=640)  # use imgsz=224 for classification

검증:

metrics = model.val(data="ul://username/datasets/my-dataset")

print(f"mAP50: {metrics.box.map50}")
print(f"mAP50-95: {metrics.box.map}")

FAQ#