YOLO Vision 2026:

REST API 레퍼런스#

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

Ultralytics Platform Interactive API Documentation

빠른 시작
# List your datasets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets
대화형 API 문서

Ultralytics Platform API docs에서 전체 대화형 API 레퍼런스를 살펴보세요.

API 개요#

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

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
리소스설명주요 작업
Datasets레이블이 지정된 이미지 컬렉션CRUD, 이미지, 레이블, 내보내기, 버전, 복제
Projects학습 워크스페이스CRUD, 복제, 아이콘
Models학습된 체크포인트CRUD, 예측, 다운로드, 복제, 내보내기
Deployments전용 추론 엔드포인트CRUD, 시작/중지, 메트릭, 로그, 상태
Exports형식 변환 작업생성, 상태, 다운로드
Training클라우드 GPU 학습 작업시작, 상태, 취소
Billing크레딧 및 사용량잔액, 사용량, 거래 내역
Teams워크스페이스 협업워크스페이스, 멤버, 역할

인증#

리소스 API는 데이터셋 클래스 및 분할 관리, 복제, 학습, 내보내기, 배포, 지원되는 계정 읽기 등을 포함하여 API 키 인증을 사용합니다. 공용 엔드포인트는 명시된 경우 익명 액세스를 지원합니다. 브라우저 전용 애플리케이션 경로는 제외됩니다.

API 키 가져오기#

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

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

인증 헤더#

모든 요청에 API 키를 포함하십시오:

Authorization: Bearer YOUR_API_KEY
API 키 형식

API 키는 ul_ 형식 뒤에 40자의 1진수 문자가 붙는 형태를 사용합니다. 키를 비밀로 유지하고 -- 버전 제어 시스템에 커밋하거나 공개적으로 공유하지 마세요.

예시#

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

기본 URL#

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

https://platform.ultralytics.com/api

속도 제한(Rate Limits)#

API는 API 키당 Upstash Redis 기반의 슬라이딩 윈도우 제한을 적용합니다. 각 라우트는 아래의 해당 카테고리를 사용합니다.

요청 제한(throttled)에 도달하면 API는 재시도 메타데이터와 함께 429을(를) 반환합니다:

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

API 키별 제한#

속도 제한은 호출되는 엔드포인트에 따라 자동으로 적용됩니다. 비용이 많이 드는 작업은 남용 방지를 위해 더 엄격한 제한이 적용되며, 표준 CRUD 작업은 다음과 같은 관대한 기본값을 공유합니다:

카테고리제한적용 대상
기본값분당 100회 요청아래 카테고리에 할당되지 않은 라우트
학습분당 10회 요청클라우드 학습 시작
업로드분당 10회 요청서명된 업로드 URL, 업로드 완료 및 데이터셋 인게스트
예측분당 20회 요청Platform API 라우트를 통한 모델 및 배포 추론
내보내기분당 20회 요청모델 내보내기 라우트 및 데이터셋 내보내기/버전 라우트
다운로드분당 30회 요청모델 파일 다운로드
Mutation (변경)분당 10회 요청팀 생성, 스토리지 통합 변경, API 키, 멤버, 초대, 배포 시작/중지
결제5 requests/min (분당 5회 요청)자동 충전 및 구독 결제 라우트
Hydrate (하이드레이트)분당 20회 요청선택한 데이터셋 이미지 세트 하이드레이션
Clustering (클러스터링)분당 10회 요청데이터셋 이미지 클러스터링

각 범주는 API 키당 독립적인 카운터를 가집니다. 예를 들어, 20회의 예측 요청을 수행해도 분당 100회 요청인 기본 허용량에는 영향을 주지 않습니다.

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

Dedicated endpoints는 엔드포인트 URL을 직접 호출할 때 Platform API-key rate limits의 적용을 받지 않습니다 (예: https://predict-abc123.run.app/predict). 처리량은 배포된 서비스 구성에 따라 달라집니다.

속도 제한 처리

429 상태 코드를 수신한 경우, 재시도하기 전에 Retry-After(또는 X-RateLimit-Reset까지) 동안 기다리세요. 지수 백오프 구현에 대해서는 rate limit FAQ를 참조하세요.

응답 형식#

성공 응답#

응답은 리소스별 필드를 포함하는 JSON을 반환합니다:

{
    "datasets": [...],
    "total": 100
}

오류 응답#

{
    "error": "Dataset not found"
}
HTTP 상태의미
200성공
201생성됨
400잘못된 요청
401인증 필요
403권한 부족
404리소스 찾을 수 없음
409충돌 (중복)
429요청 한도 초과
500서버 오류

데이터셋 API#

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

데이터셋 목록 조회#

GET /api/datasets

쿼리 매개변수:

파라미터유형설명
username문자열(string)사용자 이름으로 필터링
limit정수(int)페이지당 항목 수 (기본값: 1000, 최대값: 1000)
owner문자열(string)워크스페이스 소유자 사용자 이름
includeImageUrls부울(boolean)서명된 전체 크기 샘플 이미지 URL 포함(기본값: false)
includeSamples부울(boolean)샘플 이미지를 생략하고 응답 크기를 줄이려면 false을(를) 설정하세요.
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

응답:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

데이터셋 가져오기#

GET /api/datasets/{datasetId}

클래스 이름, 분할 수 및 기타 플랫폼 관리 속성을 포함한 데이터셋 세부 정보를 반환합니다. 사용자 정의 메타데이터는 아래의 메타데이터 엔드포인트에서 별도로 로드됩니다.

{datasetId}이 ID가 아닌 데이터셋 슬러그인 경우 username을 전달합니다.

데이터셋 생성#

POST /api/datasets

본문:

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "metadata": { "location": "factory-1", "reviewed": true },
    "visibility": "private",
    "classNames": ["person", "car"]
}
지원되는 작업

유효한 task 값: detect, segment, semantic, classify, pose, obb.

응답:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

데이터셋 업데이트#

PATCH /api/datasets/{datasetId}

본문 (부분 업데이트):

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

