REST API リファレンス#

Ultralytics Platformは、データセット、画像、プロジェクト、モデル、トレーニング、エクスポート、デプロイにプログラムからアクセスするためのREST APIを提供します。

# List the datasets owned by a workspace
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/datasets/YOUR_USERNAME

API の概要#

APIは、コアとなるPlatformリソースを中心に整理されています。

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff

認証#

ほとんどのエンドポイントではAPIキーが必要です。パブリックデータセット、プロジェクト、モデルの読み取り、パブリックデータセット画像のリスト表示、パブリックモデルでの推論実行、またはExploreの検索など、パブリックコンテンツを公開するエンドポイントも匿名リクエストを受け付け、キーが提供された場合はより多くの情報を返します。

APIキーを取得する#

1. Settings > API Keysへ移動します
2. Create Keyをクリックします
3. 生成されたキーをコピーします

詳細な手順については、API Keysをご覧ください。

認証ヘッダー#

ベアラートークンとしてAPIキーを含めます:

Authorization: Bearer YOUR_API_KEY

例#

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

ベース URL#

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

https://platform.ultralytics.com/api

リソースパス#

リソースはデータベースIDではなく、PlatformのURLに表示される人間が読みやすい名前で指定されます:

• {owner} は個人のユーザー名またはチームワークスペースのハンドルです: 4〜32文字で、セグメント間に単一のハイフンを含む小文字の英数字です。
• {dataset}、{project}、{model}、および {deployment} は、同じ小文字とハイフンのパターンに従い、最大128文字です。
• {imageId} および {exportId} は、APIによって返される24文字の16進数IDです。
• PATCH を介してリソースの名前を変更すると、表示用の name とURL名が同時に変更され、レスポンスには追跡を続けられるように現在のURL名が返されます。

レート制限#

APIは、APIキーごとにスライディングウィンドウ制限を適用します。各ルートはいずれかのカテゴリに属し、各カテゴリには独立したカウンターがあるため、20件の予測リクエストによってデフォルトの許容量が消費されることはありません。

課金チェックアウトやチーム管理などのブラウザ専用のPlatformルートには、APIキーのトラフィックには適用されない独自の制限があります。

スロットルされた場合、APIはヘッダーとJSONボディの両方を含む 429 を返します:

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

{
    "error": "Rate limit exceeded",
    "retryAfter": 12,
    "resetAt": "2026-02-21T12:34:56.000Z"
}

専用エンドポイント (無制限)#

デプロイ自体の serviceUrl を直接呼び出す場合（例：https://predict-abc123.run.app/predict）、専用エンドポイントはPlatformのAPIキーレート制限の対象外となります。スループットは、デプロイされたサービスの構成によって異なります。

レスポンスフォーマット#

成功レスポンス#

レスポンスはリソース固有のフィールドを持つJSONオブジェクトです。汎用的なエンベロープはありません。リストのエンドポイントはカウントとともに名前付きのコレクションを返し、ミューテーションは変更された識別子を返します。

{
    "datasets": [{ "id": "65f1c0a2b3d4e5f601234567", "owner": "acme-vision", "dataset": "warehouse" }],
    "total": 1,
    "region": "us"
}

データを伴うレスポンスには、そのワークスペースのストレージ領域である region（us、eu、または ap）も含まれます。

エラーレスポンス#

すべてのエラーレスポンスは、error メッセージを持つJSONオブジェクトです:

{
    "error": "Dataset not found"
}

ページネーション#

ページネーションのスタイルはコレクションによって異なります:

Datasets API#

YOLOモデルのトレーニング用に、ラベル付けされた画像データセットを作成、参照、管理します。データセットのドキュメントを参照してください。

データセット一覧#

GET /api/datasets/{owner}

Python SDK: client.datasets.list(owner)

所有者のパブリックデータセットと、キーでそのワークスペースを表示できる場合のプライベートデータセットを返します。

クエリパラメータ:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets/acme-vision?limit=10&includeSamples=false"

レスポンス:

{
    "datasets": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "owner": "acme-vision",
            "dataset": "warehouse",
            "name": "Warehouse",
            "task": "detect",
            "visibility": "private",
            "imageCount": 1000,
            "classCount": 2,
            "classNames": ["person", "forklift"],
            "splits": { "train": 800, "val": 200, "test": 0, "labeled": 1000 },
            "annotationCount": 5400,
            "starCount": 3,
            "isStarred": false,
            "status": "ready",
            "createdAt": "2026-01-15T10:00:00Z",
            "updatedAt": "2026-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

データセットを取得#

GET /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.retrieve(owner, dataset)

dataset キーの下に完全なデータセットオブジェクトを返します。これには、classNames、splits、versions、source、およびユーザー定義の metadata オブジェクトが含まれます。

データセットを作成#

POST /api/datasets

Python SDK: client.datasets.create(dataset=..., name=...)

ボディ:

{
    "dataset": "warehouse",
    "name": "Warehouse",
    "task": "detect",
    "description": "Forklift and pedestrian safety dataset",
    "classNames": ["person", "forklift"],
    "visibility": "private",
    "metadata": { "location": "factory-1", "reviewed": true },
    "owner": "acme-vision"
}

レスポンス（201）:

{
    "id": "65f1c0a2b3d4e5f601234567",
    "owner": "acme-vision",
    "dataset": "warehouse",
    "region": "us"
}

データセットを更新#

PATCH /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.update(owner, dataset)

ボディ（部分更新）:

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

受け付けられるフィールド: name、description、visibility、metadata、tags、classNames、classColors、format、task、license、iconColor、iconLetter、および starred。カスタムメタデータをクリアするには、空の metadata オブジェクト（{}）を送信します。メタデータキーは128文字に制限され、シリアル化されたオブジェクトは500,000文字に制限されます。

レスポンス:

{
    "success": true,
    "dataset": "warehouse-safety"
}

名前を変更するとURL名が変更されるため、後続のリクエストには返された dataset の値を使用してください。

データセットを削除#

DELETE /api/datasets/{owner}/{dataset}

Python SDK: client.datasets.delete(owner, dataset)

データセットをtrashに移動します。30日間は復元可能です。

データセットをクローンする#

POST /api/datasets/{owner}/{dataset}/clone

Python SDK: client.datasets.clone(owner, dataset)

アクセス可能なデータセットを、その画像とラベルとともに、個人ワークスペースまたはチームワークスペースにコピーします。

オプションのボディ（すべてのフィールドはオプション）:

{
    "dataset": "warehouse-copy",
    "name": "Warehouse Copy",
    "description": "Cloned for experimentation",
    "visibility": "private",
    "license": "CC-BY-4.0",
    "owner": "acme-vision"
}

レスポンス（201）: id、owner、dataset、name、imageCount、classCount、および region。接続されたストレージソースにバックアップされているデータセットは、ファイルがコピーされないため 409 を返します。

データセットのエクスポートをダウンロードする#

GET /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.export(owner, dataset)

署名付きのNDJSONダウンロードURLを返します。データセットの現在の状態をエクスポートするには v を省略し、生成されてから何も変更されていない場合はキャッシュされたエクスポートを再利用します。

クエリパラメータ:

レスポンス:

{
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "cached": true
}

特定のバージョンをリクエストすると、cachedの代わりにdownloadUrlとversionが返されます。

データセットバージョンを作成#

POST /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.create_export(owner, dataset)

データセットの変更不可能な番号付きスナップショットを作成し、そのNDJSONエクスポートを保存します。エディターアクセスが必要です。

ボディ（オプション）：

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

レスポンス:

{
    "version": 3,
    "downloadUrl": "https://storage.googleapis.com/...&signature=...",
    "reused": false
}

前回のバージョンからデータセットに変更がなく、そのスナップショットが代わりに返された場合、reusedはtrueになります。

バージョン説明を更新#

PATCH /api/datasets/{owner}/{dataset}/export

Python SDK: client.datasets.update_export(owner, dataset, version=..., description=...)

ボディ:

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

レスポンス： {"ok": true}

データセットバージョンの復元#

POST /api/datasets/{owner}/{dataset}/restore

Python SDK: client.datasets.restore(owner, dataset, version=...)

画像バイトをコピーせずに、保存されたバージョンから画像、アノテーション、およびクラスを再構築します。

ボディ:

{
    "version": 2
}

レスポンス： {"version": 2, "imageCount": 1000}

データセット統計の取得#

GET /api/datasets/{owner}/{dataset}/class-stats

Python SDK: client.datasets.class_stats(owner, dataset)

クラスごとのアノテーション数、画像およびアノテーションのヒストグラム、ヒートマップを返します。大規模なデータセットはサンプリングされ、その場合sampleSizeには何枚の画像が寄与したかが報告されます。

レスポンス（省略版）：

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120, "size": 1 }],
        "heightHistogram": [{ "bin": 480, "count": 95, "size": 1 }],
        "pointsHistogram": [{ "bin": 4, "count": 200, "size": 1 }],
        "formatDistribution": { "jpg": 900, "png": 100 },
        "fileSizeHistogram": [{ "bin": 250000, "count": 300, "size": 50000 }],
        "objectsPerImageHistogram": [{ "bin": 5, "count": 210, "size": 1 }],
        "bboxWidthHistogram": [{ "bin": 120, "count": 340, "size": 20 }],
        "bboxHeightHistogram": [{ "bin": 90, "count": 300, "size": 20 }]
    },
    "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", "forklift"],
    "cached": true,
    "sampleSize": null
}

クラスの管理#

クラスの統合（アノテーションをターゲットクラスに再割り当てした後、ソースを削除します）：

POST /api/datasets/{owner}/{dataset}/classes/merge

Python SDK: client.datasets.merge_classes(owner, dataset, source_class_ids=..., target_class_id=...)

