콘텐츠로 건너뛰기

REST API 참조

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

빠른 시작

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

# Run inference on a model
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  https://platform.ultralytics.com/api/models/MODEL_ID/predict

인증

모든 API 요청은 API 키를 통한 인증이 필요합니다.

API 키 받기

  1. 설정 > API 키로 이동합니다.
  2. 키 생성을 클릭합니다.
  3. 생성된 키를 복사합니다.

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

인증 헤더

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

Authorization: Bearer ul_your_api_key_here

예시

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

기본 URL

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

https://platform.ultralytics.com/api

속도 제한

플랜분당 요청 수일일 요청 수
무료601,000
Pro30050,000
엔터프라이즈사용자 정의사용자 정의

응답에 속도 제한 헤더가 포함됩니다:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1640000000

응답 형식

모든 응답은 JSON 형식입니다:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

오류 응답

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid dataset ID",
    "details": { ... }
  }
}

데이터셋 API

데이터 세트 목록

GET /api/datasets

쿼리 파라미터:

파라미터유형설명
page정수페이지 번호 (기본값: 1)
limit정수페이지당 항목 수 (기본값: 20)
task문자열작업 유형으로 필터링

응답:

{
    "success": true,
    "data": [
        {
            "id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "visibility": "private",
            "createdAt": "2024-01-15T10:00:00Z"
        }
    ]
}

데이터셋 가져오기

GET /api/datasets/{datasetId}

데이터셋 생성

POST /api/datasets

본문:

{
    "name": "my-dataset",
    "task": "detect",
    "description": "A custom detection dataset"
}

데이터세트 삭제

DELETE /api/datasets/{datasetId}

데이터셋 내보내기

POST /api/datasets/{datasetId}/export

NDJSON 형식 다운로드 URL을 반환합니다.

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

GET /api/datasets/{datasetId}/models

이 데이터셋을 사용하여 훈련된 모델 목록을 반환하며, 데이터셋과 해당 데이터셋으로 생성된 모델 간의 관계를 보여줍니다.

응답:

{
    "success": true,
    "data": [
        {
            "id": "model_abc123",
            "name": "experiment-1",
            "projectId": "project_xyz",
            "trainedAt": "2024-01-15T10:00:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72
            }
        }
    ]
}

프로젝트 API

프로젝트 목록

GET /api/projects

프로젝트 가져오기

GET /api/projects/{projectId}

프로젝트 생성

POST /api/projects

본문:

{
    "name": "my-project",
    "description": "Detection experiments"
}

프로젝트 삭제

DELETE /api/projects/{projectId}

모델 API

모델 목록

GET /api/models

쿼리 파라미터:

파라미터유형설명
projectId문자열프로젝트로 필터링
task문자열작업 유형으로 필터링

모델 가져오기

GET /api/models/{modelId}

모델 업로드

POST /api/models

멀티파트 폼:

필드유형설명
file파일모델 .pt 파일
projectId문자열대상 프로젝트
name문자열모델 이름

모델 삭제

DELETE /api/models/{modelId}

모델 다운로드

GET /api/models/{modelId}/files

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

추론 실행

POST /api/models/{modelId}/predict

멀티파트 폼:

필드유형설명
file파일이미지 파일
conf부동 소수점신뢰도 임계값
iou부동 소수점IoU 임계값

응답:

{
    "success": true,
    "predictions": [
        {
            "class": "person",
            "confidence": 0.92,
            "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
        }
    ]
}

학습 API

학습 시작

POST /api/training/start

본문:

{
    "modelId": "model_abc123",
    "datasetId": "dataset_xyz789",
    "epochs": 100,
    "imageSize": 640,
    "gpuType": "rtx-4090"
}

학습 상태 가져오기

GET /api/models/{modelId}/training

학습 취소

DELETE /api/models/{modelId}/training

배포 API

배포 목록

GET /api/deployments

쿼리 파라미터:

파라미터유형설명
modelId문자열모델로 필터링

배포 생성

POST /api/deployments

본문:

{
    "modelId": "model_abc123",
    "region": "us-central1",
    "minInstances": 0,
    "maxInstances": 10
}

배포 가져오기

GET /api/deployments/{deploymentId}

배포 시작

POST /api/deployments/{deploymentId}/start

배포 중지

POST /api/deployments/{deploymentId}/stop

배포 삭제

DELETE /api/deployments/{deploymentId}

메트릭 가져오기

GET /api/deployments/{deploymentId}/metrics