사용자 정의 메타데이터를 지우려면 빈 metadata 객체({})를 전송하세요. 직렬화된 메타데이터 객체는 500,000자로 제한되며, 각 최상위 키는 128자로 제한됩니다.

데이터셋 메타데이터 가져오기#

GET /api/datasets/{datasetId}/metadata

사용자 정의 메타데이터 객체와 Ultralytics가 관리하는 읽기 전용 필드/값 쌍의 선별된 세트를 반환합니다. 사용자 정의 메타데이터는 일반 데이터셋 페이로드에서 의도적으로 생략됩니다. 인증 및 데이터셋 워크스페이스 액세스 권한이 필요합니다.

데이터셋 아이콘#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

최대 5 MB 크기의 WebP 아이콘을 멀티파트 폼 필드 image(으)로 업로드하거나 현재 아이콘을 제거합니다.

데이터셋 삭제#

DELETE /api/datasets/{datasetId}

데이터셋을 소프트 삭제합니다(trash(으)로 이동되며, 30일 동안 복구 가능).

데이터셋 복제#

POST /api/datasets/{datasetId}/clone

모든 이미지와 라벨을 포함하여 공개, 소유 또는 편집 가능한 워크스페이스 데이터셋의 복사본을 생성합니다.

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

{
    "name": "cloned-dataset",
    "slug": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "license": "AGPL-3.0",
    "owner": "team-username"
}

데이터셋 내보내기#

GET /api/datasets/{datasetId}/export

최신 데이터셋 내보내기에 대한 서명된 다운로드 URL이 포함된 JSON 응답을 반환합니다.

쿼리 매개변수:

파라미터유형설명
v정수버전 번호 (1부터 시작하는 인덱스). 생략 시 가장 최근의 수정 가능한 내보내기를 반환하며, 데이터셋에 변경 사항이 없는 경우 이를 재사용합니다.

응답:

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

데이터셋 버전 생성#

POST /api/datasets/{datasetId}/export

데이터셋의 새로운 번호가 매겨진 버전 스냅샷을 생성합니다. 이는 Editor 권한 이상이 필요합니다. 버전은 현재 이미지 수, 클래스 수, 주석 수, 분할 분포를 캡처한 다음 변경 불가능한 NDJSON 내보내기를 생성하고 저장합니다.

요청 본문:

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

모든 필드는 선택 사항입니다. description 필드는 사용자가 지정한 버전 레이블입니다.

응답:

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

버전 설명 업데이트#

PATCH /api/datasets/{datasetId}/export

기존 버전의 설명을 업데이트합니다. 이는 Editor 권한 이상이 필요합니다.

요청 본문:

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

응답:

{
    "ok": true
}

데이터셋 버전 복원#

POST /api/datasets/{datasetId}/restore

이미지 바이트를 복사하지 않고 저장된 버전에서 데이터셋의 이미지, 주석 및 클래스를 재구성합니다.

{
    "version": 2
}

클래스 통계 가져오기#

GET /api/datasets/{datasetId}/class-stats

클래스 분포, 위치 히트맵 및 차원 통계를 반환합니다. 결과는 최대 5분까지 캐시됩니다.

응답:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "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", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

클래스 관리#

클래스 병합(소스 클래스에서 대상 클래스로 어노테이션을 재할당한 후 소스 클래스 삭제):

POST /api/datasets/{datasetId}/classes/merge
{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

클래스 ID는 위치 기반이므로 병합은 멱등하지 않습니다. 재시도하기 전에 데이터셋을 다시 가져오십시오.

클래스 삭제:

POST /api/datasets/{datasetId}/classes/delete
{
    "classIds": [2, 4]
}

데이터 분할 재배포#

POST /api/datasets/{datasetId}/splits/redistribute

학습, 검증 및 테스트 분할 전반에 걸쳐 이미지를 무작위로 재할당합니다. 백분율의 합은 100이 되어야 합니다.

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

데이터셋 임베딩#

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GET은 현재 UMAP 분석 요약 및 활성 작업 상태를 반환합니다. POST는 임베딩 분석 작업을 대기열에 추가하며, DELETE는 활성 작업을 취소합니다.

이미지 클러스터링#

GET /api/datasets/{datasetId}/images/clustering

클러스터링 산점도 뷰를 위한 UMAP 2D 레이아웃 및 이미지별 메타데이터를 반환합니다(페이징 및 속도 제한 적용).

데이터셋으로 학습된 모델 가져오기#

GET /api/datasets/{datasetId}/models

이 데이터셋을 사용하여 학습된 모델들을 반환합니다.

응답:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

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

POST /api/datasets/{datasetId}/predict

데이터셋 이미지에서 YOLO 추론을 실행하여 어노테이션을 자동 생성합니다. 선택한 모델을 사용하여 라벨이 지정되지 않은 이미지의 라벨을 예측합니다.

본문:

필드유형필수설명
imageHash문자열(string)예어노테이션할 이미지의 해시
modelId문자열(string)아니요ul:// URI(예: ul://username/project/model) 형식으로 추론에 사용할 모델을 지정합니다. 생략할 경우 데이터셋의 작업별 기본 모델이 사용됩니다.
confidence부동 소수점(float)아니요신뢰도 임계값 (기본값: 0.25)
iou부동 소수점(float)아니요IoU 임계값 (기본값: 0.7)

데이터셋 수집(Ingest)#

POST /api/datasets/ingest

기존 데이터셋에 대한 데이터셋 수집(ingest) 작업을 생성합니다. 대상 데이터셋은 URL 경로가 아니라 JSON 본문에 항상 datasetId(으)로 전달됩니다.

요청 본문에는 datasetId과 함께 sessionId(업로드된 아카이브의 업로드 세션) 또는 sourceUrl(원격 ZIP, TAR, TAR.GZ, TGZ 또는 NDJSON URL) 중 정확히 하나가 필요합니다. 아카이브의 분할 구조를 재정의하려면 선택 사항인 targetSplit(train, val 또는 test)을 추가하십시오. 사용자 지정 메타데이터를 첨부하려면 각 이미지의 정확한 아카이브 상대 경로 또는 NDJSON file 값으로 키가 지정된 imageMetadata을 사용하십시오.

업로드된 아카이브의 경우, 업로드 세션은 POST /api/upload/signed-url에 전달된 assetId에 의해 이미 데이터셋에 바인딩되어 있습니다. 수집(ingest)은 assetId가 본문 datasetId과 일치하는지 검증합니다. 선택 사항인 classMapping 항목은 각 수신 클래스 이름을 기존의 0부터 시작하는 클래스 인덱스, 재사용하거나 생성할 클래스 이름, 또는 클래스를 건너뛰기 위한 null에 매핑합니다. 원격 sourceUrl 가져오기의 경우, 먼저 데이터셋을 생성한 다음 수집(ingest)에 해당 datasetId을 전달합니다.

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

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

본문(메타데이터가 포함된 단일 또는 다중 이미지):

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

로컬 이미지는 아카이브에 이미지가 하나이든 여러 개이든 상관없이 기존 아카이브 업로드 흐름을 사용합니다. 키는 폴더를 포함하여 아카이브 내의 정규화된 경로와 일치해야 합니다. NDJSON 가져오기의 경우, 각 이미지 레코드에 자체 metadata 객체가 대신 포함될 수 있습니다. 레코드 로컬 metadata은 일치하는 imageMetadata 항목보다 우선합니다.

메타데이터는 JSON이며 중첩된 값을 지원합니다. 아카이브 경로는 1,024자, 최상위 메타데이터 키는 128자, 각 메타데이터 객체는 직렬화된 문자 기준 500,000자로 제한됩니다. 전체 imageMetadata 맵 또는 NDJSON 가져오기 전반의 결합된 유효 메타데이터 역시 직렬화된 문자 기준 500,000자로 제한됩니다. 이러한 제약 조건은 인터랙티브 OpenAPI 스키마에 포함되어 있습니다.

Python을 사용하여 메타데이터와 함께 단일 이미지 업로드하기

동일한 코드로 이미지 그룹을 처리할 수 있습니다. ZIP에 파일을 더 추가하고 imageMetadata에 일치하는 항목을 추가하면 됩니다.

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
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/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

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

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

본문 (이후 ingest, 레이블 가져오기):

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}
클래스 매핑