{
    "sourceClassIds": [2, 4],
    "targetClassId": 1
}

クラスの削除（アノテーションが削除され、残りのクラスIDが繰り上げられます）：

POST /api/datasets/{owner}/{dataset}/classes/delete

Python SDK: client.datasets.delete_classes(owner, dataset, class_ids=...)

{
    "classIds": [2, 4]
}

どちらの操作も、success、更新されたclassNamesとclassColors、および変更内容のサマリー（mergedClassIdsとtargetClassId、またはdeletedClassIdsとdeletedAnnotations）を返します。

スプリットの再分配#

POST /api/datasets/{owner}/{dataset}/splits/redistribute

Python SDK: client.datasets.redistribute_splits(owner, dataset, train=..., val=..., test=...)

分割間で画像をランダムに再割り当てします。3つのパーセンテージの合計は100である必要があります。

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

レスポンス： success、結果のsplitsのカウント、およびmodified（移動された画像の数）。

データセットの埋め込み（Embeddings）#

GET /api/datasets/{owner}/{dataset}/embeddings
POST /api/datasets/{owner}/{dataset}/embeddings
DELETE /api/datasets/{owner}/{dataset}/embeddings

Python SDK: client.datasets.embeddings(owner, dataset)、client.datasets.create_embeddings(owner, dataset)、client.datasets.delete_embeddings(owner, dataset)

GETは解析サマリー（analyzedAt、embeddingsCount、latestImageAt、activeJob）を返します。POSTは埋め込み解析をキューに入れ、jobIdを含む202を返します。DELETEはアクティブなジョブをキャンセルし、キャンセルされたジョブIDまたはnullを返します。

画像クラスタリング#

GET /api/datasets/{owner}/{dataset}/images/clustering

Python SDK: client.datasets.clustering(owner, dataset)

完了した分析からのUMAP 2Dレイアウトを返し、offsetとlimit（デフォルトおよび最大50,000）でページ分割されます。各エントリには、id、umapX、umapY、split、classIds、width、height、bytes、labelCount、およびmissingが含まれます。

データセットでトレーニングされたモデルのリスト表示#

GET /api/datasets/{owner}/{dataset}/models

Python SDK: client.datasets.models(owner, dataset)

レスポンス:

{
    "models": [
        {
            "id": "65f1c0a2b3d4e5f601234599",
            "owner": "acme-vision",
            "project": "inspection",
            "model": "v3",
            "name": "v3",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "metrics": { "mAP50": 0.85, "mAP50-95": 0.72, "precision": 0.88, "recall": 0.81 },
            "startedAt": "2026-01-14T22:00:00Z",
            "completedAt": "2026-01-15T10:00:00Z",
            "createdAt": "2026-01-14T21:55:00Z"
        }
    ],
    "count": 1
}

データセット画像のリスト表示#

GET /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.images(owner, dataset)

クエリパラメータ:

レスポンス:

{
    "images": [
        {
            "id": "65f1c0a2b3d4e5f601234567",
            "hash": "9f2c1d4b6a8e0f3c5d7b9a1e2f4c6d8b",
            "ext": "jpg",
            "name": "aisle-04.jpg",
            "thumbnailUrl": "https://storage.googleapis.com/...&signature=...",
            "width": 1920,
            "height": 1080,
            "split": "train",
            "labelCount": 6,
            "bytes": 284213,
            "error": null
        }
    ],
    "total": 1000,
    "hasMore": true,
    "classes": ["person", "forklift"],
    "errorCount": 0,
    "nextCursor": "65f1c0a2b3d4e5f601234567"
}

選択した画像の取得#

POST /api/datasets/{owner}/{dataset}/images

Python SDK: client.datasets.selected_images(owner, dataset, image_ids=...)

最大1,000個の指定された画像IDに対して同じ画像形状を返し、リスト操作と同じフィルターおよびURLクエリパラメータを受け入れます。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

データセットデータの取り込み#

POST /api/datasets/{owner}/{dataset}/ingest

Python SDK: client.datasets.ingest(owner, dataset, body=...)

完了したアップロード、リモートアーカイブ、または接続されたストレージソースを既存のデータセットに処理します。ソースを正確に1つ指定してください：

アップロードセッションは、POST /api/upload/signed-urlに渡されたassetIdによってデータセットにバインドされ、取り込みでは異なるデータセットに属するセッションが拒否されます。

ボディ（アップロード済みアーカイブ）:

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

ボディ（リモートアーカイブまたはNDJSON）:

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

ボディ（後続の取り込みでのラベルのインポート）：

{
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "forklift", "background": null }
}

ボディ（画像ごとのメタデータの添付）：

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

メタデータキーは、フォルダーを含め、アーカイブ内の正規化されたパスと一致する必要があります。NDJSONインポートの場合、各レコードは独自のmetadataオブジェクトを持つことができ、これが一致するimageMetadataエントリよりも優先されます。アーカイブパスは1,024文字、トップレベルのメタデータキーは128文字、各メタデータオブジェクトおよびimageMetadataマップ全体は500,000シリアル化文字に制限されています。

