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の主要なリソースを中心に構成されています。

認証#

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

APIキーを取得する#

1. Settings > API Keysに移動します
2. Add Keyをクリックし、プロバイダーはUltralyticsのままにして、名前を入力してからCreate Keyをクリックします
3. 生成されたキーをコピーします

詳しい手順については、APIキーをご覧ください。

Authorizationヘッダー#

APIキーをBearerトークンとして含めます。

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}、{agentId}は、APIが返す24文字の16進数IDです。
• PATCHでリソース名を変更すると、表示用のnameとURL名が同時に変更されます。レスポンスには現在のURL名が返されるため、変更後もその名前を使って追跡できます。

レート制限#

APIでは、APIキーごとにスライディングウィンドウ方式のレート制限が適用されます。各ルートは1つのカテゴリに属し、カテゴリごとに独立したカウンターがあるため、predictリクエストを20回実行してもデフォルトの上限は消費されません。

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

スロットリングが発生すると、APIはヘッダーとJSONボディの両方で429を返します。

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

{
    "error": "Rate limit exceeded, wait 12s",
    "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"
}

ページネーション#

ページネーションの方式はコレクションによって異なります。

データセット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オブジェクトを含む、データセットオブジェクト全体を返します。10,000枚以上の画像のインポート処理中は、エディターにprocessingProgressも返されます。これにはstage、percent、および判明している場合はprocessed、total、objects（スキャンされたクラウドオブジェクト）が含まれます。

データセットの作成#

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

ワークスペース内（ゴミ箱内を含む）にすでに存在するdatasetスラッグを指定すると、409が返されます。

レスポンス（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、blurFaces、kptSkeletonId（ポーズデータセットにポーズスケルトンテンプレートを割り当てます）、およびinitializeClassNames（データセットにクラスまたはアノテーションがまだない場合を除き、更新によって409が返されます）。カスタムメタデータを消去するには、空のmetadataオブジェクト（{}）を送信します。メタデータのキーは最大128文字、シリアライズされたオブジェクトは最大500,000文字です。

レスポンス:

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

名前を変更するとURL名も変わるため、以降のリクエストでは返されたdatasetの値を使用してください。

データセットの削除#

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

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

データセットをゴミ箱に移動します。ゴミ箱内のデータセットは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ダウンロードを準備せずにバージョンを保存するには、downloadをfalseに設定します。この場合、downloadUrlは省略されます。SDKはultralytics-platform>=0.1.73からdownloadを受け付けます。

ボディ（任意）:

{
    "description": "Added 500 training images",
    "download": true
}

レスポンス:

{
    "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}/versions/compare?base={from}&head={to}

Python SDK: client.datasets.compare(owner, dataset, base=1, head=2)（ultralytics-platform>=0.1.73）

レスポンス（一部抜粋）:

{
    "summary": { "added": 0, "removed": 1, "modified": 1, "moved": 1, "labelsAdded": 1, "labelsRemoved": 2 },
    "items": [
        {
            "hash": "b5c605c133f84c3024af7e652b135501",
            "name": "000000000042",
            "change": "moved",
            "base": { "split": "val", "labelCount": 1 },
            "head": { "split": "test", "labelCount": 1 }
        }
    ]
}

summaryは最初のページにのみ表示され、正確な合計数に加え、追加、削除、名前変更されたクラスや、異なるその他のデータセットフィールドを示すheaderを保持します。各アイテムのchangeは、added、removed、変更されたfieldsを含むmodified、または分割が変更されたmovedのいずれかです。また、labelsRemovedには削除された画像のラベルが含まれます。nextCursorがある場合は、次のページでcursorとして渡してください。hashを指定すると、レスポンスはversionsになります。これは各バージョンに保存された状態の画像で、ラベルと署名付きimageUrlを含みます。どちらの順序でも比較できますが、baseとheadを入れ替えると、削除された画像が追加済みとして報告されます。比較にはデフォルトのレート制限が適用されます。また、どのAPIキーから送信された場合も、hashを指定しないリクエストはユーザーおよびデータセットごとに毎分10件までに制限されます。

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

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（移動した画像数）。

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

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、cluster、split、classIds、width、height、bytes、labelCount、 labeled、missing が含まれます。cluster はサイズ順にランク付けされた点のビジュアルアイランド（0 = 最大、-1 = 散在）です。クラスタリング機能の追加前に分析されたレイアウトでは null になります。

データセットでトレーニングしたモデルを一覧表示#

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",
            "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=...)

指定された画像IDを最大1,000件まで受け取り、同じ画像形式を返します。リスト操作と同じフィルターおよびURLクエリパラメーターを使用できます。

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

画像をコピーまたは移動#

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

Python SDK： client.datasets.adopt_images(owner, dataset, image_ids=..., release=...) （ultralytics-platform>=0.1.50）

アプリのコピーと貼り付けと同様に、他のデータセットから最大1,000枚の画像をこのデータセットにコピーし、件数 adopted を返します。

{
    "imageIds": ["65f1c0a2b3d4e5f601234567"],
    "release": false,
    "classMapping": { "person": 0, "vase": null }
}

releaseまたはclassMappingを設定すると、編集可能なデータセットのラベルと分割が維持されます。release: falseは画像をコピーし、release: trueは画像を元のデータセットから移動します。両方のフィールドを省略すると、ラベルなしのtrain画像がインポートされます。読み取り専用の移行元からコピーする場合も同様です。読み取り専用の移行元から移動すると403が返されます。既存の画像はスキップされます。ラベルと分割を維持する場合、重複は移行先の分割内で確認されます。クラスは名前で照合され、2文字を超える名前では大文字と小文字が区別されません。422は移行元クラスのうちunmatchedClassesに一致するものがないクラスを返します。classMappingは各クラスをクラスインデックス、新しいクラス名、またはラベルを破棄するnullにマッピングします。409は、移行先が接続済みデータセットであるか、移行元または移行先が処理中であることを意味します。ラベルと分割を維持する場合、互換性のないタスク、画像チャンネル、ポーズ設定、深度スケールがあると、ラベルのない画像でも409が返されます。

データセットデータを取り込む#

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

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

headers_put = {"Content-Type": "application/zip", **upload.get("headers", {})}
requests.put(upload["uploadUrl"], headers=headers_put, 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=...)

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

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

{
    "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=...)

画像にモデルを適用し、予測アノテーションを返します。予測は保存されません。結果に問題がなければ、PATCH /api/images/{imageId} を使って結果を書き戻してください。

レスポンス: success、predictions（アノテーションオブジェクト）、confidences（インデックス順に対応するスコア。クラスプロンプト型モデルでは空）、modelUsed、inferenceTime、クラスプロンプト型モデルの場合は partial（生成モデルの出力が途中で切り詰められ、完全なボックスのみが返された場合は true）、有料プロバイダーモデルの場合は任意の cost（プロバイダーキーに請求される推定プロバイダー料金（USD）。推定できない場合は省略されます）が返されます。クラスがデータセットと一致しない YOLO モデル、検出以外のデータセットまたはクラス数が 1～200 の範囲外のデータセットで使用されたクラスプロンプト型モデル、およびデータセットワークスペースの 設定 > API キー にプロバイダーキーが保存されていない有料プロバイダーモデルは、422 を返します（code: missing_provider_api_key）。プロバイダーエラーにはプロバイダーからのメッセージが含まれます。プロバイダーが 400、401、403、または 404（拒否されたキー、モデル、またはリクエスト）を返した場合は 422、レート制限の場合は 429、その他のプロバイダーエラーの場合は 503 になります。深度データセットは 400 を返します。また、接続ストレージ上のデータセット、または画像チャンネルが 3 を超えるデータセットは 409 を返します。

類似画像を検索#

GET /api/images/{imageId}/similar

Python SDK: client.images.find_similar_images(image_id)

公開データセット、自分のデータセット、チームのデータセットから、視覚的に類似した images を最大24件返します。各画像には score（0～1）、署名付きの thumbnailUrl、ソースの dataset（owner、dataset、license）が含まれます。ソースデータセット内の画像と、クエリ画像のコピーは除外されます。画像への閲覧アクセス権を持つAPIキーが必要です。まだ埋め込みが作成されていない画像は先に埋め込まれます。503 はその準備に失敗したことを示すため、再試行してください。

データセットを自動アノテーション#

POST /api/datasets/{owner}/{dataset}/predict/batch

Python SDK: client.datasets.create_batch(owner, dataset, body={...})（ultralytics-platform>=0.1.57）

データセットバージョンを保存した後、未ラベル画像にモデルでラベルを付ける実行をキューに追加し、202 を返します。ボディでは、単一画像エンドポイントと同じ modelId、confidence、iou、classMapping の各フィールドに加えて、ラベル付き画像もアノテーションするための includeAnnotated（デフォルトは false）を指定します。クラスプロンプト対応モデルは信頼度スコアなしでデータセットのクラスを検出します。有料プロバイダーモデルでは、データセットワークスペースの 設定 > APIキー にプロバイダーキーを保存する必要があります（実行が受け付けられる前に 422、code：missing_provider_api_key）。既存のラベルは変更されず、実際に処理した画像に対して実行料金が請求されます。402 は残高が見積額に満たないことを示します。409 はデータセットの準備ができていない、アノテーション対象の画像が残っていない、または実行中のジョブがすでにあることを示します。422 はデータセットにクラスがないこと、またはクラスプロンプト対応モデルに検出データセット以外もしくはクラス数が1～200の範囲外のデータセットが指定されたことを示します。このエンドポイントを呼び出す前にクラスエンドポイントを使用してクラスを作成してください。アプリでは、実行開始前の「クラスのマッピング」ステップでこの処理を行います。

同じパスの GET（client.datasets.batch(owner, dataset)）は、実行中のジョブと進捗を返します。実行中のジョブがない場合は、閉じられるまで最後に完了したジョブを返します。その results には、生成モデルの出力が切り詰められ、完全なボックスのみが保持された場合に partialImages が含まれます。DELETE（client.datasets.delete_batch(owner, dataset)）は、実行中のジョブをキャンセルするか、請求を確定して完了済みの概要を閉じます。

同じエンドポイントで顔をぼかすこともできます。"operation": "blur"、confidence（デフォルトは 0.25）、boxScale（0.5～1.5、デフォルトは 1）を指定します。imageId を指定すると、処理対象が 1 枚の画像に制限されます。バージョンは作成されず、ラベルも変更されません。"preview": true を送信すると、画像を変更せずに最大 6 枚を処理できます。その後、返された jobId を同じ設定の previewJobId として送信すると適用されます。適用済みのプレビューは再利用できず、409 が返されます。 プレビューが保留中の場合は、その ID を previewJobId として DELETE に渡すと破棄できます。

{ "operation": "blur", "confidence": 0.25, "boxScale": 1, "preview": true }

画像を一括移動#

PATCH /api/images/bulk

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

1つのデータセットから別の分割に最大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、depths（ペアになった深度画像の深度ターゲットプレビュー）。すべて画像IDをキーとします。

プロジェクト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 を返します。search（最大200文字）を渡すと、モデル名またはメタデータで models をフィルターできます。

プロジェクトを作成#

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。

ワークスペース内（ゴミ箱内を含む）にすでに存在するprojectスラッグを指定すると、409が返されます。

プロジェクトを更新#

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を返して、デプロイメントを完全に削除します。プロジェクトを復元しても、デプロイメントは復元されません。502は、デプロイメントのクリーンアップが完了しなかったことを意味します。クリーンアップが成功するまで、モデルはゴミ箱に残ります。

プロジェクトをクローンする#

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

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

アクセス可能なプロジェクトと、そのプロジェクトで完了済みのモデルを複製します。任意のリクエストボディでは、project、name、description、visibility、license、および移行先の owner を指定できます。

モデル 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)

クエリパラメーター:

デフォルトのレスポンスには、ステータス、タスク、メトリクス、trainArgs、trainResults、classNames、computeCost、metadata などを含む model オブジェクトと、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 が含まれます。projectId のみを指定すると、モデルは同じ所有者の別のプロジェクトに移動します。レスポンスには、移行先でのモデルの slug、そのスラッグが移行先ですでに使用されている場合の renamed: true、およびモデルがまだトレーニング中の場合の 409 が返されます。

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

カスタム metadata は、trainArgs、environment、trainResults など、トレーニングによって管理されるフィールドとは別のもので、データセットのメタデータと同じサイズ上限が適用されます。

モデルを削除#

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

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

モデルを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=..."
        }
    ]
}