첫 번째 수집(ingest)은 아카이브에서 클래스를 자동으로 생성합니다. 이후 수집 시 classMapping에서 생략된 아카이브 클래스는 먼저 기존 데이터셋 클래스와 대소문자를 구분하지 않는 일치 항목을 찾습니다. null에 명시적으로 매핑되었거나 일치하는 기존 클래스가 없는 클래스의 라벨만 건너뜁니다.

응답:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}
graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[Upload archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E[POST /api/datasets/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

데이터셋 이미지#

이미지 목록 조회#

GET /api/datasets/{datasetId}/images

쿼리 매개변수:

파라미터유형설명
split문자열(string)분할(split)별 필터링: train, val, test
offset정수(int)페이지 매김 오프셋 (기본값: 0)
limit정수(int)페이지당 항목 수 (기본값: 50, 최대값: 5000)
sort문자열(string)정렬 순서: newest, oldest, name-asc, name-desc, height-asc, height-desc, width-asc, width-desc, size-asc, size-desc, labels-asc, labels-desc(10만 개 이상의 이미지 데이터셋의 경우 일부 비활성화됨)
hasLabel문자열(string)라벨 상태별 필터링(true 또는 false)
hasError문자열(string)오류 상태별 필터링(true 또는 false)
search문자열(string)파일명, 사용자 정의 메타데이터 키, 스칼라 값 및 배열 항목에 대한 부분 문자열 일치(하위 객체 내부에 중첩된 값은 일치하지 않음); 32자리 1진수 문자열은 정확한 이미지 해시 조회입니다.
classIds문자열(string)쉼표로 구분된 클래스 ID이며, 지정된 클래스 중 하나라도 포함하는 이미지를 반환합니다.
includeThumbnails문자열(string)서명된 썸네일 URL 포함(기본값: true)
includeImageUrls문자열(string)서명된 전체 이미지 URL 포함(기본값: false)

선택한 이미지 가져오기#

POST /api/datasets/{datasetId}/images

최대 1,000개의 제공된 이미지 ID에 대해 동일한 이미지 모양을 반환합니다. 목록 작업과 동일한 URL 및 라벨 쿼리 제어를 수락합니다.

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

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

POST /api/datasets/{datasetId}/images/urls

이미지 해시 배치에 대한 서명된 URL을 가져옵니다 (브라우저 표시용).

이미지 삭제#

DELETE /api/datasets/{datasetId}/images/{hash}

이미지 라벨 가져오기#

GET /api/datasets/{datasetId}/images/{hash}/labels

특정 이미지에 대한 어노테이션과 클래스 이름을 반환합니다.

이미지 라벨 업데이트#

PUT /api/datasets/{datasetId}/images/{hash}/labels

본문:

{
    "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] }
    ]
}
좌표 형식

라벨 좌표는 0과 1 사이의 YOLO 정규화된 값을 사용합니다. 바운딩 박스는 [x_center, y_center, width, height]을(를) 사용합니다. 세분화(segmentation) 라벨은 다각형 꼭짓점의 평탄화된 목록인 segments인 [x1, y1, x2, y2, ...]을(를) 사용합니다.

대량 이미지 작업#

데이터셋 내에서 분할(train/val/test) 간 이미지 이동:

PATCH /api/datasets/{datasetId}/images/bulk

대량 이미지 삭제:

DELETE /api/datasets/{datasetId}/images/bulk

프로젝트 API#

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

프로젝트 목록 조회#

GET /api/projects

쿼리 매개변수:

파라미터유형설명
username문자열(string)사용자 이름으로 필터링
limit정수(int)페이지당 항목 수
owner문자열(string)워크스페이스 소유자 사용자 이름

프로젝트 가져오기#

GET /api/projects/{projectId}

프로젝트 생성#

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

프로젝트 업데이트#

PATCH /api/projects/{projectId}

본문 (부분 업데이트):

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

이를 지우려면 빈 metadata 객체({})를 전송하세요. 프로젝트 메타데이터는 데이터셋 메타데이터와 동일하게 128자의 최상위 키 및 500,000자의 직렬화된 객체 제한을 사용합니다.

프로젝트 메타데이터 가져오기#

GET /api/projects/{projectId}/metadata

사용자 정의 메타데이터 객체와 Ultralytics가 관리하는 읽기 전용 필드/값 쌍을 반환합니다. 인증 및 프로젝트 워크스페이스 액세스 권한이 필요합니다.

프로젝트 삭제#

DELETE /api/projects/{projectId}

프로젝트를 소프트 삭제합니다(trash(으)로 이동됨).

프로젝트 복제#

POST /api/projects/{projectId}/clone

공개, 소유 또는 편집 가능한 워크스페이스 프로젝트와 해당 모델을 계정 또는 워크스페이스로 복제합니다. 선택 사항인 JSON 본문은 name, slug, description, visibility, license 및 대상 owner 재정의를 허용합니다.

프로젝트 아이콘#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

최대 5 MB 크기의 WebP 아이콘을 멀티파트 폼 필드 image(으)로 업로드하거나 현재 아이콘을 제거합니다.

모델 API#

학습된 YOLO 모델 관리 — 메트릭 보기, 가중치 다운로드, 추론 실행 및 다른 형식으로 내보내기. Models documentation을(를) 참조하세요.

모델 목록 조회#

GET /api/models

쿼리 매개변수:

파라미터유형필수설명
projectId문자열(string)예프로젝트 ID (필수)
fields문자열(string)아니요필드 세트: summary, charts
ids문자열(string)아니요쉼표로 구분된 모델 ID
limit정수(int)아니요최대 결과 수 (기본값 20, 최대 100)

완료된 모델 목록 조회#

GET /api/models/completed

학습 및 배포에 사용할 수 있는 가중치를 가진 모든 프로젝트의 모델을 최대 1,000개까지 반환합니다. 워크스페이스용으로 owner을(를) 전달하세요.

모델 조회#

GET /api/models/{modelId}

모델 생성#

POST /api/models

JSON 본문:

필드유형필수설명
projectId문자열(string)예대상 프로젝트 ID
slug문자열(string)아니요URL 슬러그 (영문 소문자, 숫자/하이픈 조합)
name문자열(string)아니요표시 이름 (최대 100자)
description문자열(string)아니요모델 설명 (최대 1000자)
metadata객체아니요사용자 정의 JSON 메타데이터
task문자열(string)아니요작업 유형 (detect, segment, semantic, depth, pose, obb, classify)
모델 파일 업로드

.pt 가중치를 첨부하려면 assetType: models 및 이 모델의 ID를 assetId로 지정하여 서명된 업로드 URL을 요청하고, 파일을 업로드한 다음, 반환된 sessionId와 함께 POST /api/upload/complete을 호출합니다.

모델 업데이트#

PATCH /api/models/{modelId}

본문 (부분 업데이트):

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

이를 지우려면 빈 metadata 객체({})를 전송하세요. 모델 사용자 정의 메타데이터는 학습이 소유한 모델 정보, 환경 세부 정보 및 학습 인자와는 별개이며, 데이터셋 메타데이터와 동일한 직렬화된 객체 및 최상위 키 제한을 사용합니다.

모델 메타데이터 가져오기#

GET /api/models/{modelId}/metadata

사용자 정의 메타데이터 객체와 Ultralytics가 관리하는 읽기 전용 필드/값 쌍을 반환합니다. 인증 및 모델 워크스페이스 액세스 권한이 필요합니다.

모델 삭제#

DELETE /api/models/{modelId}

모델 파일 다운로드#

GET /api/models/{modelId}/files

모델 파일에 대한 서명된 다운로드 URL을 반환합니다.

모델 복제#

POST /api/models/{modelId}/clone

공개, 소유 또는 편집 가능한 워크스페이스 모델을 귀하의 프로젝트 중 하나로 복제하십시오.

본문:

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}
필드유형필수설명
targetProjectSlug문자열(string)예대상 프로젝트 슬러그
modelName문자열(string)아니요복제할 모델의 이름
description문자열(string)아니요모델 설명
owner문자열(string)아니요팀 사용자 이름 (워크스페이스 복제용)

