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 리소스를 중심으로 구성됩니다:

인증#

대부분의 엔드포인트에는 API 키가 필요합니다. 공개 데이터셋, 프로젝트 또는 모델 읽기, 공개 데이터셋 이미지 목록 조회, 공개 모델을 통한 추론 실행, 탐색 검색 등 공개 콘텐츠를 제공하는 엔드포인트는 익명 요청도 허용하며, API 키를 제공하면 더 많은 결과를 반환합니다.

API 키 발급#

1. Settings > API Keys로 이동합니다
2. Add Key을 클릭하고, 공급자로 Ultralytics을 유지한 채 이름을 입력한 다음 Create Key를 클릭합니다
3. 생성된 키를 복사합니다

자세한 안내는 API 키를 참조하세요.

인증 헤더#

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}, {agentId}는 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, wait 12s",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

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

전용 엔드포인트를 호출할 때 배포의 자체 serviceUrl(예: https://predict-abc123.run.app/predict)을 직접 사용하면 Platform API 키 속도 제한이 적용되지 않습니다. 이 경우 처리량은 배포된 서비스 구성에 따라 달라집니다.

응답 형식#

성공 응답#

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

{
    "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 객체를 포함한 전체 데이터셋 객체를 반환합니다. 이미지 10,000개 이상을 가져오는 작업이 진행되는 동안 편집기에는 stage, percent, 그리고 알려진 경우 processed, total, objects(스캔된 클라우드 객체)이 포함된 processingProgress도 반환됩니다.

데이터셋 생성#

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 슬러그(휴지통에 있는 항목 포함)를 사용하면 409이 반환됩니다.

응답(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, blurFaces, kptSkeletonId(포즈 데이터셋에 포즈 스켈레톤 템플릿 할당), initializeClassNames(데이터셋에 클래스 또는 주석이 아직 없는 경우를 제외하고 업데이트 시 409 반환). 사용자 지정 메타데이터를 지우려면 빈 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을 반환합니다.

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

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 다운로드를 준비하지 않고 버전을 저장하려면 download을 false로 설정합니다. 그러면 downloadUrl는 생략됩니다. SDK는 ultralytics-platform>=0.1.73에서 download을 수락합니다.

본문(선택 사항):

{
    "description": "Added 500 training images",
    "download": true
}

응답:

{
    "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}/versions/compare?base={from}&head={to}

Python SDK: client.datasets.compare(owner, dataset, base=1, head=2)(ultralytics-platform>=0.1.73)

응답(요약):

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summary은 첫 페이지에만 표시되며 정확한 총계와 함께 추가, 제거 또는 이름이 변경된 클래스 및 차이가 있는 기타 데이터셋 필드를 나열하는 header을 포함합니다. 각 항목의 change는 added, removed, modified(변경된 fields 포함) 또는 moved(분할 변경)이며, labelsRemoved에는 제거된 이미지의 라벨이 포함됩니다. 다음 페이지에 nextCursor가 있으면 이를 cursor으로 전달합니다. hash을 사용하면 응답은 versions가 됩니다. 즉, 각 버전에 저장된 이미지와 해당 라벨 및 서명된 imageUrl이 반환됩니다. 어느 순서든 사용할 수 있으며, base와 head를 서로 바꾸면 제거된 이미지가 추가된 이미지로 보고됩니다. 비교에는 기본 속도 제한이 적용되며, hash이 없는 요청은 어떤 API 키를 사용하든 사용자 및 데이터셋별로 분당 10회로 제한됩니다.

데이터셋 통계 가져오기#

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, cluster, split, classIds, width, height, bytes, labelCount, labeled, missing이 포함됩니다. cluster는 크기순으로 순위가 매겨진 포인트의 시각적 아일랜드입니다(0 = 가장 큼, -1 = 분산됨). 클러스터링 기능이 추가되기 전에 분석된 레이아웃에서는 null이 반환됩니다.

데이터셋에서 학습된 모델 목록#

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",
            "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}/images/adopt

Python SDK: client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) (ultralytics-platform>=0.1.50)

앱의 복사 및 붙여넣기 기능처럼 다른 데이터셋에서 최대 1,000개의 이미지를 이 데이터셋으로 복사하고, 개수 adopted을 반환합니다.

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

release 또는 classMapping을 설정하면 편집할 수 있는 데이터셋의 레이블과 분할이 유지됩니다. release: false는 이미지를 복사하고 release: true은 이미지를 소스 데이터셋에서 이동합니다. 두 필드를 모두 생략하면 레이블이 없는 train 이미지를 가져옵니다. 읽기 전용 소스에서 복사하는 경우에도 동일하게 처리됩니다. 읽기 전용 소스에서 이동하면 403가 반환됩니다. 기존 이미지는 건너뜁니다. 레이블과 분할을 유지하는 경우 중복 여부는 대상 분할 내에서 확인합니다. 클래스는 이름을 기준으로 일치 여부를 확인하며, 두 글자를 초과하는 이름은 대소문자를 무시합니다. 422은 unmatchedClasses에서 일치 항목이 없는 소스 클래스를 반환하고, classMapping은 각 클래스를 클래스 인덱스, 새 클래스 이름 또는 레이블을 제외하는 null에 매핑합니다. 409은 대상이 연결된 데이터셋이거나 소스 또는 대상이 사용 중임을 의미합니다. 레이블과 분할을 유지하는 경우 작업, 이미지 채널, 포즈 설정 또는 깊이 스케일이 호환되지 않으면 레이블이 없는 이미지에도 409이 반환됩니다.

데이터셋 데이터 수집#

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

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

headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, 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=...)

이미지에 모델을 실행하고 예측된 어노테이션을 반환합니다. 결과는 저장되지 않습니다. 결과가 적절하다고 판단되면 PATCH /api/images/{imageId}을 사용해 저장하세요.

응답: success, predictions(어노테이션 객체), confidences(인덱스에 맞춰 정렬된 점수이며, 클래스 프롬프트 모델에서는 비어 있음), modelUsed, inferenceTime, 클래스 프롬프트 모델의 경우 partial(생성형 모델의 잘린 출력에서 완전한 박스만 반환된 경우 true), 유료 제공업체 모델의 경우 선택적으로 cost(제공업체 키로 청구되는 예상 제공업체 비용(USD)이며, 추정할 수 없는 경우 생략됨)을 반환합니다. 클래스가 데이터셋과 일치하지 않는 YOLO 모델, 검출 데이터셋이 아니거나 클래스 수가 1~200개 범위를 벗어나는 데이터셋에서 사용하는 클래스 프롬프트 모델, 데이터셋 작업 공간의 설정 > API 키에 제공업체 키를 저장하지 않은 유료 제공업체 모델은 422을 반환합니다(code: missing_provider_api_key). 제공업체 오류에는 제공업체의 메시지가 포함됩니다. 제공업체가 400, 401, 403 또는 404(거부된 키, 모델 또는 요청)로 응답하면 422, 요청 제한에 도달하면 429, 그 밖의 제공업체 오류에는 503이 반환됩니다. 깊이 데이터셋은 400을 반환하며, 연결된 스토리지에 있거나 이미지 채널이 3개를 초과하는 데이터셋은 409를 반환합니다.

유사 이미지 찾기#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

공개 데이터셋과 사용자의 개인 및 팀 데이터셋에서 시각적으로 유사한 images을 최대 24개 반환합니다. 각 이미지에는 score(0~1), 서명된 thumbnailUrl, 원본 dataset(owner, dataset, license)이 포함됩니다. 원본 데이터셋에 이미 있는 이미지와 쿼리 이미지의 복사본은 제외됩니다. 이미지에 대한 보기 권한이 있는 API 키가 필요합니다. 아직 임베딩되지 않은 이미지는 먼저 임베딩하며, 503은 준비에 실패했음을 의미하므로 다시 시도하세요.

데이터셋 자동 어노테이션#

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

Python SDK: client.datasets.create_batch(owner, dataset, body={...})(ultralytics-platform>=0.1.57)

데이터셋 버전을 저장한 다음, 모델을 사용해 데이터셋의 라벨이 없는 이미지에 라벨을 지정하는 실행을 대기열에 추가하고 202을 반환합니다. 요청 본문은 단일 이미지 엔드포인트와 동일한 modelId, confidence, iou, classMapping 필드와, 이미 라벨이 있는 이미지에도 어노테이션을 추가하는 includeAnnotated(기본값 false)를 사용합니다. 클래스 프롬프트 모델은 신뢰도 점수 없이 데이터셋 클래스를 검출합니다. 유료 제공업체 모델을 사용하려면 실행이 승인되기 전에 데이터셋 작업 공간의 설정 > API 키에 제공업체 키를 저장해야 합니다(422, code: missing_provider_api_key). 기존 라벨은 변경되지 않으며, 실제로 처리한 이미지에 대해 실행 비용이 청구됩니다. 402은 잔액으로 예상 비용을 충당할 수 없음을 의미하고, 409은 데이터셋을 사용할 준비가 되지 않았거나, 어노테이션할 이미지가 남아 있지 않거나, 이미 실행 중인 작업이 있음을 의미합니다. 422는 데이터셋에 클래스가 없거나 클래스 프롬프트 모델에 검출 데이터셋이 아닌 데이터셋 또는 클래스 수가 1~200개 범위를 벗어나는 데이터셋이 지정되었음을 의미합니다. 이 엔드포인트를 호출하기 전에 클래스 엔드포인트를 사용해 클래스를 생성하세요. 앱은 실행을 시작하기 전에 Map classes 단계에서 이 작업을 수행합니다.

동일한 경로에서 GET (client.datasets.batch(owner, dataset))을 호출하면 진행 중인 실행과 진행 상황을 반환하거나, 마지막으로 완료된 실행을 닫힐 때까지 반환하며, 생성형 모델의 실행에서 잘린 출력 중 완전한 박스만 유지된 경우 해당 실행의 results에는 partialImages이 포함됩니다; DELETE (client.datasets.delete_batch(owner, dataset))는 진행 중인 실행을 취소하거나 청구를 정산하고 완료된 요약을 닫습니다.

동일한 엔드포인트는 "operation": "blur", confidence(기본값 0.25) 및 boxScale(0.5~1.5, 기본값 1)를 사용해 얼굴을 흐리게 처리합니다. imageId은 실행을 이미지 하나로 제한합니다. 버전을 생성하지 않으며 라벨도 변경하지 않습니다. "preview": true를 보내면 변경 없이 최대 6개 이미지에 처리한 다음, 반환된 jobId을 동일한 설정과 함께 previewJobId로 보내 적용할 수 있습니다. 이미 적용된 미리 보기는 재사용할 수 없으며 409를 반환합니다. 미리 보기가 대기 중일 때 해당 ID를 previewJobId으로 전달해 DELETE를 호출하면 미리 보기를 폐기합니다.

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

이미지 일괄 이동#

PATCH /api/images/bulk

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

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

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

파일 이름 또는 콘텐츠 충돌이 발생하면 바스켓 전체에 적용할 skip, keep_both 또는 replace 중 하나를 conflictPolicy로 선택할 때까지 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"]
}

응답: urls, thumbnails, depths(쌍을 이루는 깊이 이미지의 깊이 타깃 미리 보기)를 반환하며, 모두 이미지 ID를 키로 사용합니다.

프로젝트 API#

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

프로젝트 목록#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

쿼리 매개변수:

프로젝트 가져오기#

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

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

project 객체, 모델별 요약(status, metrics, epochs, weights, train args) 배열인 models, isOwner를 반환합니다. 모델 이름 또는 메타데이터로 models를 필터링하려면 search(최대 200자)을 전달하세요.

프로젝트 만들기#

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.

워크스페이스에 이미 존재하는 project 슬러그(휴지통에 있는 항목 포함)를 사용하면 409이 반환됩니다.

프로젝트 업데이트#

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을 반환하며, 해당 모델을 사용하는 배포를 영구 삭제합니다. 프로젝트를 복원해도 배포는 복원되지 않습니다. 502는 배포 정리가 완료되지 않았음을 의미합니다. 정리가 완료될 때까지 모델은 휴지통에 유지됩니다.

프로젝트 복제#

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)

