REST API 참조

Q: How do I paginate large results?

대부분의 엔드포인트는 요청당 반환되는 결과 수를 제어하기 위해 limit 매개변수를 사용합니다: Activity 및 Trash 엔드포인트는 페이지 기반 페이지네이션을 위한 page 매개변수도 지원합니다: Explore Search 엔드포인트는 page 대신 offset을 사용하며, 고정된 페이지 크기는 20개입니다:

Q: How do I handle rate limits?

429 응답의 Retry-After 헤더를 사용하여 적절한 시간을 기다리십시오:

Ultralytics 플랫폼은 데이터셋, 모델, 훈련 및 배포에 대한 프로그래밍 방식의 접근을 위한 포괄적인 REST API를 제공합니다.

Ultralytics API 개요

빠른 시작

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

API 개요

API는 핵심 플랫폼 리소스를 중심으로 구성됩니다:

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

자원	설명	핵심 운영
데이터 세트	라벨링된 이미지 컬렉션	CRUD, 이미지, 라벨, 내보내기, 복제
프로젝트	훈련 작업 공간	CRUD, 복제, 아이콘
모델	훈련된 체크포인트	CRUD, 예측, 다운로드, 복제, 내보내기
배포	전용 추론 엔드포인트	CRUD, 시작/중지, 메트릭스, 로그, 상태
내보내기	형식 변환 작업	생성, 상태, 다운로드
훈련	클라우드 GPU 작업	시작, 상태, 취소
결제	크레딧 및 구독	잔액, 충전, 결제 방법
팀	작업 공간 협업	회원, 초대, 역할

인증

대부분의 API 요청은 API 키를 통한 인증이 필요합니다. 공개 엔드포인트(공개 데이터셋, 프로젝트 및 모델 목록 조회)는 키 없이 익명 읽기 액세스를 지원합니다.

API 키 받기

가다 Settings > Profile (API 키 섹션)
클릭 Create Key
생성된 키를 복사합니다.

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

인증 헤더

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

Authorization: Bearer ul_your_api_key_here

API 키 형식

API 키는 다음 형식을 사용합니다. ul_ 40개의 16진수 문자가 뒤따릅니다. 키를 비밀로 유지하십시오 — 버전 관리에 커밋하거나 공개적으로 공유하지 마십시오.

예시

cURLPython자바스크립트

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

import requests

headers = {"Authorization": "Bearer ul_abc123..."}
response = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers=headers,
)
data = response.json()

const response = await fetch("https://platform.ultralytics.com/api/datasets", {
  headers: { Authorization: "Bearer ul_abc123..." },
});
const data = await response.json();

기본 URL

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

https://platform.ultralytics.com/api

속도 제한

API는 악용을 방지하면서도 정상적인 사용에는 제한을 두지 않기 위해 이중 속도 제한 시스템을 사용합니다:

API 키별 — 인증된 요청에 대해 API 키별로 적용되는 제한
IP당 — 모든 IP 주소당 분당 100건의 요청 /api/* 경로 (인증된 요청과 인증되지 않은 요청 모두에 적용됨)

제한될 경우, API는 반환합니다 429 재시도 메타데이터와 함께:

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

API 키 제한 사항

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

엔드포인트	제한	적용 대상
기본값	분당 100 요청	아래에 나열되지 않은 모든 엔드포인트 (목록 조회, 가져오기, 생성, 업데이트, 삭제)
훈련	분당 10건의 요청	클라우드 교육 일자리 시작하기 (`POST /api/training/start`)
업로드	분당 10건의 요청	파일 업로드, 서명된 URL, 데이터셋 수집
예측	분당 20건의 요청	공유 모델 추론 (`POST /api/models/{id}/predict`)
내보내기	분당 20건의 요청	모델 형식 내보내기 (`POST /api/exports`) 및 NDJSON 데이터셋 내보내기
다운로드	분당 30건의 요청	모델 가중치 파일 다운로드 (`GET /api/models/{id}/download`)
전용	무제한	전용 엔드포인트 — 자체 서비스, API 제한 없음

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

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

전용 엔드포인트 이다 API 키 속도 제한의 적용을 받지 않음모델을 전용 엔드포인트에 배포하면, 해당 엔드포인트 URL(예: https://predict-abc123.run.app/predict플랫폼의 속도 제한 없이 전용 서비스로 직접 연결됩니다. 컴퓨팅 비용을 지불하므로 엔드포인트의 확장 구성에 따라 무제한 처리량을 확보할 수 있습니다.

처리 속도 제한

수신 시 429 상태 코드, 대기 Retry-After (또는 ~할 때까지) X-RateLimit-Reset) 재시도하기 전에. 참조: 속도 제한 FAQ 지수적 백오프 구현을 위한.

응답 형식

성공 응답

응답은 리소스별 필드가 포함된 JSON을 반환합니다:

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

오류 응답

{
    "error": "Invalid dataset ID"
}

HTTP 상태	의미
`200`	성공
`201`	생성됨
`400`	잘못된 요청
`401`	인증이 필요합니다
`403`	권한 부족
`404`	리소스를 찾을 수 없음
`409`	갈등 (중복)
`429`	요청 횟수 제한 초과
`500`	서버 오류

데이터셋 API

YOLO 훈련을 위한 라벨링된 이미지 컬렉션 관리

데이터 세트 목록

GET /api/datasets

쿼리 파라미터:

파라미터	유형	설명
`username`	문자열	사용자명으로 필터링
`slug`	문자열	슬러그로 단일 데이터셋 가져오기
`limit`	정수	페이지당 항목 수 (기본값: 20, 최대값: 500)
`owner`	문자열	작업 공간 소유자 사용자 이름

cURLPython

curl -H "Authorization: Bearer $API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=10"

import requests

resp = requests.get(
    "https://platform.ultralytics.com/api/datasets",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10},
)
for ds in resp.json()["datasets"]:
    print(f"{ds['name']}: {ds['imageCount']} images")

응답:

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

전체 데이터셋 세부 정보를 반환합니다. 여기에는 메타데이터, 클래스 이름 및 분할 횟수가 포함됩니다.

데이터셋 생성

POST /api/datasets

본문:

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "visibility": "private",
    "classNames": ["person", "car"]
}

지원되는 작업

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

데이터셋 업데이트

PATCH /api/datasets/{datasetId}

본문 (부분 업데이트):

{
    "name": "Updated Name",
    "description": "New description",
    "visibility": "public"
}

데이터세트 삭제

DELETE /api/datasets/{datasetId}

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

데이터셋 복제

POST /api/datasets/{datasetId}/clone

모든 이미지와 라벨을 포함한 데이터셋의 복사본을 생성합니다. 공개 데이터셋만 복제할 수 있습니다.

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

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

데이터셋 내보내기

GET /api/datasets/{datasetId}/export

데이터셋 내보내기 파일의 서명된 다운로드 URL이 포함된 JSON 응답을 반환합니다.

응답:

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

클래스 통계 확인

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
}

데이터셋으로 모델 훈련하기

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`	문자열	예	주석 달 이미지 해시
`modelId`	문자열	아니요	추론에 사용할 모델 ID
`confidence`	부동 소수점	아니요	신뢰도 임계값 (기본값: 0.25)
`iou`	부동 소수점	아니요	IoU (기본값: 0.45)

데이터셋 수집

POST /api/datasets/ingest

이미지와 레이블이 포함된 업로드된 ZIP 파일을 처리하기 위한 데이터셋 인제스트 작업을 생성합니다.

graph LR
    A[Upload ZIP] --> B[POST /api/datasets/ingest]
    B --> C[Process ZIP]
    C --> D[Extract images]
    C --> E[Parse labels]
    C --> F[Generate thumbnails]
    D & E & F --> G[Dataset ready]

데이터셋 이미지

이미지 목록

GET /api/datasets/{datasetId}/images

쿼리 파라미터:

파라미터	유형	설명
`split`	문자열	분할별 필터링: `train`, `val`, `test`
`offset`	정수	페이지 번호 오프셋 (기본값: 0)
`limit`	정수	페이지당 항목 수 (기본값: 50, 최대값: 5000)
`sort`	문자열	정렬 순서: `newest`, `oldest`, `name-asc`, `name-desc`, `size-asc`, `size-desc`, `labels-asc`, `labels-desc`
`hasLabel`	문자열	라벨 상태로 필터링하기 (`true` 또는 `false`)
`hasError`	문자열	오류 상태로 필터링하기 (`true` 또는 `false`)
`search`	문자열	파일명 또는 이미지 해시로 검색
`includeThumbnails`	문자열	서명된 썸네일 URL 포함 (기본값: `true`)
`includeImageUrls`	문자열	서명된 전체 이미지 URL 포함 (기본값: `false`)

서명된 이미지 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] }]
}

좌표 형식

바운딩 박스는 YOLO 형식을 사용합니다: [x_center, y_center, width, height] 모든 값이 0과 1 사이인 경우.

대량 이미지 작업

데이터셋 내 분할(훈련/검증/테스트) 간 이미지 이동:

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

이미지 일괄 삭제:

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

프로젝트 API

모델을 그룹화하는 훈련 작업 공간을 관리합니다.

프로젝트 목록

GET /api/projects

쿼리 파라미터:

파라미터	유형	설명
`username`	문자열	사용자명으로 필터링
`limit`	정수	페이지당 항목 수
`owner`	문자열	작업 공간 소유자 사용자 이름

프로젝트 가져오기

GET /api/projects/{projectId}

프로젝트 생성

POST /api/projects

cURLPython

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "slug": "my-project", "description": "Detection experiments"}' \
  https://platform.ultralytics.com/api/projects

resp = requests.post(
    "https://platform.ultralytics.com/api/projects",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"name": "my-project", "slug": "my-project", "description": "Detection experiments"},
)
project_id = resp.json()["projectId"]

프로젝트 업데이트

PATCH /api/projects/{projectId}

프로젝트 삭제

DELETE /api/projects/{projectId}

프로젝트를 휴지통으로 이동하여 삭제합니다.

클론 프로젝트

POST /api/projects/{projectId}/clone

프로젝트 아이콘

프로젝트 아이콘 업로드 (이미지 파일을 포함한 멀티파트 양식):

POST /api/projects/{projectId}/icon

프로젝트 아이콘 제거:

DELETE /api/projects/{projectId}/icon

모델 API

프로젝트 내에서 훈련된 모델 체크포인트를 관리합니다.

모델 목록

GET /api/models

쿼리 파라미터:

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

완성된 모델 목록

GET /api/models/completed

훈련을 완료한 모델을 반환합니다(모델 선택기 및 배포에 사용).

모델 가져오기

GET /api/models/{modelId}

모델 생성

POST /api/models

JSON 본문:

필드	유형	필수	설명
`projectId`	문자열	예	대상 프로젝트 ID
`slug`	문자열	아니요	URL 슬러그 (소문자 영숫자/하이픈)
`name`	문자열	아니요	표시 이름 (최대 100자)
`description`	문자열	아니요	모델 설명 (최대 1000자)
`task`	문자열	아니요	작업 유형 (detect, segment, 포즈, obb, classify)

모델 파일 업로드

모델 .pt 파일 업로드는 별도로 처리됩니다. 플랫폼 UI를 사용하여 모델 파일을 프로젝트로 드래그 앤 드롭하세요.

모델 업데이트

PATCH /api/models/{modelId}

모델 삭제

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`	문자열	예	목적지 프로젝트 슬러그
`modelName`	문자열	아니요	복제된 모델의 이름
`description`	문자열	아니요	모델 설명
`owner`	문자열	아니요	팀 사용자 이름 (워크스페이스 복제를 위한)

트랙 다운로드

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

트랙 모델 다운로드 분석 추적.

추론 실행

POST /api/models/{modelId}/predict

멀티파트 폼:

필드	유형	설명
`file`	파일	이미지 파일 (JPEG, PNG, WebP)
`conf`	부동 소수점	신뢰도 임계값 (기본값: 0.25)
`iou`	부동 소수점	IoU (기본값: 0.7)
`imgsz`	정수	이미지 크기 (픽셀 단위) (기본값: 640)

cURLPython

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

with open("image.jpg", "rb") as f:
    resp = requests.post(
        f"https://platform.ultralytics.com/api/models/{model_id}/predict",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"conf": 0.5},
    )
results = resp.json()["images"][0]["results"]

응답:

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

예측 토큰 받기

POST /api/models/{modelId}/predict/token

직접 예측 요청을 위한 단기 토큰을 획득하세요. 이 토큰은 클라이언트 측 애플리케이션에서 더 낮은 지연 시간의 추론을 위해 API 프록시를 우회합니다.

워밍업 모델

POST /api/models/{modelId}/predict/warmup

모델을 사전 로드하여 첫 번째 추론을 더 빠르게 수행합니다. 예측 실행 전에 이 작업을 호출하여 초기 요청 시 지연을 방지하십시오.

학습 API

클라우드 트레이닝 작업을 시작, 모니터링 및 취소합니다.

graph LR
    A[POST /training/start] --> B[Job Created]
    B --> C{Training}
    C -->|progress| D[GET /models/id/training]
    C -->|cancel| E[DELETE /models/id/training]
    C -->|complete| F[Model Ready]
    F --> G[Deploy or Export]

학습 시작

POST /api/training/start

cURLPython

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

resp = requests.post(
    "https://platform.ultralytics.com/api/training/start",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "modelId": "MODEL_ID",
        "projectId": "PROJECT_ID",
        "gpuType": "rtx-4090",
        "trainArgs": {
            "model": "yolo11n.pt",
            "data": "ul://username/datasets/my-dataset",
            "epochs": 100,
            "imgsz": 640,
            "batch": 16,
        },
    },
)

GPU

사용 가능한 GPU 다음과 같습니다: rtx-4090, a100-80gb-pcie, a100-80gb-sxm, h100-sxm, rtx-pro-6000, 그리고 기타. 참조 클라우드 트레이닝 가격이 포함된 전체 목록을 보려면.

학습 상태 가져오기

GET /api/models/{modelId}/training

모델에 대한 현재 훈련 작업 상태, 메트릭 및 진행 상황을 반환합니다.

학습 취소

DELETE /api/models/{modelId}/training

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

배포 API

전용 추론 엔드포인트를 생성하고 관리합니다.

graph LR
    A[Create] --> B[Deploying]
    B --> C[Ready]
    C -->|stop| D[Stopped]
    D -->|start| C
    C -->|delete| E[Deleted]
    D -->|delete| E
    C -->|predict| F[Inference Results]

배포 목록

GET /api/deployments

쿼리 파라미터:

파라미터	유형	설명
`modelId`	문자열	모델로 필터링
`status`	문자열	상태별 필터링
`limit`	정수	최대 결과 수 (기본값: 20, 최대: 100)
`owner`	문자열	작업 공간 소유자 사용자 이름

배포 생성

POST /api/deployments

본문:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

필드	유형	필수	설명
`modelId`	문자열	예	배포할 모델 ID
`name`	문자열	예	배포 이름
`region`	문자열	예	배포 지역
`resources`	object	아니요	리소스 구성 (cpu, 메모리Gi, 최소 인스턴스 수, 최대 인스턴스 수)

지정된 리전에 전용 추론 엔드포인트를 생성합니다. 이 엔드포인트는 고유한 URL을 통해 전역적으로 접근할 수 있습니다.

지역 선택

사용자와 가까운 지역을 선택하여 지연 시간을 최소화하세요. 플랫폼 UI에서는 사용 가능한 43개 지역 모두에 대한 예상 지연 시간을 표시합니다.

배포 가져오기

GET /api/deployments/{deploymentId}

배포 삭제

DELETE /api/deployments/{deploymentId}

배포 시작

POST /api/deployments/{deploymentId}/start

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

배포 중지

POST /api/deployments/{deploymentId}/stop

실행 중인 배포를 일시 중지합니다(청구 중지).

상태 점검

GET /api/deployments/{deploymentId}/health

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

배포 시 추론 실행

POST /api/deployments/{deploymentId}/predict

추론을 위해 이미지를 배포 엔드포인트로 직접 전송합니다. 모델 예측과 기능적으로 동일하지만, 더 낮은 지연 시간을 위해 전용 엔드포인트를 통해 라우팅됩니다.

멀티파트 폼:

필드	유형	설명
`file`	파일	이미지 파일 (JPEG, PNG, WebP)
`conf`	부동 소수점	신뢰도 임계값 (기본값: 0.25)
`iou`	부동 소수점	IoU (기본값: 0.7)
`imgsz`	정수	이미지 크기 (픽셀 단위) (기본값: 640)

메트릭 가져오기

GET /api/deployments/{deploymentId}/metrics

요청 수, 지연 시간 및 오류율 메트릭을 스파크라인 데이터와 함께 반환합니다.

쿼리 파라미터:

파라미터	유형	설명
`range`	문자열	시간 범위: `1h`, `6h`, `24h` (기본값), `7d`, `30d`
`sparkline`	문자열	설정됨 `true` 대시보드 보기를 위한 최적화된 스파크라인 데이터

로그 가져오기

GET /api/deployments/{deploymentId}/logs

쿼리 파라미터:

파라미터	유형	설명
`severity`	문자열	쉼표로 구분된 필터: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
`limit`	정수	항목 수 (기본값: 50, 최대: 200)
`pageToken`	문자열	이전 응답의 페이지 매김 토큰

모니터링 API

집계된 메트릭

GET /api/monitoring

모든 사용자 배포에 걸쳐 집계된 메트릭을 반환합니다: 총 요청 수, 활성 배포 수, 오류율 및 평균 지연 시간.

내보내기 API

모델을 에지 배포를 위한 최적화된 형식으로 변환합니다.

내보내기 목록

GET /api/exports

쿼리 파라미터:

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

내보내기 생성

POST /api/exports

본문:

필드	유형	필수	설명
`modelId`	문자열	예	소스 모델 ID
`format`	문자열	예	수출 형식 (아래 표 참조)
`gpuType`	문자열	조건부	필요할 때 `format` 입니다. `engine` (TensorRT)
`args`	object	아니요	인수 내보내기 (`imgsz`, `half`, `dynamic`등)

cURLPython

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

resp = requests.post(
    "https://platform.ultralytics.com/api/exports",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"modelId": "MODEL_ID", "format": "onnx"},
)
export_id = resp.json()["exportId"]

지원되는 형식:

형식	값	사용 사례
ONNX	`onnx`	크로스 플랫폼 추론
TorchScript	`torchscript`	PyTorch 배포
OpenVINO	`openvino`	Intel
TensorRT	`engine`	NVIDIA GPU
CoreML	`coreml`	애플 기기
TFLite	`tflite`	모바일 및 임베디드
TF SavedModel	`saved_model`	TensorFlow
TF GraphDef	`pb`	TensorFlow 그래프
PaddlePaddle	`paddle`	바이두 PaddlePaddle
NCNN	`ncnn`	이동 신경망
엣지 TPU	`edgetpu`	Google 기기
TF.js	`tfjs`	브라우저 추론
MNN	`mnn`	알리바바 모바일 추론
RKNN	`rknn`	록칩 NPU
IMX	`imx`	소니 IMX500 센서
Axelera	`axelera`	액셀레라 AI 가속기
ExecuTorch	`executorch`	메타 실행기 런타임

내보내기 상태 가져오기

GET /api/exports/{exportId}

수출 취소

DELETE /api/exports/{exportId}

트랙 내보내기 다운로드

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

활동 API

계정의 활동 이벤트를 track하고 관리합니다.

활동 목록

GET /api/activity

쿼리 파라미터:

파라미터	유형	설명
`limit`	정수	페이지 크기 (기본값: 20, 최대값: 100)
`page`	정수	페이지 번호 (기본값: 1)
`archived`	boolean	`true` 아카이브 탭용, `false` 수신함용
`search`	문자열	이벤트 필드에서 대소문자 구분 없는 검색

이벤트 확인 표시

POST /api/activity/mark-seen

본문:

{
    "all": true
}

또는 특정 ID를 전달하세요:

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

이벤트 보관

POST /api/activity/archive

본문:

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

또는 특정 ID를 전달하세요:

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

휴지통 API

소프트 삭제된 리소스(30일 보존)를 관리합니다.

휴지통 목록

GET /api/trash

쿼리 파라미터:

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

항목 복원

POST /api/trash

본문:

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

항목을 영구적으로 삭제

DELETE /api/trash

본문:

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

불가역적

영구 삭제는 되돌릴 수 없습니다. 해당 리소스와 관련된 모든 데이터가 제거됩니다.

휴지통 비우기

DELETE /api/trash/empty

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

결제 API

크레딧, 구독 및 결제 수단을 관리하세요.

통화 단위

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

잔액 가져오기

GET /api/billing/balance

쿼리 파라미터:

파라미터	유형	설명
`owner`	문자열	작업 공간 소유자 사용자 이름

응답:

{
    "creditsCents": 2500,
    "plan": "free",
    "cashBalance": 25,
    "creditBalance": 0,
    "reservedAmount": 0,
    "totalBalance": 25
}

사용량 요약 가져오기

GET /api/billing/usage-summary

플랜 세부 정보, 제한 및 사용량 지표를 반환합니다.

거래 조회

GET /api/billing/transactions

거래 내역을 반환합니다(가장 최근 거래부터).

쿼리 파라미터:

파라미터	유형	설명
`owner`	문자열	작업 공간 소유자 사용자 이름

결제 세션 생성

POST /api/billing/checkout-session

본문:

{
    "amount": 25,
    "owner": "team-username"
}

필드	유형	필수	설명
`amount`	숫자	예	금액(달러)($5-$1000)
`owner`	문자열	아니요	워크스페이스 충전용 팀 사용자명 (관리자 역할 필요)

신용 구매를 위한 결제 세션을 생성합니다.

구독 결제 생성

POST /api/billing/subscription-checkout

Pro 구독 업그레이드를 위한 결제 세션을 생성합니다.

본문:

{
    "planId": "pro",
    "billingCycle": "monthly",
    "owner": "team-username"
}

필드	유형	필수	설명
`planId`	문자열	예	구독할 계획입니다.`pro`)
`billingCycle`	문자열	아니요	청구 주기: `monthly` (기본값) 또는 `yearly`
`owner`	문자열	아니요	워크스페이스 업그레이드용 팀 사용자 이름 (관리자 역할 필요)

포털 세션 생성

POST /api/billing/portal-session

구독 관리를 위한 결제 포털 URL을 반환합니다.

자동 충전

잔액이 기준 금액 이하로 떨어지면 자동으로 크레딧을 추가합니다.

자동 충전 설정 받기

GET /api/billing/auto-topup

쿼리 파라미터:

파라미터	유형	설명
`owner`	문자열	작업 공간 소유자 사용자 이름

자동 충전 설정 업데이트

PATCH /api/billing/auto-topup

본문:

{
    "enabled": true,
    "thresholdCents": 500,
    "amountCents": 2500
}

결제 방법

결제 방법 목록

GET /api/billing/payment-methods

설정 인텐트 생성

POST /api/billing/payment-methods/setup

새 결제 수단 추가를 위한 클라이언트 시크릿을 반환합니다.

기본 결제 수단 설정

POST /api/billing/payment-methods/default

본문:

{
    "paymentMethodId": "pm_123"
}

결제 정보 업데이트

PATCH /api/billing/payment-methods

본문:

{
    "name": "Jane Doe",
    "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    }
}

결제 수단 삭제

DELETE /api/billing/payment-methods/{id}

저장소 API

저장소 정보 가져오기

GET /api/storage

응답:

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

저장 공간 재계산

POST /api/storage

저장소 사용량 재계산을 트리거합니다.

업로드 API

직접 파일 업로드는 두 단계 서명된 URL 흐름을 사용합니다.

서명된 업로드 URL 받기

POST /api/upload/signed-url

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

본문:

{
    "assetType": "images",
    "assetId": "abc123",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "totalBytes": 5242880
}

필드	유형	설명
`assetType`	문자열	자산 유형: `models`, `datasets`, `images`, `videos`
`assetId`	문자열	대상 자산의 ID
`filename`	문자열	원본 파일명
`contentType`	문자열	MIME 유형
`totalBytes`	정수	파일 크기 (바이트 단위)

응답:

{
    "sessionId": "session_abc123",
    "uploadUrl": "https://storage.example.com/...",
    "objectPath": "images/abc123/my-image.jpg",
    "downloadUrl": "https://cdn.example.com/...",
    "expiresAt": "2026-02-22T12:00:00Z"
}

완료 업로드

POST /api/upload/complete

파일 업로드가 완료되었음을 플랫폼에 알리십시오. 그러면 플랫폼이 처리를 시작할 수 있습니다.

본문:

{
    "datasetId": "abc123",
    "objectPath": "datasets/abc123/images/my-image.jpg",
    "filename": "my-image.jpg",
    "contentType": "image/jpeg",
    "size": 5242880
}

API 키 API

API 키 목록

GET /api/api-keys

API 키 생성

POST /api/api-keys

본문:

{
    "name": "training-server"
}

API 키 삭제

DELETE /api/api-keys

쿼리 파라미터:

파라미터	유형	설명
`keyId`	문자열	취소할 API 키 ID

예시:

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

팀 및 멤버 API

팀, 멤버 및 초대 기능을 통해 작업 공간 협업을 관리하세요.

팀 목록

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`	전체 접근 권한(회원 관리 포함)

UI에서 역할 세부 정보는 Teams를 참조하세요.

회원 역할 업데이트

PATCH /api/members/{userId}

멤버 제거

DELETE /api/members/{userId}

소유권 이전

POST /api/members/transfer-ownership

초대장

초대 수락

POST /api/invites/accept

초대 정보 받기

GET /api/invites/info

쿼리 파라미터:

파라미터	유형	설명
`token`	문자열	초대 토큰

초대 취소

DELETE /api/invites/{inviteId}

초대장 재발송

POST /api/invites/{inviteId}/resend

API 탐색

공개 콘텐츠 검색

GET /api/explore/search

쿼리 파라미터:

파라미터	유형	설명
`q`	문자열	검색어
`type`	문자열	자원 유형: `all` (기본값), `projects`, `datasets`
`sort`	문자열	정렬 순서: `stars` (기본값), `newest`, `oldest`, `name-asc`, `name-desc`, `count-desc`, `count-asc`
`offset`	정수	페이지 매김 오프셋 (기본값: 0). 결과는 페이지당 20개 항목을 반환합니다.

GET /api/explore/sidebar

탐색 사이드바에 선별된 콘텐츠를 반환합니다.

사용자 및 설정 API

사용자 이름으로 사용자 조회

GET /api/users

쿼리 파라미터:

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

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

PATCH /api/users

본문:

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

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

GET /api/username/check

쿼리 파라미터:

파라미터	유형	설명
`username`	문자열	확인할 사용자 이름
`suggest`	bool	선택 사항: `true` 포함할 경우 제안 사항

설정

GET /api/settings
POST /api/settings

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

프로필 아이콘

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

프로필 아바타를 업로드하거나 제거하세요.

온보딩

POST /api/onboarding

온보딩 절차 완료 (데이터 지역 설정, 사용자 이름 설정).

데이터 내보내기 및 삭제를 위한 GDPR 준수 엔드포인트.

GET /api/gdpr

쿼리 파라미터:

파라미터	유형	설명
`jobId`	문자열	GDPR 작업 ID 확인

작업 상태를 반환합니다. 완료된 내보내기 작업의 경우 응답에는 downloadUrl.

흐름 내보내기 시작 또는 삭제

POST /api/gdpr

본문:

{
    "action": "export"
}

{
    "action": "delete",
    "confirmationWord": "DELETE"
}

팀 작업 공간에 대한 선택 사항:

{
    "action": "delete",
    "confirmationWord": "DELETE",
    "teamUsername": "my-team"
}

되돌릴 수 없는 작업

계정 삭제는 영구적이며 되돌릴 수 없습니다. 모든 데이터, 모델 및 배포가 삭제됩니다.

오류 코드

코드	HTTP 상태	설명
`UNAUTHORIZED`	401	유효하지 않거나 누락된 API 키
`FORBIDDEN`	403	권한 부족
`NOT_FOUND`	404	리소스를 찾을 수 없음
`VALIDATION_ERROR`	400	유효하지 않은 요청 데이터
`RATE_LIMITED`	429	요청이 너무 많습니다
`INTERNAL_ERROR`	500	서버 오류

Python

통합을 용이하게 하려면 인증, 업로드 및 실시간 메트릭 스트리밍을 자동으로 처리하는 Ultralytics Python 사용하십시오.

설치 및 설정

pip install ultralytics

설치 확인:

yolo check

패키지 버전 요구 사항

플랫폼 통합에는 ultralytics>= 8.4.14 버전이 필요합니다. 하위 버전은 플랫폼과 호환되지 않습니다.

인증

CLI 권장)환경 변수코드 내

yolo settings api_key=YOUR_API_KEY

export ULTRALYTICS_API_KEY=YOUR_API_KEY

from ultralytics import settings

settings.api_key = "YOUR_API_KEY"

플랫폼 데이터셋 사용

참조 데이터셋과 함께 ul:// URI:

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

# Train on your Platform dataset
model.train(
    data="ul://your-username/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("yolo11n.pt")

# Results automatically sync to Platform
model.train(
    data="coco8.yaml",
    epochs=100,
    project="ul://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, half=True)

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

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

유효성 검사:

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

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

웹훅

웹훅은 HTTP POST 콜백을 통해 플랫폼 이벤트를 서버에 알립니다:

이벤트	설명
`training.started`	학습 작업 시작됨
`training.epoch`	에포크 완료됨
`training.completed`	학습 완료됨
`training.failed`	학습 실패
`export.completed`	내보내기 준비 완료

엔터프라이즈 기능

엔터프라이즈 플랜에서는 사용자 지정 웹훅 엔드포인트를 사용할 수 있습니다. Python SDK용 트레이닝 웹훅은 모든 플랜에서 자동으로 작동합니다.

FAQ

대규모 결과를 페이지네이션하려면 어떻게 해야 하나요?

대부분의 엔드포인트는 limit 요청당 반환되는 결과 수를 제어하는 매개변수:

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

활동 및 휴지통 엔드포인트도 다음을 지원합니다. page 페이지 기반 페이지 매김을 위한 매개변수:

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

탐색 검색 엔드포인트는 offset 대신 page고정 페이지 크기가 20인:

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

SDK 없이 API를 사용할 수 있나요?

예, 모든 기능은 REST를 통해 이용 가능합니다. Python 실시간 메트릭 스트리밍 및 자동 모델 업로드와 같은 기능을 추가하는 편의성 래퍼입니다.

API 클라이언트 라이브러리가 있나요?

현재는 Ultralytics Python 패키지를 사용하거나 직접 HTTP 요청을 하세요. 다른 언어용 공식 클라이언트 라이브러리는 계획 중입니다.

요청 제한(Rate Limit)은 어떻게 처리해야 하나요?

다음을 사용하여 Retry-After 429 응답의 헤더를 통해 적절한 시간을 기다리도록:

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 Exception("Rate limit exceeded")

내 모델 또는 데이터셋 ID를 어떻게 찾을 수 있나요?

API를 통해 리소스를 생성할 때 리소스 ID가 반환됩니다. 플랫폼 URL에서도 확인할 수 있습니다:

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

목록 엔드포인트를 사용하여 이름으로 검색하거나 프로젝트별로 필터링하세요.

5; 1 전에 생성됨 ✏️ 5 전에 업데이트됨