다운로드 추적#

POST /api/models/{modelId}/track-download

모델 다운로드 분석을 추적합니다.

추론 실행#

POST /api/models/{modelId}/predict

공개 모델은 인증 없이 예측할 수 있습니다. 비공개 및 공유 모델은 상위 프로젝트에 액세스할 수 있는 API 키가 필요합니다.

멀티파트 폼:

파라미터유형기본값범위설명
file파일--이미지 또는 비디오 파일 (source이(가) 설정된 경우 제외 필수)
conf부동 소수점(float)0.250.01 – 1.0최소 신뢰도 임계값
iou부동 소수점(float)0.70.0 – 0.95NMS IoU 임계값
imgsz정수(int)64032 – 1280입력 이미지 크기 (픽셀 단위)
normalizeboolfalse-바운딩 박스 좌표를 0 – 1 범위로 반환
decimals정수(int)50 – 10좌표 값에 대한 소수점 정밀도
source문자열(string)--이미지 URL 또는 base64 문자열 (file의 대안)

file 또는 source 중 하나를 제공하세요. 최대 업로드 크기는 100 MB입니다.

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

응답:

응답에는 이미지별 shape, speed, results 및 선택적 조밀 픽셀 맵 데이터(시맨틱 클래스 맵, 또는 기본 8비트 맵의 경우 제수 255, bits=12|16 사용 시 65535인 깊이 맵 depth = pixel × max / divisor)와 함께 이미지 수, 함수 타이밍, 태스크 및 서비스 버전이 포함된 metadata가 포함됩니다. 내부 모델 경로는 절대 반환되지 않습니다.

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

학습 API#

클라우드 GPU(RTX 2000 Ada부터 B300까지 26가지 GPU 유형)에서 YOLO 학습을 시작하고 실시간으로 진행 상황을 모니터링하세요. Cloud Training documentation을(를) 참조하세요.