쿼리 매개변수:

기본 응답에는 상태, 태스크, 지표, trainArgs, trainResults, classNames, computeCost, metadata 등이 포함된 model 객체와 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=..."
        }
    ]
}

최악의 검증 이미지와 유사한 이미지 찾기#

GET /api/models/{owner}/{project}/{model}/similar-images

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

최대 100개의 images을 반환합니다. 형식은 유사한 이미지 찾기와 같으며, 이 학습 실행에서 점수가 가장 낮았던 검증 이미지와 유사하되 학습 데이터셋에 이미 포함된 이미지는 제외합니다. 해당 최악 이미지 중 일부를 기준으로 검색하려면 hashes(쉼표로 구분, 최대 100개)를 전달합니다. 모델 워크스페이스에 액세스할 수 있는 API 키가 필요합니다. 실행에서 이미지별 결과를 기록하지 않은 경우 목록은 비어 있으며, 404은 최악의 이미지가 아직 임베딩되지 않았다는 의미이기도 합니다. 먼저 학습 데이터셋에서 데이터셋 임베딩을 실행하세요.

모델 복제#

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 페이로드가 포함됩니다(깊이 값은 pixel × max / divisor이며 기본 8비트 맵에서는 제수 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,
        "classNames": ["person", "forklift"],
        "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 학습을 시작하고 진행 상황을 실시간으로 모니터링합니다. 자세한 내용은 클라우드 학습 문서를 참조하세요.

GPU 가용성 조회#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

GPU ID를 기준으로 현재 재고 상태를 반환합니다. 공개 API이며 인증이 필요하지 않습니다. 관리형 학습 용량을 포함하려면 managed=true을 전달해야 하며, 이 경우 API 키가 필요합니다.

학습 시작#

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

각 형식은 아래 내보내기 표의 인수 열에 지정된 옵션만 지원합니다. 해당 옵션을 지원하지 않는 형식에 기본값이 아닌 batch, dynamic, opset, simplify, workspace 또는 optimize 값을 지정하면 400이 반환됩니다. imx 내보내기는 INT8만 지원하며 detect, segment, classify 및 pose 모델에서 사용할 수 있습니다. YOLO26 모델과 나노 이외의 YOLOv8 또는 YOLO11 크기는 400을 반환합니다.

응답(201): id, format, status(queued 또는 running), region, 그리고 TensorRT 내보내기의 경우 gpuType입니다. 동일한 내보내기가 이미 진행 중이면 409을 반환합니다.

지원되는 형식:

아래 공통 내보내기 표의 format 인수를 사용합니다. PyTorch는 소스 형식이며 API 내보내기 대상이 아닙니다.

nms=None은 외부 NMS를 위한 원시 출력을 기본값으로 사용합니다. 사용 가능한 NMS-free head를 선택하려면 nms=False을 설정합니다. 지원되지 않는 형식은 해당 형식의 기본 출력 경로로 대체됩니다. 위의 nms 항목은 nms=True을 사용해 NMS를 포함할 수 있는 형식을 나타냅니다.

내보내기 상태 조회#

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

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

status, format, args, gpuType(TensorRT만 해당), 타임스탬프와 export 객체를 반환합니다. 완료되면 size, downloadUrl, downloadFilename이 포함된 file 객체도 반환합니다.

내보내기 취소 또는 삭제#

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

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

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

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

배포 API#

상태 점검 및 모니터링 기능을 갖춘 전용 추론 엔드포인트에 모델을 배포합니다. 자세한 내용은 엔드포인트 문서를 참조하세요.

배포 목록 조회#

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)

