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 키가 필요합니다. 공개 콘텐츠를 제공하는 엔드포인트(공개 데이터셋, 프로젝트 또는 모델 읽기, 공개 데이터셋 이미지 목록 조회, 공개 모델에 대한 추론 실행 또는 탐색 검색)는 익명 요청도 허용하며, 키가 제공되면 더 많은 결과를 반환합니다.

API 키 가져오기#

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

자세한 지침은 API 키를 참조하십시오.

Authorization 헤더#

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 이름이 반환되므로 해당 리소스를 계속 사용할 수 있습니다.

속도 제한#

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을 직접 호출할 때 Platform API 키 속도 제한의 적용을 받지 않습니다(예: https://predict-abc123.run.app/predict). 이 경우 처리량은 배포된 서비스 구성에 따라 달라집니다.

응답 형식#

성공 응답#

응답은 리소스별 필드를 포함하는 JSON 객체입니다. 일반적인 envelope는 없습니다. 목록 엔드포인트는 개수와 함께 이름이 지정된 컬렉션을 반환하며, 변경 작업은 변경된 식별자를 반환합니다.

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

데이터를 포함하는 응답에는 해당 작업 공간의 스토리지 리전인 region(us, eu 또는 ap)도 포함됩니다.

오류 응답#

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

{
    "error": "Dataset not found"
}

페이지 매김#

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

데이터셋 API#

YOLO 모델 학습을 위한 라벨이 지정된 이미지 데이터셋을 생성하고, 탐색하고, 관리합니다. 자세한 내용은 데이터셋 문서를 참조하십시오.

데이터셋 목록 조회#

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 키 아래에 전체 데이터셋 객체를 반환하며, 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"
}

응답은 실제로 생성된 dataset 슬러그를 반환하므로, requireExactSlug을 설정하지 않은 경우 업로드하기 전에 읽어오세요.

응답(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)

데이터셋을 휴지통으로 이동하며, 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을 반환합니다.

데이터셋 export 다운로드#

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

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

서명된 NDJSON 다운로드 URL을 반환합니다. v을 생략하면 데이터셋의 현재 상태를 export하며, 생성 이후 변경 사항이 없을 경우 캐시된 export를 재사용합니다.

쿼리 매개변수:

응답:

{
    "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 export를 저장합니다. 편집자 액세스 권한이 필요합니다.

본문(선택 사항):

{
    "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=...)

제공된 이미지 ID를 최대 1,000개까지 동일한 이미지 형태로 반환하며, 목록 작업과 동일한 필터 및 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를 반환합니다.

데이터셋 자동 주석 달기#

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, model_id=...)

데이터셋 버전을 저장한 후, 모델을 사용하여 데이터셋의 레이블이 지정되지 않은 이미지에 레이블을 지정하는 실행을 대기열에 추가하고 202을(를) 반환합니다. 본문은 단일 이미지 엔드포인트와 동일한 modelId, confidence, iou 필드를 가지며, 이미 레이블이 지정된 이미지에도 주석을 추가하기 위한 includeAnnotated (기본값 false)과, 각 모델 클래스에 대한 데이터셋 클래스 인덱스를 제공하는 선택적 classMapping 배열 또는 이를 건너뛰기 위한 null을(를) 추가로 포함합니다. 기존 레이블은 절대 변경되지 않으며, 실행은 실제로 처리한 이미지에 대해서만 비용이 청구됩니다. 402은(는) 잔액이 예상 금액을 충족할 수 없음을 의미하고, 409는(은) 데이터셋이 준비되지 않았거나, 주석을 달 이미지가 남아 있지 않거나, 이미 진행 중인 실행이 있음을 의미하며, 422은(는) 데이터셋에 클래스가 없음을 의미합니다. 앱의 클래스 매핑 단계가 실행을 시작하기 전에 수행하는 작업인 이 엔드포인트를 호출하기 전에 classes 엔드포인트를 사용하여 클래스를 생성하십시오.

동일한 경로(client.datasets.batch(owner, dataset))의 GET은(는) 진행 중인 실행과 그 진행 상황을 반환하거나, 해제될 때까지 마지막으로 완료된 실행을 반환합니다. DELETE (client.datasets.delete_batch(owner, dataset))은(는) 진행 중인 실행을 취소하거나 결제를 정산하고 완료된 요약을 해제합니다.

이미지 일괄 이동#

PATCH /api/images/bulk

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

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

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

파일 이름 또는 콘텐츠 충돌이 발생하면 409을 반환합니다. 이때 skip, keep_both 또는 replace 중 conflictPolicy을 전체 묶음에 적용할 항목을 선택해야 합니다. 응답에는 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을 반환합니다.

프로젝트 Clone#

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가 포함됩니다. 단독으로 projectId를 전달하면 모델이 동일한 소유자의 다른 프로젝트로 이동하며, 응답은 대상에서의 모델 slug, 해당 슬러그가 이미 사용 중인 경우 renamed: true, 그리고 모델이 여전히 학습 중인 동안에는 409을 반환합니다.

{
    "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을 지정합니다. Depth 모델은 bits(8, 12 또는 16)도 허용하여 depth map의 PNG 양자화를 선택합니다. 서비스의 입력 제한을 초과하는 요청은 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 및 dense-prediction 작업의 경우 semantic_mask 또는 depth PNG payload가 포함됩니다(depth 값은 pixel × max / divisor이며, 기본 8비트 map에서는 제수가 255이고 bits이 12 또는 16이면 65535입니다). 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" }
    }
}