graph LR
    A[POST /training/start]:::start --> B[Job Created]:::proc
    B --> C{Training}:::decide
    C -->|progress| D[GET /models/id/training]:::proc
    C -->|cancel| E[DELETE /models/id/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

학습 시작#

POST /api/training/start
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "MODEL_ID",
    "projectId": "PROJECT_ID",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://username/datasets/my-dataset",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start
GPU 유형

사용 가능한 GPU 유형에는 rtx-4090, a100-80gb-pcie, a100-80gb-sxm, h100-sxm, rtx-pro-6000, b300 등이 포함됩니다. 가격이 포함된 전체 목록은 Cloud Training을(를) 참조하세요.

GPU 가용성 확인#

GET /api/training/gpu-availability

GPU 유형 ID를 키로 하는 현재 GPU 재고 상태(High, Medium, Low 또는 null)를 반환합니다. 공개, 인증 불필요; 5분 동안 캐시됩니다.

학습 상태 가져오기#

GET /api/models/{modelId}/training

현재 학습 작업 상태, 메트릭, 진행 상황, 타이밍, GPU 세부 정보 및 오류를 반환합니다. 공개 프로젝트는 인증 없이 액세스할 수 있으며, 비공개 및 공유 프로젝트는 액세스 권한이 있는 API 키가 필요합니다.

학습 취소#

DELETE /api/models/{modelId}/training

실행 중인 컴퓨팅 인스턴스를 종료하고 작업을 취소됨으로 표시합니다.

배포 API#

상태 확인 및 모니터링 기능이 포함된 전용 추론 엔드포인트에 모델을 배포합니다. 새 배포는 기본적으로 0으로 확장(scale-to-zero)을 사용하며, API는 선택 사항인 resources 객체를 허용합니다. Endpoints documentation을(를) 참조하세요.

경로별 API 키 지원

아래의 모든 배포 라우트는 API 키 인증을 허용합니다. 고처리량 추론을 위해 배포 고유의 엔드포인트 URL(예: https://predict-abc123.run.app/predict)을 API 키와 함께 직접 호출하세요. Dedicated endpoints은(는) 요청 제한(rate-limited)이 없습니다.

graph LR
    A[Create]:::start --> B[Deploying]:::proc
    B --> C[Ready]:::out
    C -->|stop| D[Stopped]:::extern
    D -->|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

쿼리 매개변수:

파라미터유형설명
modelId문자열(string)모델별 필터링
status문자열(string)상태별 필터링
limit정수(int)최대 결과 수 (기본값: 20, 최대: 100)
owner문자열(string)워크스페이스 소유자 사용자 이름

배포 생성#

POST /api/deployments

본문:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}
필드유형필수설명
modelId문자열(string)예배포할 모델 ID
name문자열(string)예배포 이름
region문자열(string)예배포 리전
resources객체아니요리소스 구성(cpu, memoryGi, minInstances, maxInstances)

지정된 리전에 전용 추론 엔드포인트를 생성합니다. 이 엔드포인트는 고유 URL을 통해 전 세계 어디에서나 접근할 수 있습니다.

기본 리소스

현재 배포 대화상자에서는 cpu=1, memoryGi=2, minInstances=0 및 maxInstances=1의 고정된 기본값을 제출합니다. API 라우트는 resources 객체를 허용하지만, 플랜 제한으로 인해 minInstances은(는) 0으로, maxInstances은(는) 1(으)로 제한됩니다.

리전 선택

가장 낮은 지연 시간을 위해 사용자에게 가까운 리전을 선택하십시오. 플랫폼 UI는 사용 가능한 42개 모든 리전에 대한 지연 시간 예상치를 보여줍니다.

배포 조회#

GET /api/deployments/{deploymentId}

배포 삭제#

DELETE /api/deployments/{deploymentId}

배포 시작#

POST /api/deployments/{deploymentId}/start

중지된 배포를 재개합니다.

배포 중지#

POST /api/deployments/{deploymentId}/stop

서비스의 최소 및 최대 인스턴스를 0으로 설정하여 요청 처리를 중지합니다.

상태 확인#

GET /api/deployments/{deploymentId}/health

배포 엔드포인트의 상태를 반환합니다.

배포에서 추론 실행#

POST /api/deployments/{deploymentId}/predict

이미지를 배포 엔드포인트로 직접 보내 추론을 수행합니다. 모델 예측과 기능적으로 동일하지만 지연 시간을 줄이기 위해 전용 엔드포인트를 통합니다.

멀티파트 폼:

파라미터유형기본값범위설명
file파일--이미지 또는 비디오 파일 (source이(가) 설정된 경우 제외 필수)
conf부동 소수점(float)0.250.01 – 1.0최소 신뢰도 임계값
iou부동 소수점(float)0.70.0 – 0.95NMS IoU 임계값
imgsz정수(int)64032 – 1280입력 이미지 크기 (픽셀 단위)
normalizeboolfalse-바운딩 박스 좌표를 0 – 1 범위로 반환
decimals정수(int)50 – 10좌표 값에 대한 소수점 정밀도
source문자열(string)--이미지 URL 또는 base64 문자열 (file의 대안)

file 또는 source 중 하나를 제공하세요. 응답은 모델 예측과 동일한 이미지 및 메타데이터 계약을 사용하며 내부 모델 경로를 절대 반환하지 않습니다.

지표 가져오기#

GET /api/deployments/{deploymentId}/metrics

스파크라인 데이터를 포함한 요청 수, 지연 시간 및 오류율 지표를 반환합니다.

쿼리 매개변수:

파라미터유형설명
range문자열(string)시간 범위: 1h, 6h, 24h(기본값), 7d, 30d
sparkline문자열(string)대시보드 보기용으로 최적화된 스파크라인 데이터를 위해 true(으)로 설정합니다.

로그 가져오기#

GET /api/deployments/{deploymentId}/logs

쿼리 매개변수:

파라미터유형설명
severity문자열(string)쉼표로 구분된 필터: DEBUG, INFO, WARNING, ERROR, CRITICAL
limit정수(int)항목 수 (기본값: 50, 최대: 200)
pageToken문자열(string)이전 응답에서 가져온 페이지네이션 토큰

내보내기 API#

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

내보내기 목록#

GET /api/exports

쿼리 매개변수:

파라미터유형설명
modelId문자열(string)모델 ID (필수)
status문자열(string)상태별 필터링
limit정수(int)최대 결과 수 (기본값: 20, 최대: 100)

내보내기 생성#

POST /api/exports

본문:

필드유형필수설명
modelId문자열(string)예소스 모델 ID
format문자열(string)예내보내기 형식 (아래 표 참조)
gpuType문자열(string)조건부format이(가) engine일 때 필요합니다. 지원되는 GPU 또는 Jetson target을(를) 사용하세요.
args객체아니요내보내기 인수(imgsz, quantize, dynamic 등)
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

지원되는 형식:

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

형식format 인수모델메타데이터인수
PyTorch-yolo26n.pt✅-
TorchScripttorchscriptyolo26n.torchscript✅imgsz, quantize, dynamic, nms, batch, device
ONNXonnxyolo26n.onnx✅imgsz, quantize, dynamic, simplify, opset, nms, batch, data, fraction, device
OpenVINOopenvinoyolo26n_openvino_model/✅imgsz, quantize, dynamic, nms, batch, data, fraction, device
TensorRTengineyolo26n.engine✅imgsz, quantize, dynamic, simplify, opset, workspace, nms, batch, data, fraction, device
CoreMLcoremlyolo26n.mlpackage✅imgsz, dynamic, quantize, nms, batch, device
TF SavedModelsaved_modelyolo26n_saved_model/✅imgsz, keras, quantize, opset, nms, batch, data, fraction, device
TF GraphDefpbyolo26n.pb❌imgsz, opset, batch, device
TF Edge TPUedgetpuyolo26n_edgetpu.tflite✅imgsz, quantize, opset, data, fraction, device
PaddlePaddlepaddleyolo26n_paddle_model/✅imgsz, batch, device
MNNmnnyolo26n.mnn✅imgsz, batch, dynamic, quantize, simplify, opset, nms, device
NCNNncnnyolo26n_ncnn_model/✅imgsz, quantize, batch, device
IMX500imxyolo26n_imx_model/✅imgsz, quantize, data, fraction, nms, device
RKNNrknnyolo26n_rknn_model/✅imgsz, batch, name, quantize, simplify, opset, data, fraction, device
ExecuTorchexecutorchyolo26n_executorch_model/✅imgsz, batch, device
Axeleraaxelerayolo26n_axelera_model/✅imgsz, batch, quantize, data, fraction, device
DEEPXdeepxyolo26n_deepx_model/✅imgsz, quantize, simplify, opset, data, optimize, device
Qualcomm QNNqnnyolo26n_qnn.onnx✅imgsz, batch, name, quantize, simplify, opset, data, fraction, device
LiteRTlitertyolo26n.tflite✅imgsz, quantize, batch, data, fraction, device
Hailohailoyolo26n_hailo_model/✅imgsz, name, quantize, data, fraction, simplify, conf, iou
Huawei Ascendascendyolo26n_ascend_model/✅imgsz, batch, name, quantize, opset, simplify, nms

내보내기 상태 가져오기#

GET /api/exports/{exportId}

내보내기 취소#

DELETE /api/exports/{exportId}

내보내기 다운로드 추적#

POST /api/exports/{exportId}/track-download

활동 API#

계정의 최근 활동 피드(학습 실행, 업로드 등)를 확인하세요. Activity documentation을(를) 참조하세요.

경로별 API 키 지원

아래의 모든 활동(Activity) 경로는 API 키 인증을 수락합니다.

활동 목록#

GET /api/activity

쿼리 매개변수:

파라미터유형설명
limit정수(int)페이지 크기(기본값: 20, 최대: 100)
page정수(int)페이지 번호(기본값: 1)
archived부울(boolean)아카이브 탭의 경우 true, 받은 편지함의 경우 false
search문자열(string)이벤트 필드 내 대소문자를 구분하지 않는 검색
start날짜이 날짜 이후의 이벤트 포함
end날짜이 날짜 이전의 이벤트 포함
export부울(boolean)일치하는 모든 이벤트를 JSON으로 반환
owner문자열(string)워크스페이스 사용자 이름

이벤트를 확인됨으로 표시#

POST /api/activity/mark-seen

본문:

{
    "all": true
}

또는 특정 ID를 전달하십시오:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

워크스페이스의 이벤트를 표시하려면 선택 사항인 owner 쿼리 파라미터를 전달하세요.

이벤트 보관#

POST /api/activity/archive

본문:

{
    "all": true,
    "archive": true
}

또는 특정 ID를 전달하십시오:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

워크스페이스 이벤트를 보관하거나 복원하려면 선택 사항인 owner 쿼리 파라미터를 전달하세요.

휴지통 API#

삭제된 항목을 확인하고 복원합니다. 항목은 30일 후에 영구적으로 제거됩니다. Trash documentation을(를) 참조하세요.

휴지통 목록#

GET /api/trash

쿼리 매개변수:

파라미터유형설명
type문자열(string)필터: all, project, dataset, model
page정수(int)페이지 번호(기본값: 1)
limit정수(int)페이지당 항목 수(기본값: 50, 최대: 200)
owner문자열(string)워크스페이스 소유자 사용자 이름

항목 복원#

POST /api/trash

본문:

{
    "id": "item_abc123",
    "type": "dataset"
}

항목 영구 삭제#

DELETE /api/trash

본문:

{
    "id": "item_abc123",
    "type": "dataset"
}
되돌릴 수 없음

영구 삭제는 취소할 수 없습니다. 리소스와 모든 관련 데이터가 제거됩니다.

휴지통 비우기#

DELETE /api/trash/empty

휴지통의 모든 항목을 영구적으로 삭제합니다.

인증

DELETE /api/trash/empty은(는) API 키 인증을 허용하며 선택한 계정 또는 워크스페이스 휴지통에 있는 모든 항목을 영구적으로 삭제합니다.

결제 API#

크레딧 잔액, 플랜 사용량 및 거래 내역을 확인하세요. Billing documentation을(를) 참조하세요.

잔액 및 거래 엔드포인트는 워크스페이스 소유자의 사용자 이름이 포함된 선택 사항인 owner 쿼리 파라미터를 허용합니다.

통화 단위

청구 금액은 100 = $1.00인 센트 단위(creditsCents)를 사용합니다.

잔액 가져오기#

GET /api/billing/balance

응답:

{
    "creditsCents": 2500,
    "plan": "free"
}

사용 요약 가져오기#

GET /api/billing/usage-summary

플랜 세부 정보, 제한 사항 및 사용량 메트릭을 반환합니다.

거래 내역 가져오기#

GET /api/billing/transactions

거래 내역을 반환합니다(최근 항목 우선).

거래 내역에는 금액, 결과 잔액, 날짜, 선택적 모델 컨텍스트 및 영수증 URL과 같은 클라이언트용 원장 필드가 포함됩니다. 내부 메모, Stripe 결제/환불 ID 및 멱등성 키는 반환되지 않습니다.

스토리지 API#

카테고리별(데이터셋, 모델, 내보내기) 스토리지 사용 내역을 확인하고 가장 용량이 큰 항목을 확인합니다.

API 키 액세스

GET /api/storage은(는) API 키 인증을 허용합니다. 동일한 대화형 내역 분석을 보려면 Settings > Profile 페이지를 사용하세요.

스토리지 정보 가져오기#

GET /api/storage

쿼리 매개변수:

파라미터유형설명
details부울(boolean)topItems(가장 큰 데이터셋, 모델, 내보내기)을 포함하려면 true(으)로 설정합니다.
owner문자열(string)워크스페이스 사용자 이름입니다.

응답:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

클라우드 스토리지 통합#

읽기 전용 GCS, S3 또는 Azure Blob 스토리지 통합을 연결하고 탐색하십시오:

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

4가지 작업 모두 워크스페이스용 선택적 owner 쿼리 파라미터를 허용합니다. 객체 탐색은 필수 target 및 선택적 prefix와 공급자 cursor 쿼리 파라미터도 허용합니다. 연결 및 검색 요청 본문은 대화형 OpenAPI 레퍼런스의 공급자 자격 증명 스키마를 사용하며, 자격 증명은 절대 반환되지 않습니다.

업로드 API#

빠르고 안정적인 전송을 위해 서명된 URL을 사용하여 클라우드 스토리지에 파일을 직접 업로드합니다. 모델 업로드를 완료하면 가중치가 첨부됩니다. 데이터셋 아카이브 업로드를 완료하면 세션이 기록됩니다. 해당 sessionId을(를) POST /api/datasets/ingest에 전달하여 처리를 시작하세요. Data documentation을(를) 참조하세요.

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

POST /api/upload/signed-url

클라우드 스토리지로 직접 파일을 업로드하기 위한 서명된 URL을 요청합니다. 서명된 URL은 대용량 파일 전송 시 API 서버를 우회합니다.

본문:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}
필드유형설명
assetType문자열(string)에셋 유형: models, datasets, images, videos
assetId문자열(string)대상 에셋의 ID
filename문자열(string)원본 파일명
contentType문자열(string)MIME 유형
totalBytes정수(int)바이트 단위의 파일 크기