deployment 객체를 반환하며, 여기에는 status, statusMessage, region, serviceUrl, resources, 사용자 지정 metadata이 포함됩니다. 소유자의 경우 camera과 cameraApplying도 포함됩니다.

배포 업데이트#

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

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

다음 본문 중 하나를 전송합니다:

{ "name": "Edge 1 (primary)" }

이름을 변경하면 URL의 deployment 값이 새 이름을 슬러그로 변환한 값으로 설정되고, 이 값은 deployment로 반환됩니다. 이전 경로는 404를 반환하며 serviceUrl은 변경되지 않습니다. 비어 있는 metadata 객체는 사용자 지정 메타데이터를 지웁니다. 교체 작업은 배포 ID, 리전, 엔드포인트 URL을 유지하면서 새 리비전을 배포합니다. 배포에 실패하면 기존 리비전이 계속 실행됩니다. 교체 모델은 키로 액세스할 수 있는 가중치가 포함된 완료된 모델이어야 합니다. 카메라 작업은 RTSP 또는 RTSPS 카메라를 저장하며, 준비된 사용자 지정 리소스 엔드포인트에서 해당 카메라의 추론을 계속 실행합니다(백그라운드 카메라 참조). "url": null을 사용하거나 크기를 기본값으로 조정하면 카메라가 제거됩니다. 기본 크기 엔드포인트에 카메라를 저장하면 403이 반환됩니다. 카메라 변경을 적용하는 동안에는 202이 status ready과 함께 반환됩니다. cameraApplying이 더 이상 true가 아닐 때까지 배포 상태를 폴링한 다음 camera을 확인하세요. 변경에 실패하면 이전 카메라가 유지되고 statusMessage가 설정됩니다. 작업이 완료되면 200가 status ready 또는 stopped과 함께 반환됩니다. 다른 작업이 계속 배포 중이면 202가 deploying 또는 stopping과 함께 반환됩니다.