レスポンス（201）:

{
    "jobId": "65f1c0a2b3d4e5f6012345aa",
    "status": "queued"
}

graph LR
    A[POST /api/datasets]:::start --> B[POST /api/upload/signed-url]:::proc
    B --> C[PUT archive to signed URL]:::proc
    C --> D[POST /api/upload/complete]:::proc
    D --> E["POST /api/datasets/{owner}/{dataset}/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

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
owner, dataset = "acme-vision", "warehouse"
dataset_id = "65f1c0a2b3d4e5f601234567"  # id returned by POST /api/datasets
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/{owner}/{dataset}/ingest",
    headers=headers,
    json={
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

画像API#

24文字の画像IDを使用して、データセット画像の検査、アノテーション付与、移動、および削除を行います。アノテーションのドキュメントを参照してください。

画像の取得#

GET /api/images/{imageId}

Python SDK: client.images.retrieve(image_id)

metadata（カスタム、ユーザー定義）、properties（ファイル名、ハッシュ、寸法、分割、カウント、タイムスタンプ）、labels、およびデータセットのclassNamesを返します。

画像の更新#

PATCH /api/images/{imageId}

Python SDK: client.images.update(image_id, body=...)

アノテーションまたはカスタムメタデータのいずれかを置き換えます。両方ではなく、2つの形状のうちの1つを送信してください。

ボディ（アノテーション）：

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

ボディ（メタデータ）：

{
    "metadata": { "location": "strasbourg", "reviewed": true }
}

画像を削除#

DELETE /api/images/{imageId}

Python SDK: client.images.delete(image_id)

1つの画像とそのアノテーションを完全に削除します。

画像の自動アノテーション#

POST /api/images/{imageId}/predict

Python SDK: client.images.predict(image_id, model_id=...)

画像に対してYOLO推論を実行し、予測されたアノテーションを返します。それらは保存されません。結果に満足したら、PATCH /api/images/{imageId}を使用して結果を書き戻してください。

レスポンス： success、predictions（アノテーションオブジェクト）、modelUsed、およびinferenceTime。クラスがデータセットと一致しないモデルは、422を返します。

画像のバルク移動#

PATCH /api/images/bulk

Python SDK: client.images.update_bulk(image_ids=..., split=...)

最大1,000枚の画像をあるデータセットから別の分割に移動します。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "split": "val",
    "conflictPolicy": "skip"
}

ファイル名またはコンテンツの競合が発生した場合は、skip、keep_both、またはreplaceのバスケット全体のconflictPolicyを選択するまで、409が返されます。レスポンスには、modifiedCount、skippedCount、およびtargetSplitが報告されます。

画像のバルク削除#

DELETE /api/images/bulk

Python SDK: client.images.delete_bulk(image_ids=...)

{
    "imageIds": ["65f1c0a2b3d4e5f601234567", "65f1c0a2b3d4e5f601234568"]
}

単一のデータセットから最大1,000枚の画像を削除し、deletedCountおよびdeletedImageIdsを返します。

署名付き画像URLを取得#

POST /api/images/urls

Python SDK: client.images.urls(image_ids=...)

1つのデータセットから最大100個の画像IDの一時的な署名付きURLを返します。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"]
}

レスポンス： urlsおよびthumbnails（どちらも画像IDでキー付けされています）。

Projects API#

モデルをプロジェクトに整理します。各モデルは1つのプロジェクトに属します。プロジェクトのドキュメントを参照してください。

プロジェクト一覧を取得#

GET /api/projects/{owner}

Python SDK: client.projects.list(owner)

クエリパラメータ:

プロジェクトを取得#

GET /api/projects/{owner}/{project}

Python SDK: client.projects.retrieve(owner, project)

projectオブジェクト、モデルごとのサマリー（ステータス、メトリクス、エポック、重み、トレーニング引数）のmodels配列、およびisOwnerを返します。

プロジェクトを作成#

POST /api/projects

Python SDK: client.projects.create(project=..., name=...)

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

レスポンス（201）： id、owner、project、region。

プロジェクトを更新#

PATCH /api/projects/{owner}/{project}

Python SDK: client.projects.update(owner, project)

受け入れられるフィールド：name、description、visibility、metadata、tags、license、archived、iconColor、iconLetter、viewPreferences、およびstarred。

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

クリアするには、空のmetadataオブジェクト（{}）を送信します。プロジェクトメタデータには、データセットメタデータと同じ128文字のキーおよび500,000文字のシリアル化オブジェクト制限が適用されます。

プロジェクトを削除#

DELETE /api/projects/{owner}/{project}

Python SDK: client.projects.delete(owner, project)

プロジェクトとそのモデルをゴミ箱に移動し、cascadedModelsを返します。

プロジェクトのクローン#

POST /api/projects/{owner}/{project}/clone

Python SDK: client.projects.clone(owner, project)