로그 가져오기

GET /api/deployments/{deploymentId}/logs

쿼리 파라미터:

파라미터유형설명
severity문자열INFO, WARNING, ERROR
limit정수항목 수

내보내기 API

내보내기 목록

GET /api/exports

내보내기 생성

POST /api/exports

본문:

{
    "modelId": "model_abc123",
    "format": "onnx"
}

지원되는 형식:

onnx, torchscript, openvino, tensorrt, coreml, tflite, saved_model, graphdef, paddle, ncnn, edgetpu, tfjs, mnn, rknn, imx, axelera, executorch

내보내기 상태 가져오기

GET /api/exports/{exportId}

활동 API

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

활동 목록

GET /api/activity

쿼리 파라미터:

파라미터유형설명
startDate문자열시작 날짜로 필터링 (ISO)
endDate문자열종료 날짜로 필터링 (ISO)
search문자열이벤트 메시지에서 검색

이벤트 확인 표시

POST /api/activity/mark-seen

이벤트 보관

POST /api/activity/archive

휴지통 API

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

휴지통 목록

GET /api/trash

항목 복원

POST /api/trash

본문:

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

휴지통 비우기

POST /api/trash/empty

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

결제 API

크레딧 및 구독을 관리합니다.

잔액 가져오기

GET /api/billing/balance

응답:

{
    "success": true,
    "data": {
        "cashBalance": 5000000,
        "creditBalance": 20000000,
        "reservedAmount": 0,
        "totalBalance": 25000000
    }
}

마이크로-USD

모든 금액은 정확한 회계 처리를 위해 마이크로-USD(1,000,000 = $1.00) 단위입니다.

사용량 요약 가져오기

GET /api/billing/usage-summary

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

결제 세션 생성

POST /api/billing/checkout-session

본문:

{
    "amount": 25
}

크레딧 구매($5-$1000)를 위한 Stripe 결제 세션을 생성합니다.

구독 결제 생성

POST /api/billing/subscription-checkout

Pro 구독을 위한 Stripe 결제 세션을 생성합니다.

포털 세션 생성

POST /api/billing/portal-session

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

결제 내역 가져오기

GET /api/billing/payments

Stripe의 결제 거래 내역 목록을 반환합니다.

저장소 API

저장소 정보 가져오기

GET /api/storage

응답:

{
    "success": true,
    "data": {
        "used": 1073741824,
        "limit": 107374182400,
        "percentage": 1.0
    }
}

GDPR API

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

계정 데이터 내보내기/삭제

POST /api/gdpr

본문:

{
    "action": "export"
}
작업설명
export모든 계정 데이터 다운로드
delete계정 및 모든 데이터 삭제

되돌릴 수 없는 작업

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

API 키 API

API 키 목록

GET /api/api-keys

API 키 생성

POST /api/api-keys

본문:

{
    "name": "training-server",
    "scopes": ["training", "models"]
}

API 키 삭제

DELETE /api/api-keys/{keyId}

오류 코드

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

Python

더 쉬운 통합을 위해 Ultralytics python 패키지를 사용하세요.

설치 및 설정

pip install ultralytics

설치 확인:

yolo check

패키지 버전 요구 사항

Platform 통합에는 ultralytics>=8.4.0이 필요합니다. 하위 버전은 Platform에서 작동하지 않습니다.

인증

방법 1: CLI (권장)

yolo settings api_key=YOUR_API_KEY

방법 2: 환경 변수

export ULTRALYTICS_API_KEY=YOUR_API_KEY

방법 3: 코드에서

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}/{resource-type}/{name}

Examples:
ul://john/datasets/coco-custom     # Dataset
ul://john/my-project               # Project
ul://john/my-project/exp-1         # Specific model
ul://ultralytics/yolo26/yolo26n    # Official model

플랫폼으로 푸시

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

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

웹훅

웹훅은 플랫폼 이벤트를 서버에 알립니다:

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

웹훅 설정은 엔터프라이즈 플랜에서 사용할 수 있습니다.

FAQ

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

다음을 사용합니다. page 및 limit 파라미터:

GET /api/datasets?page=2 &
limit=50

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

네, 모든 기능은 REST를 통해 사용할 수 있습니다. SDK는 편의를 위한 래퍼입니다.

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

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

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

지수 백오프 구현:

import time


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


5; 20 전에 생성됨 ✏️ 14 전에 업데이트됨
glenn-jocherLaughing-q

댓글