배포 삭제#

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

이미지 또는 비디오를 전용 엔드포인트로 전달합니다. 요청 및 응답 규약은 모델 추론과 일치합니다. 카메라 스트림은 프록시되지 않습니다. 실시간 카메라 추론에 설명된 대로 엔드포인트 URL로 보내세요.

멀티파트 양식:

메트릭 가져오기#

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

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

쿼리 매개변수:

전체 응답에는 summary(요청 총계, 오류율, 평균 및 p50/p95/p99 지연 시간)과 timeSeries(요청, 오류, 지연 시간, CPU, 메모리, 인스턴스 수)이 포함됩니다. 스파크라인 응답은 requests24h(시간별 요청 수, 요청이 없는 시간은 생략), totalRequests, errorRate, avgLatencyMs(시간별 P95 지연 시간의 평균)를 반환합니다. view=overview을 사용하면 summary에는 totalRequests, errorRate, p95LatencyMs이 포함되고, timeSeries에는 requests, errors, latencyP95가 포함됩니다.

로그 가져오기#

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

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

쿼리 매개변수:

에이전트 API#

에이전트 워크플로를 저장하고 관리합니다. API는 에이전트 정의를 저장하며, 실행은 Agents 캔버스에서 시작합니다. 여기서 https://platform.ultralytics.com/agents?workflow={id}을 선택하면 저장된 에이전트가 열립니다. Python SDK 메서드에는 ultralytics-platform>=0.1.74가 필요합니다.