検証画像のうち最もスコアの低い画像に類似する画像を検索#

GET /api/models/{owner}/{project}/{model}/similar-images

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

トレーニングデータセットにすでに含まれている画像を除外したうえで、このトレーニング実行でスコアが最も低かった検証画像に類似する images を最大100件、類似画像の検索と同じ形式で返します。スコアが最も低かった画像の一部を対象に検索するには、hashes（カンマ区切り、最大100件）を渡します。モデルのワークスペースへのアクセス権を持つ API キーが必要です。実行で画像ごとの結果が記録されていない場合、リストは空になり、404 はスコアが最も低かった画像の埋め込みがまだ生成されていないことも意味するため、まずトレーニングデータセットでデータセットの埋め込みを実行してください。

モデルをクローン#

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 キーが必要です。

マルチパートフォーム:

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,
        "classNames": ["person", "forklift"],
        "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 を返します。

トレーニング API#

クラウド GPU でYOLOのトレーニングを開始し、進捗をリアルタイムでモニタリングします。詳しくはクラウドトレーニングのドキュメントをご覧ください。

GPUの利用状況を取得#

GET /api/training/gpu-availability

Python SDK: client.training.gpu_availability()

GPU IDごとの現在の在庫状況を返します。公開されており、認証は不要です。管理対象のトレーニング容量も含めるには managed=true を指定します。この場合は API キーが必要です。