Training Progress 확인#

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

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

상태, epoch 진행률, 실행 시간, 컴퓨팅 세부 정보, train args, epoch metrics 및 안전한 오류 세부 정보가 포함된 job을 반환하거나, 모델이 한 번도 학습되지 않은 경우 null을 반환합니다. 공개 프로젝트의 모델은 인증 없이 읽을 수 있습니다.

학습 취소#

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

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

실행 중인 compute instance를 종료하고 작업을 취소됨으로 표시합니다. 학습이 더 이상 활성 상태가 아니면 409을 반환합니다.

Training API#

클라우드 GPU에서 YOLO 학습을 시작하고 진행 상황을 실시간으로 모니터링합니다. Cloud Training documentation을 참조하십시오.

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별 현재 재고 상태를 반환합니다. 공개이며 인증이 필요하지 않습니다. 관리형 training capacity를 포함하려면 managed=true을 전달해야 하며, 이 경우 API key가 필요합니다.

학습 시작#

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
    }
}

credit balance가 너무 낮으면 학습은 402을 반환하고, 요청한 GPU에 사용할 수 있는 capacity가 없으면 503을 반환합니다.

Exports API#

엣지 배포를 위해 모델을 ONNX, TensorRT, CoreML 및 LiteRT와 같은 최적화된 형식으로 변환합니다. Deploy documentation을 참조하십시오.

Export 목록#

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

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

쿼리 매개변수:

Export 생성#

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. 이미 진행 중인 동일한 export는 409을 반환합니다.

지원되는 형식:

아래의 공용 export 표에서 format 인수를 사용하십시오. PyTorch는 source format이며 API export target이 아닙니다.

nms=None은(는) 외부 NMS에 대해 기본적으로 원시 출력을 사용합니다. 사용 가능한 NMS 프리 헤드를 선택하려면 nms=False을(를) 설정하세요. 지원되지 않는 형식은 기본 출력 경로로 대체됩니다. 위의 nms 항목은 nms=True(으)로 NMS를 임베드할 수 있는 형식을 식별합니다.

Export 상태 가져오기#

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

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

status, format, args, gpuType, timestamp 및 완료 후 size, downloadUrl, downloadFilename을 포함하는 file 객체가 포함된 export 객체를 반환합니다.

Export 취소 또는 삭제#

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

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

활성 export를 취소하거나 완료된 export와 해당 파일을 삭제합니다. 응답에는 수행된 작업이 보고됩니다:

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

Deployments API#

상태 확인 및 모니터링 기능이 있는 전용 inference endpoint에 모델을 배포합니다. Endpoints documentation을 참조하십시오.

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

Deployment 목록#

GET /api/deployments/{owner}

Python SDK: client.deployments.list(owner)

쿼리 매개변수:

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

Deployment 생성#

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.

Deployment 가져오기#

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

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

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

Deployment 시작, 중지 또는 교체#

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

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

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

{ "action": "start" }

교체하면 deployment ID, region 및 endpoint URL을 유지하면서 새 revision을 rollout합니다. rollout에 실패하면 기존 revision이 계속 활성 상태로 유지됩니다. 교체 모델은 key가 액세스할 수 있는 weight가 포함된 완료된 모델이어야 합니다. 완료된 작업은 status, ready 또는 stopped이 포함된 200을 반환하며, 아직 rollout 중인 작업은 deploying 또는 stopping이 포함된 202를 반환합니다.

Deployment 삭제#

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

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

inference endpoint를 영구적으로 제거합니다.

상태 점검#

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

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

endpoint를 ping하고 warm up한 후 healthy, latencyMs 및 upstream status 코드를 반환합니다.

Deployment에서 inference 실행#

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

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

전용 endpoint를 통해 이미지 또는 비디오를 라우팅합니다. 요청 및 응답 계약은 model inference와 일치합니다.

멀티파트 폼:

Metrics 가져오기#

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

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