응답:

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

업로드 완료#

POST /api/upload/complete

파일 업로드가 완료되었음을 플랫폼에 알립니다. 모델의 경우 업로드된 가중치를 첨부합니다. 데이터셋 아카이브의 경우 업로드 세션을 확인하고 기록합니다. 이후 데이터셋 처리를 시작하려면 POST /api/datasets/ingest을(를) 호출하세요.

본문:

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

통합 API#

타사 서비스에서 데이터셋을 가져옵니다. Integrations documentation을(를) 참조하세요.

Roboflow 가져오기 미리보기#

POST /api/integrations/roboflow/preview

Roboflow API 키를 통해 대량 가져오기 계획을 확인합니다: 워크스페이스 정보, 새로 가져올 프로젝트, 이미 가져온 버전 수(건너뜀) 및 지원되지 않는 프로젝트 유형. Roboflow API 키는 본문에 전달되며 저장되지 않습니다.

Roboflow에서 가져오기#

POST /api/integrations/roboflow/import

선택한 Roboflow 프로젝트를 워크스페이스로 가져오기 위해 데이터셋 수집 작업을 대기열에 추가합니다. 저장 공간 여유가 필요하며, 각 데이터셋은 귀하의 요금제별 가져오기 크기 제한을 충족해야 합니다.