トレーニングを開始#

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 などの最適化された形式に変換して、エッジデプロイメントに利用できます。詳しくはデプロイのドキュメントをご覧ください。

エクスポート一覧#

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

各形式で指定できるのは、下のエクスポート表の 引数 列に記載されたオプションのみです。対応していない形式に対してデフォルト以外の batch、dynamic、opset、simplify、workspace、または optimize の値を指定すると、400 が返されます。imx のエクスポートは INT8 のみで、detect、segment、classify、pose モデルで利用できます。YOLO26 モデル、および nano 以外の YOLOv8 または YOLO11 のサイズでは 400 が返されます。

レスポンス（201）: id、format、status（queued または running）、region、および TensorRT エクスポートの場合は gpuType。同等のエクスポートがすでに実行中の場合は 409 が返されます。

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

下の共通エクスポート表にある format 引数を使用してください。PyTorch はソース形式であり、API のエクスポート先ではありません。

nms=None は外部NMS向けにraw出力をデフォルトで使用します。利用可能なNMSフリーヘッドを選択するには、nms=Falseを設定してください。未対応のフォーマットでは、ネイティブの出力パスにフォールバックします。上記のnmsの項目は、nms=Trueを使用してNMSを埋め込めるフォーマットを示しています。

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

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

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

status、format、args、gpuType（TensorRT のみ）、タイムスタンプを含む export オブジェクトを返します。完了後は、size、downloadUrl、downloadFilename を含む file オブジェクトも返されます。

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

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

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

実行中のエクスポートをキャンセルするか、完了したエクスポートとそのファイルを削除します。レスポンスには実行された処理が示されます:

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

デプロイメント API#

ヘルスチェックとモニタリング機能を備えた専用推論エンドポイントにモデルをデプロイします。詳しくはエンドポイントのドキュメントをご覧ください。

デプロイメント一覧#

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、カスタムのmetadataを含むdeploymentオブジェクトを返します。所有者にはcameraとcameraApplyingも返します。

デプロイメントの更新#

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

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

次のいずれかのリクエストボディを送信します:

{ "name": "Edge 1 (primary)" }