アクセス可能なプロジェクトと、その完了したモデルをクローンします。オプションのボディでは、project、name、description、visibility、license、および宛先のownerを受け入れます。

Models API#

トレーニング済みYOLOモデルの管理（メトリクスの表示、重みのダウンロード、推論の実行、トレーニングの監視）。モデルのドキュメントを参照してください。

プロジェクト内のモデルのリスト表示#

GET /api/models/{owner}/{project}

Python SDK: client.models.list(owner, project)

クエリパラメータ:

モデルの取得#

GET /api/models/{owner}/{project}/{model}

Python SDK: client.models.retrieve(owner, project, model)

クエリパラメータ:

デフォルトのレスポンスには、modelオブジェクト（ステータス、タスク、メトリクス、trainArgs、trainResults、classNames、computeCost、metadataなど）に加えて、isOwnerが含まれます。

モデルの作成#

POST /api/models

Python SDK: client.models.create(body=...)

重みを添付したりトレーニングしたりできる、未トレーニングのモデルレコードを作成します。

レスポンス（201）： id、owner、project、model、region。

モデルの更新#

PATCH /api/models/{owner}/{project}/{model}

Python SDK: client.models.update(owner, project, model)

受け入れられるフィールドには、name、description、color、metadata、status、license、datasetSlug、trainArgs、trainResults、epochs、bestEpoch、bestFitness、version、trainingError、およびstarredが含まれます。

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

カスタムのmetadataは、trainArgs、environment、trainResultsなどのトレーニング所有のフィールドとは別であり、データセットメタデータと同じサイズ制限を使用します。

モデルの削除#

DELETE /api/models/{owner}/{project}/{model}

Python SDK: client.models.delete(owner, project, model)

モデルを trash に30日間移動します。

モデルファイルのダウンロード#

GET /api/models/{owner}/{project}/{model}/files

Python SDK: client.models.files(owner, project, model)

モデルの重みに対する有効期間の短い署名付きURLを返します。

{
    "files": [
        {
            "name": "best.pt",
            "size": 6534127,
            "downloadUrl": "https://storage.googleapis.com/...&signature=..."
        }
    ]
}

モデルをクローンする#

POST /api/models/{owner}/{project}/{model}/clone

Python SDK: client.models.clone(owner, project, model, project_body=...)

アクセス可能なモデルを既存のプロジェクトにコピーします。

{
    "owner": "acme-vision",
    "project": "inspection",
    "model": "v3-copy",
    "name": "V3 Copy",
    "description": "Cloned from a public model"
}

推論を実行します#

POST /api/models/{owner}/{project}/{model}/predict

Python SDK: client.models.predict(owner, project, model, body=...)

パブリックモデルは認証なしで予測を実行できます。プライベートおよび共有モデルでは、親プロジェクトへのアクセス権を持つAPIキーが必要です。

Multipart Form:

file または source を指定します。深度モデルでは、深度マップのPNG量子化を選択するために bits (8、12、または 16) も受け付けます。サービスの入力制限を超えるリクエストは 413 を返します。

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

レスポンス:

images の各エントリには、shape、speed、results が含まれており、高密度予測タスクの場合は semantic_mask または depth のPNGペイロードが含まれます（深度値は pixel × max / divisor であり、デフォルトの8ビットマップの場合は除数255、bits が12または16の場合は65535です）。metadata オブジェクトには、画像数、関数タイミング、タスク、およびサービスのバージョンがレポートされます。内部モデルパスが返されることはありません。

{
    "images": [
        {
            "shape": [1080, 1920],
            "speed": { "preprocess": 2.1, "inference": 12.4, "postprocess": 1.3 },
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeAlive": 184.2,
        "functionTimeCall": 0.31,
        "task": "detect",
        "version": { "ultralytics": "8.4.120" }
    }
}

学習の進行状況を確認する#

GET /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.training(owner, project, model)

ステータス、エポックの進行状況、タイミング、計算詳細、学習引数、エポック指標、および安全なエラー詳細を含む job を返します。モデルが一度も学習されていない場合は null を返します。パブリックプロジェクト内のモデルは認証なしで読み取り可能です。

トレーニングのキャンセル#

DELETE /api/models/{owner}/{project}/{model}/training

Python SDK: client.models.delete_training(owner, project, model)

実行中のコンピュートインスタンスを終了し、ジョブをキャンセル済みとしてマークします。学習がアクティブでなくなった場合に 409 を返します。

Training API#

クラウドGPUでYOLOの学習を開始し、リアルタイムで進捗を監視します。Cloud Training documentation を参照してください。

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

GPU可用性の取得#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

GPU IDをキーとする現在の在庫状況を返します。パブリックかつ未認証です。管理された学習キャパシティを含めるには、APIキーが必要な managed=true を渡してください。

トレーニングの開始#

POST /api/training/start

Python SDK: client.training.start(model_id=..., train_args=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "gpuType": "rtx-4090",
    "trainArgs": {
      "model": "yolo26n.pt",
      "data": "ul://acme-vision/datasets/warehouse",
      "epochs": 100,
      "imgsz": 640,
      "batch": 16
    }
  }' \
  https://platform.ultralytics.com/api/training/start

レスポンス:

{
    "modelId": "65f1c0a2b3d4e5f601234599",
    "status": "starting",
    "gpuType": "rtx-4090",
    "estimatedCost": { "pricePerHour": 0.69, "gpuMemoryGb": 24 },
    "billing": {
        "estimatedCostCents": 138,
        "estimatedCostDisplay": "$1.38",
        "balanceCents": 2500
    }
}

クレジット残高が低すぎる場合は 402 が返され、要求されたGPUに対して利用可能なキャパシティがない場合は 503 が返されます。

エクスポートAPI#

エッジデプロイメント向けに、ONNX、TensorRT、CoreML、LiteRTなどの最適化されたフォーマットにモデルを変換します。Deploy documentation を参照してください。

エクスポート一覧#

GET /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.list(owner, project, model)

クエリパラメータ:

エクスポート作成#

POST /api/models/{owner}/{project}/{model}/exports

Python SDK: client.exports.create(owner, project, model, format=...)

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "onnx", "args": {"imgsz": 640, "quantize": 16}}' \
  https://platform.ultralytics.com/api/models/acme-vision/inspection/v3/exports

