콘텐츠로 건너뛰기

REST API

Ultralytics 데이터셋, 모델, 훈련 및 배포에 대한 프로그래매틱 접근을 REST API 포괄적인 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

쿼리 매개변수:

파라미터유형설명
pageint페이지 번호 (기본값: 1)
limitint페이지당 항목 수 (기본값: 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을 반환합니다.

프로젝트 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문자열정보, 경고, 오류
limitint항목 수

수출 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

계정의 활동 이벤트를 추적하고 관리하세요.

활동 목록

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

정확한 회계 처리를 위해 모든 금액은 마이크로 달러(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서버 오류

SDK 지원

통합을 용이하게 하려면 Ultralytics Python 사용하십시오.

패키지 버전 요구 사항

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

pip install "ultralytics>=8.4.0"

import os

from ultralytics import YOLO

# Set API key
os.environ["ULTRALYTICS_API_KEY"] = "ul_your_key"

# Train with Platform integration
model = YOLO("yolo11n.pt")
model.train(data="ul://username/datasets/my-dataset", project="username/my-project", name="experiment-1", epochs=100)

웹훅

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

이벤트설명
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 요청을 수행하십시오. 다른 언어용 공식 클라이언트 라이브러리는 계획 중입니다.

속도 제한은 어떻게 처리하나요?

지수적 백오프 구현:

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


📅 생성 0 일 전 ✏️ 업데이트 0일 전
glenn-jocher

댓글