API 키 API#

프로그래밍 방식 액세스를 위한 API 키를 관리하세요. API Keys documentation을(를) 참조하세요.

API 키 목록#

GET /api/api-keys

API 키 인증 클라이언트는 키 메타데이터를 수신하며, 복호화된 기존 키 값은 절대 수신하지 않습니다. 새로 생성된 키는 POST /api/api-keys에 의해 한 번 반환됩니다.

편집자 권한이 있는 워크스페이스의 키를 관리하려면 선택 사항인 owner 쿼리 파라미터를 전달하세요.

API 키 생성#

POST /api/api-keys

본문:

{
    "name": "training-server"
}

API 키 삭제#

DELETE /api/api-keys

쿼리 매개변수:

파라미터유형설명
keyId문자열(string)취소할 API 키 ID
owner문자열(string)선택적 워크스페이스 사용자 이름입니다.

예시:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

팀 및 멤버 API#

팀 워크스페이스를 만들고, 멤버를 초대하고, 협업을 위한 역할을 관리하세요. Teams documentation을(를) 참조하세요.

팀 목록#

GET /api/teams

팀 생성#

POST /api/teams/create

본문:

{
    "username": "my-team",
    "fullName": "My Team"
}

멤버 목록#

GET /api/members

현재 워크스페이스의 멤버를 반환합니다.