レスポンス（201）： id、format、status（queued または running）、gpuType、region。すでに実行中の同等のエクスポートは 409 を返します。

サポートされている形式:

以下の共有エクスポート表の format 引数を使用してください。PyTorchはソースフォーマットであり、APIのエクスポートターゲットではありません。

エクスポートステータスの取得#

GET /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.retrieve(owner, project, model, export_id)

status、format、args、gpuType、タイムスタンプ、および完了時には size、downloadUrl、downloadFilename を含む file オブジェクトを持つ export オブジェクトを返します。

エクスポートのキャンセルまたは削除#

DELETE /api/models/{owner}/{project}/{model}/exports/{exportId}

Python SDK: client.exports.delete(owner, project, model, export_id)

アクティブなエクスポートをキャンセルするか、完了したエクスポートとそのファイルを削除します。レスポンスには、実行されたアクションがレポートされます。

{
    "success": true,
    "action": "cancelled"
}

Deployments API#

ヘルスチェックとモニタリングを備えた専用の推論エンドポイントにモデルをデプロイします。Endpoints documentation を参照してください。

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

Python SDK: client.deployments.list(owner)

クエリパラメータ:

匿名ユーザーは1つのパブリックモデルでフィルタリングする必要があります。ワークスペース全体をリスト表示するには認証が必要です。

デプロイメントの作成#

POST /api/deployments/{owner}

Python SDK: client.deployments.create(owner, project=..., model=..., deployment=..., name=..., region=...)

ボディ:

{
    "project": "inspection",
    "model": "v3",
    "deployment": "edge-1",
    "name": "Edge 1",
    "region": "us-central1"
}

レスポンス（201）： id、deployment、status（creating）、message、および region。

デプロイメントの取得#

GET /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.retrieve(owner, deployment)

status、statusMessage、region、serviceUrl、および resources を含む deployment オブジェクトを返します。

デプロイメントの開始、停止、または置換#

PATCH /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.update(owner, deployment, body=...)

単一の action フィールドで操作を選択します：

{ "action": "start" }

置換を行うと、デプロイメントID、リージョン、およびエンドポイントURLを維持したまま新しいリビジョンがロールアウトされます。ロールアウトが失敗した場合、既存のリビジョンはライブ状態のまま維持されます。置換モデルは、キーでアクセスできる重みを持つ完了済みのモデルである必要があります。完了した操作は、status ready または stopped を伴う 200 を返します。まだロールアウト中の操作は、deploying または stopping を伴う 202 を返します。

デプロイメントの削除#

DELETE /api/deployments/{owner}/{deployment}

Python SDK: client.deployments.delete(owner, deployment)

推論エンドポイントを完全に削除します。

ヘルスチェック#

GET /api/deployments/{owner}/{deployment}/health

Python SDK: client.deployments.health(owner, deployment)

エンドポイントにpingを送信してウォームアップし、healthy、latencyMs、およびアップストリームの status コードを返します。

デプロイメントでの推論の実行#

POST /api/deployments/{owner}/{deployment}/predict

Python SDK: client.deployments.predict(owner, deployment, body=...)

画像または動画を専用エンドポイントにルーティングします。リクエストとレスポンスの契約は model inference に一致します。

Multipart Form:

メトリクスの取得#

GET /api/deployments/{owner}/{deployment}/metrics

Python SDK: client.deployments.metrics(owner, deployment)

クエリパラメータ:

完全なレスポンスには、summary（リクエスト合計、エラー率、平均およびp50/p95/p99レイテンシ）と timeSeries（リクエスト、エラー、レイテンシ、CPU、メモリ、インスタンス数）が含まれます。スパークラインのレスポンスは、requests24h、totalRequests、errorRate、および avgLatencyMs を返します。