모든 작업은 선택 사항인 owner 쿼리 매개변수를 지원하며, 이 매개변수에는 소속된 워크스페이스의 사용자 이름을 지정합니다(기본값: 본인). 목록 조회에는 뷰어 액세스 권한이 필요하며, 저장 및 삭제에는 편집자 액세스 권한이 필요합니다.

에이전트 목록 조회#

GET /api/workflows

Python SDK: client.agents.list()

응답은 workflows에 최대 100개의 에이전트를 나열하며, 최근에 업데이트된 항목부터 표시합니다. 각 에이전트에는 id, username, name, version, createdAt, updatedAt이 포함됩니다. id을 요청하면 에이전트의 graph도 반환됩니다.

에이전트 저장#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

에이전트를 생성하려면 version: 0을 전송합니다. 에이전트를 업데이트하려면 해당 에이전트의 id과 마지막 목록 조회 또는 저장 시 반환된 version를 전송합니다. 오래된 version은 409를 반환하므로 에이전트 목록을 다시 조회한 후 재시도하세요. 연결이 순환을 이루거나 블록에 입력이 두 개 이상 연결된 그래프는 400를 반환합니다.

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

응답은 에이전트 id, 새 version, 그리고 errors를 반환하며, 캔버스에서 경고로 표시할 블록의 예로는 데이터 세트가 선택되지 않은 데이터 세트 블록이 있습니다. 어느 경우든 에이전트는 저장됩니다. 모든 블록 유형과 해당 구성에 대해서는 openapi.json를 참조하세요.

에이전트 삭제#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

에이전트를 삭제하고 활성 실행을 취소합니다. 삭제된 에이전트는 휴지통에 표시되지 않으며 복원할 수 없습니다.

휴지통 API#

소프트 삭제된 프로젝트, 데이터셋, 모델을 확인하고 복원하거나 영구적으로 삭제합니다. 항목은 30일 후 자동으로 완전히 삭제됩니다. 휴지통 문서를 참조하세요.

휴지통 목록 조회#

