コンテンツにスキップ

REST APIリファレンス

Ultralytics Platformは、データセット、モデル、トレーニング、デプロイメントへのプログラムによるアクセスを可能にする包括的な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キーを参照してください。

認証ヘッダー

すべてのリクエストにAPキーを含める:

Authorization: Bearer ul_your_api_key_here

例

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

ベースURL

すべてのAPエンドポイントは以下を使用します:

https://platform.ultralytics.com/api

レート制限

プラン1分あたりのリクエスト数1日あたりのリクエスト数
無料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)
limitint1ページあたりの項目数 (デフォルト: 20)
taskstringタスクタイプでフィルタリング

レスポンス:

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

クエリパラメータ:

パラメータ種類説明
projectIdstringプロジェクトでフィルタリング
taskstringタスクタイプでフィルタリング

モデルの取得

GET /api/models/{modelId}

モデルのアップロード

POST /api/models

マルチパートフォーム:

フィールド種類説明
fileファイルモデルの.ptファイル
projectIdstring対象プロジェクト
namestringモデル名

モデルの削除

DELETE /api/models/{modelId}

モデルをダウンロードする

GET /api/models/{modelId}/files

モデルファイル用の署名付きダウンロードURLを返します。

推論の実行

POST /api/models/{modelId}/predict

マルチパートフォーム:

フィールド種類説明
fileファイル画像ファイル
conffloat信頼度しきい値
ioufloatIoUしきい値

レスポンス:

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

デプロイメントAP

デプロイメントを一覧表示

GET /api/deployments

クエリパラメータ:

パラメータ種類説明
modelIdstringモデルでフィルタ

デプロイメントを作成

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

クエリパラメータ:

パラメータ種類説明
severitystringINFO, WARNING, ERROR
limitintエントリ数

エクスポートAP

エクスポートを一覧表示

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}

アクティビティAP

アカウントのアクティビティイベントをtrackし、管理します。

アクティビティを一覧表示

GET /api/activity

クエリパラメータ:

パラメータ種類説明
startDatestringフィルタ開始日 (ISO)
endDatestringフィルタ終了日 (ISO)
searchstringイベントメッセージ内で検索

イベントを既読にする

POST /api/activity/mark-seen

イベントをアーカイブ

POST /api/activity/archive

ゴミ箱AP

論理削除されたリソースを管理します (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の例

Platformからモデルを読み込みます:

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

Webhook

Webhookは、プラットフォームイベントをサーバーに通知します：

イベント説明
training.startedトレーニングジョブが開始されました
training.epochエポックが完了しました
training.completedトレーニングが終了しました
training.failedトレーニングが失敗しました
export.completedエクスポート準備完了

Webhookの設定はEnterpriseプランで利用可能です。

よくある質問

大量の結果をページ分割するにはどうすればよいですか？

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


📅 20日前に作成✏️ 14日前に更新
glenn-jocherLaughing-q

コメント