멤버 초대#

POST /api/members

본문:

{
    "email": "user@example.com",
    "role": "editor"
}
멤버 역할
역할권한
viewer워크스페이스 리소스에 대한 읽기 전용 액세스
editor리소스 생성, 편집 및 삭제
admin멤버, 결제 및 모든 리소스 관리(팀 소유자만 할당 가능)

팀 owner은(는) 생성자이므로 초대할 수 없습니다. 소유자는 POST /api/members/transfer-ownership을(를) 통해 별도로 이전됩니다. 전체 역할 세부 정보는 Teams을(를) 참조하세요.

멤버 역할 업데이트#

PATCH /api/members/{userId}

멤버 제거#

DELETE /api/members/{userId}

소유권 이전#

POST /api/members/transfer-ownership

탐색(Explore) API#

커뮤니티에서 공유한 공개 데이터셋과 프로젝트를 검색하고 탐색하세요. Explore documentation을(를) 참조하세요.

공개 콘텐츠 검색#

GET /api/explore/search

쿼리 매개변수:

파라미터유형설명
q문자열(string)검색 쿼리
type문자열(string)리소스 유형: all(기본값), projects, datasets
sort문자열(string)정렬 순서: newest(기본값), stars, oldest, name-asc, name-desc, count-desc, count-asc
offset정수(int)페이지네이션 오프셋 (기본값: 0). 결과는 페이지당 20개 항목을 반환합니다.
task문자열(string)선택 사항: 데이터셋을 필터링하기 위한 쉼표로 구분된 YOLO 작업 유형(detect, segment, semantic, classify, pose, obb)
author문자열(string)선택적 소유자 사용자 이름 필터입니다.
starred부울(boolean)인증된 호출자가 별표 표시한 콘텐츠를 반환하려면 true을(를) 설정하세요. API 키가 필요합니다.

사이드바 데이터#

GET /api/explore/sidebar

탐색 사이드바를 위한 추천 콘텐츠를 반환합니다.

사용자 및 설정 API#

프로필, API 키, 스토리지 사용량 및 팀 워크스페이스를 관리하세요. Settings documentation을(를) 참조하세요.

계정 요약#

GET /api/account/summary

인증된 계정의 플랜, 크레딧 잔액, 리소스 수 및 팀 워크스페이스를 반환합니다.

사용자 이름으로 사용자 가져오기#

GET /api/users

쿼리 매개변수:

파라미터유형설명
username문자열(string)조회할 사용자 이름

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

PATCH /api/users

본문:

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

사용자 이름 사용 가능 여부 확인#

GET /api/username/check

쿼리 매개변수:

파라미터유형설명
username문자열(string)확인할 사용자 이름
suggestbool선택 사항: 이미 사용 중인 경우 제안을 포함하기 위한 true

설정#

GET /api/settings
POST /api/settings

사용자 프로필 설정(표시 이름, 소개, 소셜 링크 등)을 가져오거나 업데이트합니다.

워크스페이스 아이콘#

POST /api/settings/icon
DELETE /api/settings/icon

최대 5 MB 크기의 WebP 프로필/워크스페이스 아이콘을 멀티파트 폼 필드 image(으)로 업로드하거나 제거합니다. 팀 워크스페이스를 위해 선택 사항인 owner을(를) 전달하세요.

Python 통합#

더 쉬운 통합을 위해 인증, 업로드 및 실시간 메트릭 스트리밍을 자동으로 처리하는 Ultralytics Python 패키지를 사용하십시오.

설치 및 설정#

pip install "ultralytics>=8.4.104"

설치 확인:

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

패턴설명
ul://username/datasets/slug데이터셋
ul://username/project-name프로젝트
ul://username/project/model-name특정 모델
ul://ultralytics/yolo26/yolo26n공식 모델

플랫폼으로 푸시#

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

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#

대규모 결과를 페이지로 나누려면 어떻게 해야 합니까?#

대부분의 엔드포인트는 요청당 반환되는 결과 수를 제어하기 위해 limit 파라미터를 사용합니다:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

Activity 및 Trash 엔드포인트는 페이지 기반 페이지네이션을 위한 page 파라미터도 지원합니다:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

탐색 검색(Explore Search) 엔드포인트는 page 대신 offset을 사용하며, 고정 페이지 크기는 20입니다.

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

SDK 없이 API를 사용할 수 있습니까?#

위에 문서화된 공개 REST 작업은 Python SDK 없이도 사용할 수 있습니다. SDK는 실시간 메트릭 스트리밍 및 자동 모델 업로드와 같은 기능을 추가하는 편리한 래퍼입니다. platform.ultralytics.com/api/docs에서 머신 레더블 계약을 대화형으로 탐색할 수 있으며, 브라우저 세션 전용 계정 흐름은 Platform UI에 유지됩니다.

API 클라이언트 라이브러리가 있습니까?#

Ultralytics Python 패키지를 사용하거나 모든 언어에서 직접 HTTP 요청을 만드세요.

요청 제한(rate limit)은 어떻게 처리합니까?#

올바른 시간 동안 기다리려면 429 응답의 Retry-After 헤더를 사용하세요:

import time

import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(wait)
    raise RuntimeError("Rate limit exceeded")

모델 또는 데이터셋 ID는 어떻게 찾습니까?#

리소스 ID는 생성, 목록 조회 및 가져오기 API 응답에 의해 반환됩니다. Platform 페이지 URL은 데이터베이스 ID가 아니라 사람이 읽을 수 있는 슬러그를 사용합니다:

https://platform.ultralytics.com/username/project/model-name
                                  ^^^^^^^^ ^^^^^^^ ^^^^^^^^^^
                                  username project   model

목록 엔드포인트를 사용하여 모델, 데이터셋, 프로젝트, 배포 또는 기타 리소스에 해당하는 _id을(를) 찾으세요.

기여자
GLglenn-jocher35SEsergiuwaxmann2MYmykolaxboiko2AMamanharshx1AMambitious-octopus1ONonuralpszr1LAlaodouya1RAraimbekovm1LALaughing-q1

댓글