GET /api/trash

Python SDK: client.lifecycle.trash()

쿼리 매개변수:

응답에는 items(각 항목에 daysRemaining 포함), total, page, limit, totalPages, 유형별 총계가 포함된 summary이 포함됩니다. id을 사용하면 대신 resources이 반환되며, 여기에는 영향을 받는 모델과 영구적으로 삭제될 배포가 포함됩니다.

항목 복원#

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

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

업로드 완료#

POST /api/upload/complete

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

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

응답: success과 size 및 contentType이 포함된 file 객체입니다. 모델의 경우 가중치가 연결되며, 데이터셋 아카이브의 경우 처리를 시작하려면 다음 단계로 수집을 호출하세요.

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

스토리지 통합 API#

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

스토리지를 검색하고 연결하려면 워크스페이스 관리자 액세스 권한과 Pro 또는 Enterprise 플랜이 필요합니다(그렇지 않으면 403). 통합 목록 조회와 객체 탐색에는 편집자 액세스 권한이 필요합니다.

통합 목록 조회#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

integrations을 반환하며, 각 항목에는 id, provider, credentialIdentity, targets, createdAt가 포함됩니다. 자격 증명은 반환되지 않습니다.

위치 검색#

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

검색과 동일한 자격 증명 형식을 사용하며, 필수 targets 배열에는 버킷 또는 컨테이너 이름을 1~50개 지정합니다. 저장된 통합을 포함하는 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, 이미 가져온 항목(skippedCount), 버전이 없는 프로젝트, 지원되지 않는 프로젝트와 확인되지 않은 프로젝트의 수, bytesTotal, 사용 가능한 storage 용량이 포함됩니다. Roboflow API 키는 본문에서 읽으며 저장하지 않습니다.

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Roboflow에서 가져오기#

POST /api/integrations/roboflow/import

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

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

{
    "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": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "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"
}

usage은 projects, datasets, models, images, annotations, deployments의 개수와 storage의 바이트 수를 보고합니다. limit이 -1이면 제한이 없음을 의미하며, percent은 제한 대비 정수 백분율입니다.

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

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

Explore API#

커뮤니티가 공유한 공개 프로젝트와 데이터셋을 검색하거나 이미지에 표시된 내용을 기준으로 이미지를 검색하세요. Explore 문서를 참조하세요.

공개 콘텐츠 검색#

GET /api/explore/search

Python SDK: client.explore.search()

쿼리 매개변수:

응답: projects, datasets, hasMore. type=images은 일치 항목을 images에 대신 반환하며, 가장 일치하는 항목부터 정렬됩니다. 각 항목에는 소스 dataset와 0~1 범위의 유사도 score이 포함됩니다. 이 기능에는 q이 필요하며, 공개 데이터셋을 검색합니다. API 키를 보내면 본인 및 팀의 데이터셋도 검색합니다.

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:  # ULTRALYTICS_API_KEY 또는 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 코드에 동일한 리소스 트리를 제공하며, 응답이 성공하지 않으면 APIError과 함께 status_code, body 및 파싱된 json을 발생시키고, 연결 실패 시 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을 요청하므로 직접 호출할 필요가 없습니다.

설치 및 설정#

Platform 통합에는 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")

# Platform 데이터셋으로 학습
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

URI 형식:

Platform에 푸시#

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

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# 결과가 Platform에 자동으로 동기화됩니다.
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

동기화 항목:

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

API 예제#

Platform에서 모델 로드:

# 사용자 모델
model = YOLO("ul://username/project/model-name")

# 공식 모델
model = YOLO("ul://ultralytics/yolo26/yolo26n")

추론 실행:

results = model("image.jpg")

# 결과에 접근
for r in results:
    boxes = r.boxes  # 검출 박스
    masks = r.masks  # 세그멘테이션 마스크
    keypoints = r.keypoints  # 포즈 키포인트
    probs = r.probs  # 분류 확률

모델 내보내기:

# ONNX로 내보내기
model.export(format="onnx", imgsz=640, quantize=16)

# TensorRT로 내보내기
model.export(format="engine", imgsz=640, quantize=16)

# CoreML로 내보내기
model.export(format="coreml", imgsz=640)  # 분류에는 imgsz=224 사용

검증:

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

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

자주 묻는 질문#