ログの取得#

GET /api/deployments/{owner}/{deployment}/logs

Python SDK: client.deployments.logs(owner, deployment)

クエリパラメータ:

ゴミ箱API#

論理削除されたプロジェクト、データセット、およびモデルの表示、復元、および完全削除を行います。アイテムは30日後に自動的にパージされます。Trash documentation を参照してください。

ゴミ箱一覧#

GET /api/trash

Python SDK: client.lifecycle.trash()

クエリパラメータ:

レスポンスには、items（それぞれ daysRemaining を含む）、total、page、limit、totalPages、およびタイプ別の合計を含む summary が含まれます。

アイテムの復元#

POST /api/trash

Python SDK: client.lifecycle.restore(id=..., type=...)

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

プロジェクトを復元すると、それと一緒にゴミ箱に入れられたモデルも復元され、restoredModels としてレポートされます。

完全削除#

DELETE /api/trash

Python SDK: client.lifecycle.delete_trash(body=...)

1つのアイテムを削除する：

{
    "id": "65f1c0a2b3d4e5f601234567",
    "type": "dataset"
}

またはゴミ箱全体を空にする：

{
    "all": true
}

レスポンスには deletedCount がレポートされ、該当する場合はさらに cascadedModels および survivingDeployments がレポートされます。

アップロードAPI#

署名付きURLを使用して、ファイルをクラウドストレージに直接アップロードします。モデルのアップロードを完了すると重みが添付され、データセットアーカイブのアップロードを完了するとセッションが記録されます。その後、そのセッションを dataset ingest に渡します。Data documentation を参照してください。

署名付きアップロードURLの取得#

POST /api/upload/signed-url

Python SDK: client.upload.signed_url(body=...)

ボディ:

{
    "assetType": "datasets",
    "assetId": "65f1c0a2b3d4e5f601234567",
    "filename": "warehouse.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

レスポンス:

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

宣言した同じ Content-Type を使用して、PUT リクエストにより uploadUrl にファイルをアップロードします。

アップロードの完了#

POST /api/upload/complete

Python SDK: client.upload.complete(session_id=...)

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

レスポンス： success、および size と contentType を持つ file オブジェクト。モデルの場合はこれにより重みが添付され、データセットアーカイブの場合は、次に ingest を呼び出して処理を開始します。

ストレージ統合API#

読み取り専用のGoogle Cloud Storage、Amazon S3、またはAzure Blob Storageアカウントを接続し、データセットソースとして参照します。Integrations documentation を参照してください。

統合のリスト表示#

GET /api/integrations/buckets

Python SDK: client.storage_integrations.list()

integrations を返します。各エントリには id、provider、credentialIdentity、targets、および createdAt が含まれます。資格情報が返されることはありません。

ロケーションの検出#

POST /api/integrations/buckets/discover

Python SDK: client.storage_integrations.discover(body=...)

保存せずに、提供された資格情報で読み取り可能なバケットまたはコンテナをリスト表示します。

{
    "provider": "gcs",
    "credentials": {
        "client_email": "svc@project.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...",
        "project_id": "my-project"
    }
}

レスポンス： {"targets": ["my-bucket", "another-bucket"]}

ストレージの接続#

POST /api/integrations/buckets

Python SDK: client.storage_integrations.create(body=...)

検出と同じ資格情報の形状に加え、1〜50個のバケットまたはコンテナ名の必須の targets 配列。保存された統合とともに 201 を返します。一時的なS3資格情報（ASIA アクセスキー）は拒否されます。

オブジェクトの参照#

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

Python SDK: client.storage_integrations.objects(id, target=...)

クエリパラメータ:

entries（各 kind は folder または file）、および次のページ用のオプションの cursor を返します。

ストレージの切断#

DELETE /api/integrations/buckets/{id}

Python SDK: client.storage_integrations.delete(id)

プロバイダーデータを削除せずに、保存された資格情報を削除します。接続されたデータセットは表示されたままになりますが、同じストレージアカウントが再接続されるまでファイルは利用できないままになります。ワークスペース管理者アクセスが必要です。

データセットインポートAPI#

サードパーティサービスからデータセットをインポートします。Roboflow integration を参照してください。

Roboflow インポートをプレビューする#

POST /api/integrations/roboflow/preview

Python SDK: client.datasets.preview_roboflow(api_key=...)

Roboflow API キーをインポート計画に解決します：ワークスペースの詳細、インポートされる newDatasets、スキップ・未対応・未解決のプロジェクトの数 bytesTotal、および storage の余裕容量。Roboflow API キーは本文から読み取られ、永続化されません。

{
    "apiKey": "ROBOFLOW_API_KEY"
}

Roboflowからのインポート#

POST /api/integrations/roboflow/import

Python SDK: client.datasets.import_roboflow(api_key=..., items=...)

プレビューによって返されたアイテムを使用して、選択された最大 500 件の Roboflow プロジェクトバージョンに対する取り込みジョブをキューに入れます。

{
    "apiKey": "ROBOFLOW_API_KEY",
    "items": [
        {
            "workspace": "my-workspace",
            "projectId": "warehouse-safety",
            "projectName": "Warehouse Safety",
            "projectType": "object-detection",
            "latestVersion": 4
        }
    ]
}

レスポンス (201)： imported、failed、および skipped 配列。インポートにはストレージの余裕容量が必要であり、各データセットはプランごとのインポートあたりサイズ制限に収まる必要があります。

アカウント API#

Platform アカウント、キー、ストレージ、および公開プロフィールを検査します。設定ドキュメント を参照してください。

アカウントの概要#

GET /api/account/summary

Python SDK: client.account.summary()

キーを発行したワークスペースのプラン、クレジット残高、およびリソース数を返します。

{
    "username": "acme-vision",
    "name": "Acme Vision",
    "accountType": "team",
    "plan": "pro",
    "creditsCents": 2500,
    "counts": { "projects": 4, "datasets": 7, "models": 21 },
    "teams": []
}

APIキーの一覧表示#

GET /api/api-keys

Python SDK: client.account.api_keys()

キーのワークスペースの keys と keyId、name、keyPrefix、および createdAt を返します。API キーで認証されたリクエストはメタデータのみを受信します。キーの完全な値は、Platform UI の 設定 > API キー（キーの作成と取り消しも行う場所）でワークスペースの所有者に表示されます。

ストレージ使用量を確認する#

GET /api/storage

Python SDK: client.account.storage()

クエリパラメータ:

レスポンス:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 107374182400, "percent": 1.0 },
        "datasets": { "current": 536870912, "limit": 107374182400, "percent": 0.5 }
    },
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "65f1c0a2b3d4e5f601234567",
                "name": "Warehouse",
                "slug": "warehouse",
                "sizeBytes": 536870912,
                "type": "dataset"
            }
        ]
    },
    "region": "us",
    "username": "acme-vision",
    "updatedAt": "2026-01-15T10:00:00Z"
}