쿼리 매개변수:

전체 응답에는 summary(요청 총계, 오류율, 평균 및 p50/p95/p99 latency)과 timeSeries (requests, errors, latency, CPU, memory, instance count)이 포함됩니다. sparkline 응답은 requests24h, totalRequests, errorRate 및 avgLatencyMs를 반환합니다.

Logs 가져오기#

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

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

쿼리 매개변수:

Trash API#

soft-deleted된 프로젝트, dataset 및 모델을 확인, 복원 및 영구 삭제합니다. 항목은 30일 후 자동으로 purge됩니다. Trash documentation을 참조하십시오.

휴지통 목록 조회#

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가 보고됩니다.

Upload API#

signed URL을 사용하여 파일을 클라우드 스토리지에 직접 업로드합니다. 모델 업로드를 완료하면 해당 weight가 연결되고, dataset archive 업로드를 완료하면 세션이 기록되며 이후 이를 dataset ingest에 전달합니다. Data documentation을 참조하십시오.

Signed Upload 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",
    "headers": { "x-goog-if-generation-match": "0" }
}

선언한 동일한 Content-Type와 headers에 반환된 모든 헤더를 사용하여 uploadUrl에 PUT 요청으로 파일을 업로드합니다. 데이터셋 업로드 URL은 12시간 동안 유효하며 생성 전용입니다. 동일한 URL에 대한 두 번째 PUT는 412를 반환하고, 반환된 헤더가 없는 PUT은 400을 반환합니다.

Upload 완료#

POST /api/upload/complete

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

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

응답: success 및 size와 contentType이 포함된 file 객체. 모델의 경우 weight가 연결되고, dataset archive의 경우 다음으로 ingest를 호출하여 처리를 시작합니다.

md5이 제공되면 저장된 객체와 비교하여 검사합니다. 불일치 시 400이 반환되며, 아직 완료되지 않은 세션의 경우 업로드된 파일도 삭제하고 세션을 미완료 상태로 유지하므로 새 서명된 URL을 요청하고 다시 업로드하세요. 완료된 데이터셋 세션은 아카이브가 존재하는 동안 다시 완료할 수 있지만, 다이제스트가 다른 경쟁 완료 요청은 409를 반환합니다. 모델 세션은 완료 시 제거됩니다. checksum은 모델 파일 메타데이터로 저장되며 검증되지 않습니다.

Storage Integrations API#

읽기 전용 Google Cloud Storage, Amazon S3 또는 Azure Blob Storage 계정을 연결하고 dataset source로 탐색합니다. Integrations documentation을 참조하십시오.

통합 목록#

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)

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

데이터셋 가져오기 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이 포함된 공개 user 프로필과 인증된 호출자의 경우 isFollowed를 반환합니다.

사용자 팔로우 또는 팔로우 취소#

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 및 학습 요금에 대한 모델 컨텍스트가 포함됩니다. 내부 결제 세부 정보는 반환되지 않습니다.

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 계약에서 생성된 타입이 지정된 Python 클라이언트이며, 엔드포인트마다 하나의 메서드(client.datasets.list, client.models.predict, client.exports.create, ...)가 있습니다. 모든 메서드는 경로 매개변수를 위치 인수로, 그 외 입력을 키워드 인수로 받으며, 요청별 선택적 timeout 및 extra_headers도 지원합니다.

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

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY or the key saved by yolo login
    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 패키지를 사용하십시오. Python 3.11 이상에서는 pip install ultralytics이 ultralytics-platform SDK도 설치합니다. model.train(project=...)가 Platform을 대상으로 할 때, 학습 콜백은 SDK의 client.training.metrics()을 통해 이벤트를 스트리밍하고 OpenAPI 문서의 POST /api/webhooks/training/metrics 및 POST /api/webhooks/models/upload 작업인 client.models.upload_checkpoint()를 통해 체크포인트 업로드 URL을 요청하므로 직접 호출할 작업이 없습니다.

설치 및 설정#

플랫폼 통합에는 Python>=3.11 및 ultralytics>=8.4.120가 필요합니다:

pip install "ultralytics>=8.4.120"

설치를 확인합니다:

yolo check

인증#

yolo login YOUR_API_KEY

Platform 데이터셋 사용#

다음 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 형식:

Platform으로 푸시#

결과를 Platform 프로젝트로 전송합니다:

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",
)

동기화되는 항목:

• 학습 메트릭(실시간)
• 최종 모델 가중치
• 검증 플롯
• 콘솔 출력
• 시스템 메트릭
• 학습 인수 및 호스트 환경(호스트 이름, 운영 체제, Python, 하드웨어, 깃 커밋, 명령줄)

API 예제#

Platform에서 모델 로드:

# 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#