名前を変更すると、URLのdeployment値が新しい名前のスラッグに設定され、deploymentとして返されます。古いパスは404を返し、serviceUrlは変わりません。空のmetadataオブジェクトを指定すると、カスタムメタデータが消去されます。置き換えでは、デプロイメントID、リージョン、エンドポイントURLを維持したまま、新しいリビジョンがロールアウトされます。ロールアウトに失敗した場合、既存のリビジョンは稼働を続けます。置き換え先のモデルは完了済みで、キーからアクセス可能な重みを持つ必要があります。カメラアクションでは、カスタムリソースを使用するReady状態のエンドポイントが推論を継続するRTSPまたはRTSPSカメラを保存します（バックグラウンドカメラを参照）。"url": nullを指定するか、デフォルトサイズに戻すとカメラは削除されます。デフォルトサイズのエンドポイントにカメラを保存すると、403が返されます。カメラの変更を適用している間は、202とstatus readyが返されます。cameraApplyingがtrueでなくなるまでデプロイメントをポーリングし、その後cameraを確認してください。変更に失敗した場合は以前のカメラが維持され、statusMessageが設定されます。完了した操作では、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=...)

専用エンドポイントを介して画像または動画を処理します。リクエストとレスポンスの仕様はモデル推論と一致します。カメラストリームはプロキシされません。ライブカメラ推論の説明に従って、エンドポイントURLに送信してください。

マルチパートフォーム:

メトリクスを取得#

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

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

クエリパラメーター:

完全なレスポンスには、summary（リクエスト総数、エラー率、平均レイテンシ、p50/p95/p99レイテンシ）とtimeSeries（リクエスト数、エラー数、レイテンシ、CPU、メモリ、インスタンス数）が含まれます。スパークラインのレスポンスは、requests24h（1時間ごとのリクエスト数。リクエストがない時間は省略）、totalRequests、errorRate、およびavgLatencyMs（1時間ごとのP95レイテンシの平均）を返します。view=overviewを指定すると、summaryにはtotalRequests、errorRate、p95LatencyMsが含まれ、timeSeriesにはrequests、errors、latencyP95が含まれます。

ログを取得#

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

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

クエリパラメーター:

Agents API#

Agentsのワークフローを保存および管理します。APIはエージェント定義を保存します。実行はAgentsキャンバスから開始し、https://platform.ultralytics.com/agents?workflow={id}で保存済みエージェントを開きます。Python SDKのメソッドにはultralytics-platform>=0.1.74が必要です。

各操作では、所属するワークスペースのユーザー名を指定する任意のownerクエリパラメーターを使用できます（デフォルト: 自分のユーザー名）。一覧表示には閲覧者アクセス権が必要です。保存と削除には編集者アクセス権が必要です。

エージェントを一覧表示#

GET /api/workflows

Python SDK: client.agents.list()

レスポンスでは、workflowsに最大100件のエージェントを格納し、更新日時の新しい順に、各エージェントのid、username、name、version、createdAt、updatedAtを返します。idをリクエストすると、エージェントのgraphも返されます。

エージェントを保存#

PUT /api/workflows

Python SDK: client.agents.save(name=..., graph=..., version=...)

エージェントを作成するにはversion: 0を送信します。エージェントを更新するには、そのidと、前回の一覧表示または保存操作で返されたversionを送信します。古いversionを送信すると409が返されるため、エージェントを再度一覧表示してやり直してください。接続が循環しているグラフ、または1つのブロックに複数の入力があるグラフを送信すると、400が返されます。

from ultralytics_platform import Platform

def block(node_id, kind, x, config):
    return {
        "id": node_id,
        "type": "agent",
        "position": {"x": x, "y": 0},
        "data": {"label": kind, "type": kind, "config": config},
    }

graph = {
    "nodes": [
        block("images", "Dataset", 0, {"dataset": "official:coco8", "split": "val", "maxInputs": 2}),
        block("yolo", "YOLO", 220, {"model": "ul://ultralytics/yolo26/yolo26n", "task": "detect"}),
        block("output", "Output", 440, {}),
    ],
    "edges": [{"id": "e1", "source": "images", "target": "yolo"}, {"id": "e2", "source": "yolo", "target": "output"}],
    "templateId": "",
}