公開ユーザープロフィールを取得する#

GET /api/users

Python SDK: client.account.profile(username=...)

クエリパラメータ:

公開の user プロフィールを followerCount とともに返し、認証された呼び出し元に対しては isFollowed を返します。

ユーザーをフォローまたはフォロー解除する#

PATCH /api/users

Python SDK: client.account.follow(username=..., followed=...)

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

レスポンス： followed および更新された followerCount。

請求API#

プランの使用量とクレジット元帳を確認します。請求ドキュメント を参照してください。

プランと使用量を表示する#

GET /api/billing/usage-summary

Python SDK: client.billing.usage_summary()

plan（ID、ステータス、請求サイクル、期間終了）、metrics（ストレージ制限と使用量）、trainingCredit、features、creditsCents、およびシート数を返します。

トランザクションを表示する#

GET /api/billing/transactions

Python SDK: client.billing.transactions()

クエリパラメータ:

各トランザクションには、id、type（purchase、training、monthly_grant、または refund など）、amountCents、balanceAfter、createdAt、オプションの receiptUrl、およびトレーニング料金のモデルコンテキストが含まれます。内部の請求詳細は一切返されません。

探索API#

コミュニティによって共有された公開プロジェクトやデータセットを検索します。探索ドキュメント を参照してください。

公開コンテンツの検索#

GET /api/explore/search

Python SDK: client.explore.search()

クエリパラメータ:

レスポンス： projects、datasets、および hasMore。

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

Python SDK#

ultralytics-platform は、OpenAPI コントラクトから生成された型付き Python クライアントであり、エンドポイントごとに 1 つのメソッド (client.datasets.list、client.models.predict、client.exports.create、...) を持ちます。すべてのメソッドはパスパラメータを位置引数として受け入れ、その他の入力はキーワード引数として、またオプションのリクエストごとの timeout および extra_headers を受け入れます。

pip install "ultralytics-platform>=0.1.5" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    dataset = client.datasets.retrieve("acme-vision", "warehouse")
    images = client.datasets.images("acme-vision", "warehouse", limit=10)
    export = client.exports.create("acme-vision", "inspection", "v3", format="onnx")

AsyncPlatform は async/await コードに対して同じリソースツリーを公開し、失敗したレスポンスは APIError を status_code、body、および解析された json と共に発生させ、接続失敗は APIConnectionError を発生させます。完全な README については、SDK リポジトリ を参照してください。

Pythonの統合#

トレーニングおよび推論ワークフローには、認証、アップロード、およびリアルタイムメトリックストリーミングを自動的に処理する Ultralytics Python パッケージを使用してください。

インストールとセットアップ#

pip install "ultralytics>=8.4.120"

インストールの確認:

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形式:

プラットフォームへのプッシュ#

プラットフォームプロジェクトに結果を送信します:

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