with Platform() as client:
    saved = client.agents.save(name="Detect COCO8", graph=graph, version=0)
    print(saved["id"], saved["version"], saved["errors"])

レスポンスは、エージェント id とその新しい version、および errors（データセットが選択されていない データセット ブロックなど、キャンバスで警告対象となるブロック）を返します。エージェントはどちらの場合でも保存されます。すべてのブロックタイプとその設定については、openapi.jsonを参照してください。

エージェントを削除#

DELETE /api/workflows?id={id}

Python SDK: client.agents.delete(id=...)

エージェントを削除し、そのアクティブな実行をキャンセルします。削除したエージェントはゴミ箱に表示されず、復元できません。

ゴミ箱API#

論理削除されたプロジェクト、データセット、モデルを表示、復元、完全に削除できます。アイテムは30日後に自動的に消去されます。ゴミ箱のドキュメントを参照してください。

ゴミ箱を一覧表示#

GET /api/trash

Python SDK: client.lifecycle.trash()

クエリパラメーター:

レスポンスには、items（各項目にdaysRemainingを含む）、total、page、limit、totalPages、および種類別の合計を含むsummaryが含まれます。idを指定すると、代わりにresourcesが返されます。これは、影響を受けるモデルと完全に削除されるデプロイを示します。

アイテムを復元#

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を使用して、ファイルをクラウドストレージに直接アップロードします。モデルのアップロードを完了すると重みが関連付けられます。データセットアーカイブのアップロードを完了すると検証されます。その後、セッションをデータセットの取り込みに渡します。この手順を省略した場合も、データセットの取り込みがアップロードを完了します。データのドキュメントを参照してください。

署名付きアップロード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",
    "headers": { "x-goog-if-generation-match": "0" }
}

PUTリクエストでファイルをuploadUrlにアップロードします。指定したContent-Typeと、headersで返されたすべてのヘッダーを使用してください。データセットのアップロードURLは12時間有効で、新規作成専用です。同じURLへの2回目のPUTは412を返します。また、返されたヘッダーを付けないPUTは400を返します。

アップロードを完了#

POST /api/upload/complete

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

{
    "sessionId": "session_abc123",
    "md5": "<optional md5 hex>"
}

レスポンス: successと、sizeおよびcontentTypeを含むfileオブジェクトです。モデルの場合は重みが関連付けられます。データセットアーカイブの場合は、次に取り込みを呼び出して処理を開始してください。

md5を指定すると、保存済みオブジェクトと照合されます。一致しない場合は400が返されます。未完了のセッションでは、アップロード済みファイルも削除され、セッションは未完了のままとなるため、新しい署名付きURLをリクエストして再度アップロードしてください。アーカイブが存在する場合、完了済みのデータセットセッションは再度完了できますが、ダイジェストが異なる並行完了処理では409が返されます。モデルセッションは完了時に削除されます。checksumはモデルファイルのメタデータとして保存され、検証されません。

ストレージ連携API#

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

ストレージの検出と接続には、ワークスペース管理者アクセス権とProまたはEnterpriseプランが必要です（それ以外の場合は403）。連携の一覧表示とオブジェクトの参照には編集者アクセス権が必要です。

連携を一覧表示#

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連携を参照してください。

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

POST /api/integrations/roboflow/preview

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

Roboflow APIキーをインポート計画に変換します。計画には、ワークスペースの詳細、インポート対象となるnewDatasets、すでにインポート済み（skippedCount）、バージョンなし、未サポート、未解決の各プロジェクトの件数、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()

キーのワークスペースについて、keyId、name、keyPrefix、createdAtを含むkeysを返します。APIキーで認証されたリクエストにはメタデータのみが返されます。キーの完全な値は、Platform UIの設定 > APIキーでワークスペース所有者に表示されます。キーの作成と取り消しも、この画面で行います。

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

GET /api/storage

Python SDK: client.account.storage()

クエリパラメーター:

レスポンス:

{
    "tier": "pro",
    "usage": {
        "storage": { "current": 1073741824, "limit": 536870912000, "percent": 0 },
        "datasets": { "current": 2, "limit": -1, "percent": 0 },
        "models": { "current": 4, "limit": 500, "percent": 1 }
    },
    "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"
}

usageは、projects、datasets、models、images、annotations、deploymentsの件数と、storageのバイト数を報告します。limitが-1の場合は無制限を意味し、percentは上限に対する整数の割合です。

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

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、およびトレーニング料金のモデルコンテキストが含まれます。内部の請求詳細は返されません。

Explore API#

コミュニティが共有する公開プロジェクトやデータセットを検索するか、画像に写っている内容で画像を検索します。Exploreのドキュメントをご覧ください。

公開コンテンツの検索#

GET /api/explore/search

Python SDK: client.explore.search()

クエリパラメーター:

レスポンス: projects、datasets、hasMore。type=imagesは、一致結果を最も関連性の高い順にimagesで返します。各結果には、元のdatasetと0～1の類似度scoreが含まれます。qが必要です。公開データセットを検索し、APIキーを送信した場合は自分とチームのデータセットも検索します。

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.45" # Python 3.11+

from ultralytics_platform import Platform

with Platform() as client:  # ULTRALYTICS_API_KEY、またはyolo loginで保存したキーを読み込みます
    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コードと同じリソースツリーを公開します。レスポンスが成功しなかった場合は、status_code、body、解析済みのjsonを含むAPIErrorが発生し、接続に失敗した場合はAPIConnectionErrorが発生します。完全なREADMEについては、SDKリポジトリをご覧ください。

Python連携#

トレーニングと推論のワークフローには、認証、アップロード、リアルタイムのメトリクスストリーミングを自動的に処理するUltralytics Pythonパッケージを使用してください。Python 3.11以降では、pip install ultralyticsによってultralytics-platform SDKもインストールされます。model.train(project=...)がPlatformを対象とする場合、トレーニングコールバックはSDKのclient.training.metrics()を介してイベントをストリーミングし、OpenAPIドキュメントのPOST /api/webhooks/training/metricsおよびPOST /api/webhooks/models/upload操作であるclient.models.upload_checkpoint()を介してチェックポイントのアップロードURLをリクエストするため、ご自身で呼び出す必要はありません。

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

Platform連携にはPython>=3.11とultralytics>=8.4.120が必要です:

pip install "ultralytics>=8.4.120"

インストールを確認します:

yolo check

認証#

yolo login YOUR_API_KEY

Platformのデータセットを使用#

ul:// URIを使用してデータセットを参照します:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Platformのデータセットでトレーニングします
model.train(
    data="ul://your-username/datasets/your-dataset",
    epochs=100,
    imgsz=640,
)

URI形式:

Platformへの送信#

結果をPlatformプロジェクトに送信します:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# 結果は自動的にPlatformと同期されます
model.train(
    data="coco8.yaml",
    epochs=100,
    project="your-username/my-project",
    name="experiment-1",
)

同期される内容:

• トレーニングメトリクス（リアルタイム）
• 最終モデルの重み
• 検証プロット
• コンソール出力
• システムメトリクス
• トレーニング引数とホスト環境（ホスト名、OS、Python、ハードウェア、gitコミット、コマンドライン）

APIの例#

Platformからモデルを読み込む:

# 独自のモデル
model = YOLO("ul://username/project/model-name")

# 公式モデル
model = YOLO("ul://ultralytics/yolo26/yolo26n")

推論を実行する:

results = model("image.jpg")

# 結果にアクセス
for r in results:
    boxes = r.boxes  # 検出ボックス
    masks = r.masks  # セグメンテーションマスク
    keypoints = r.keypoints  # ポーズのキーポイント
    probs = r.probs  # 分類確率

モデルをエクスポート:

# ONNXにエクスポートします
model.export(format="onnx", imgsz=640, quantize=16)

# TensorRTにエクスポートします
model.export(format="engine", imgsz=640, quantize=16)

# CoreMLにエクスポート
model.export(format="coreml", imgsz=640)  # 分類ではimgsz=224を使用します

検証:

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

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

よくある質問#