REST API リファレンス#

Ultralytics Platformでは、データセット、モデル、トレーニング、デプロイメントにプログラムからアクセスするための包括的なREST APIを提供しています。

Ultralytics Platform Interactive API Documentation

クイックスタート

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

インタラクティブな API ドキュメント

完全なインタラクティブAPIリファレンスについては、Ultralytics Platform API docsをご覧ください。

API の概要#

API は、プラットフォームのコアリソースを中心に構成されています。

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

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

リソース	説明	主要な操作
Datasets	ラベル付き画像コレクション	CRUD、画像、ラベル、エクスポート、バージョン、クローン
Projects	トレーニングワークスペース	CRUD、クローン、アイコン
モデル	学習済みチェックポイント	CRUD、推論（predict）、ダウンロード、クローン、エクスポート
Deployments	専用の推論エンドポイント	CRUD、開始/停止、メトリクス、ログ、ヘルスチェック
Exports	フォーマット変換ジョブ	作成、ステータス、ダウンロード
Training	クラウド GPU トレーニングジョブ	開始、ステータス、キャンセル
Billing	クレジットと利用状況	残高、利用状況、トランザクション
Teams	ワークスペースの共同作業	ワークスペース、メンバー、ロール

認証#

リソースAPIは、データセットのクラス管理や分割管理、クローン、トレーニング、エクスポート、デプロイ、およびサポートされているアカウントの読み取りを含め、APIキー認証を使用します。パブリックエンドポイントは、記載がある場合に限り匿名アクセスをサポートしています。ブラウザ専用のアプリケーションルートは除外されます。

API キーの取得#

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

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

認証ヘッダー#

すべてのリクエストに API キーを含めてください：

Authorization: Bearer YOUR_API_KEY

API キーのフォーマット

APIキーの形式は、ul_に続いて40文字の16進数が続きます。キーは秘密として保持し、バージョン管理にコミットしたり公開したりしないでください。

例#

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

ベース URL#

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

https://platform.ultralytics.com/api

レート制限#

APIキーごとに、Upstash Redisをバックエンドとしたスライディングウィンドウ方式の制限がAPIによって強制されます。各ルートは、以下の一致するカテゴリを使用します。

制限に達した場合、APIはリトライメタデータとともに429を返します。

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

API キーごとの制限#

レート制限は、呼び出されるエンドポイントに基づいて自動的に適用されます。負荷の高い操作には不正利用を防ぐために厳しい制限が設けられていますが、標準的な CRUD 操作には十分なデフォルト枠が設定されています。

カテゴリ	制限	適用対象
デフォルト	100 リクエスト/分	以下のカテゴリに割り当てられていないルート
トレーニング	10 リクエスト/分	クラウドトレーニングの開始
アップロード	10 リクエスト/分	署名付きアップロードURL、アップロードの完了、およびデータセットのインジェスト
推論 (Predict)	20 リクエスト/分	Platform APIルートを通じたモデルとデプロイの推論
エクスポート	20 リクエスト/分	モデルのエクスポートルートおよびデータセットのエクスポート／バージョンルート
ダウンロード	30 リクエスト/分	モデルファイルのダウンロード
Mutation	10 リクエスト/分	チームの作成、ストレージ統合の変更、APIキー、メンバー、招待、およびデプロイの開始／停止
請求	5リクエスト／分	自動チャージおよびサブスクリプション決済のルート
Hydrate	20 リクエスト/分	選択した一連のデータセット画像の hydration
Clustering	10 リクエスト/分	データセット画像のクラスタリング

各カテゴリには、API キーごとに独立したカウンターがあります。例えば、20 回の推論リクエストを行っても、100 リクエスト/分のデフォルト許容量には影響しません。

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

Dedicated endpoints are not subject to Platform API-key rate limits when you call the endpoint URL directly (for example, https://predict-abc123.run.app/predict). Throughput then depends on the deployed service configuration.

レート制限の処理

429ステータスコードを受信した場合は、リトライする前にRetry-After（またはX-RateLimit-Resetになるまで）待機してください。指数バックオフの実装については、rate limit FAQをご覧ください。

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

成功レスポンス#

レスポンスはリソース固有のフィールドを持つ JSON を返します。

{
    "datasets": [...],
    "total": 100
}

エラーレスポンス#

{
    "error": "Dataset not found"
}

HTTP ステータス	意味
`200`	成功
`201`	作成完了
`400`	無効なリクエスト
`401`	認証が必要
`403`	権限不足
`404`	リソースが見つかりません
`409`	競合（重複）
`429`	レート制限を超えました
`500`	サーバーエラー

Datasets API#

YOLOモデルのトレーニング用に、ラベル付けされた画像データセットの作成、閲覧、管理を行います。詳細はDatasets documentationをご覧ください。

データセット一覧#

GET /api/datasets

クエリパラメータ:

パラメータ	タイプ	説明
`username`	string	ユーザー名でフィルタリング
`limit`	int	ページあたりのアイテム数（デフォルト: 1000、最大: 1000）
`owner`	string	ワークスペース所有者のユーザー名
`includeImageUrls`	boolean	署名付きのフルサイズサンプル画像のURLを含めます（デフォルト：`false`）
`includeSamples`	boolean	サンプル画像を省略してレスポンスサイズを小さくするには、`false`を設定します。

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

レスポンス:

{
    "datasets": [
        {
            "_id": "dataset_abc123",
            "name": "my-dataset",
            "slug": "my-dataset",
            "task": "detect",
            "imageCount": 1000,
            "classCount": 10,
            "classNames": ["person", "car"],
            "visibility": "private",
            "username": "johndoe",
            "starCount": 3,
            "isStarred": false,
            "sampleImages": [
                {
                    "url": "https://storage.example.com/...",
                    "width": 1920,
                    "height": 1080,
                    "labels": [{ "classId": 0, "bbox": [0.5, 0.4, 0.3, 0.6] }]
                }
            ],
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-01-16T08:30:00Z"
        }
    ],
    "total": 1,
    "region": "us"
}

データセットを取得#

GET /api/datasets/{datasetId}

クラス名、分割数、その他のPlatform管理プロパティを含むデータセットの詳細を返します。カスタムメタデータは、以下のメタデータエンドポイントから個別に読み込まれます。

Pass username when {datasetId} is a dataset slug rather than an ID.

データセットを作成#

POST /api/datasets

ボディ:

{
    "slug": "my-dataset",
    "name": "My Dataset",
    "task": "detect",
    "description": "A custom detection dataset",
    "metadata": { "location": "factory-1", "reviewed": true },
    "visibility": "private",
    "classNames": ["person", "car"]
}

サポートされているタスク

有効なtaskの値：detect、segment、semantic、classify、pose、obb。

レスポンス:

{
    "datasetId": "dataset_abc123",
    "slug": "my-dataset",
    "region": "us"
}

データセットを更新#

PATCH /api/datasets/{datasetId}

ボディ（部分更新）:

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

カスタムメタデータをクリアするには、空の metadata オブジェクト（{}）を送信します。シリアライズされたメタデータオブジェクトは最大500,000文字まで、各トップレベルキーは最大128文字までに制限されています。

データセットメタデータの取得#

GET /api/datasets/{datasetId}/metadata

カスタムメタデータオブジェクトと、Ultralyticsが管理する読み取り専用のフィールド/値の厳選されたセットを返します。カスタムメタデータは、通常のデータセットペイロードからは意図的に除外されます。認証とデータセットのワークスペースアクセスが必要です。

データセットアイコン#

POST /api/datasets/{datasetId}/icon
DELETE /api/datasets/{datasetId}/icon

マルチパートフォームフィールドimageとして最大5 MBのWebPアイコンをアップロードするか、現在のアイコンを削除します。

データセットを削除#

DELETE /api/datasets/{datasetId}

データセットをソフト削除します（trashに移動され、30日間復元可能です）。

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

POST /api/datasets/{datasetId}/clone

パブリック、所有、または編集可能なワークスペースデータセットのコピーを、すべての画像とラベルとともに作成します。

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

{
    "name": "cloned-dataset",
    "slug": "cloned-dataset",
    "description": "My cloned dataset",
    "visibility": "private",
    "license": "AGPL-3.0",
    "owner": "team-username"
}

データセットをエクスポート#

GET /api/datasets/{datasetId}/export

最新のデータセットエクスポートへの署名付きダウンロードURLを含むJSONレスポンスを返します。

クエリパラメータ:

パラメータ	タイプ	説明
`v`	integer	バージョン番号（1から始まるインデックス）。省略した場合は、最新のミュータブルなエクスポートが返され、データセットに変更がない場合はそれが再利用されます。

レスポンス:

{
    "downloadUrl": "https://storage.example.com/export.ndjson?signed=...",
    "cached": true
}

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

POST /api/datasets/{datasetId}/export

データセットの新しい番号付きバージョンスナップショットを作成します。これにはEditorアクセス権限以上が必要です。バージョンは現在の画像数、クラス数、アノテーション数、および分割分布をキャプチャし、イミュータブルなNDJSONエクスポートを生成して保存します。

リクエストボディ:

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

すべてのフィールドは任意です。descriptionフィールドは、バージョンに対してユーザーが指定するラベルです。

レスポンス:

{
    "version": 3,
    "downloadUrl": "https://storage.example.com/v3.ndjson?signed=..."
}

バージョン説明を更新#

PATCH /api/datasets/{datasetId}/export

既存のバージョンの説明を更新します。これにはEditorアクセス権限以上が必要です。

リクエストボディ:

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

レスポンス:

{
    "ok": true
}

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

POST /api/datasets/{datasetId}/restore

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

{
    "version": 2
}

クラス統計を取得#

GET /api/datasets/{datasetId}/class-stats

クラス分布、位置ヒートマップ、次元統計を返します。結果は最大5分間キャッシュされます。

レスポンス:

{
    "classes": [{ "classId": 0, "count": 1500, "imageCount": 450 }],
    "imageStats": {
        "widthHistogram": [{ "bin": 640, "count": 120 }],
        "heightHistogram": [{ "bin": 480, "count": 95 }],
        "pointsHistogram": [{ "bin": 4, "count": 200 }]
    },
    "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", "car", "dog"],
    "cached": true,
    "sampled": false,
    "sampleSize": 1000
}

クラスの管理#

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

POST /api/datasets/{datasetId}/classes/merge

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

クラスIDは位置に基づくため、マージはべき等ではありません。再試行する前にデータセットを再取得してください。

クラスを削除します：

POST /api/datasets/{datasetId}/classes/delete

{
    "classIds": [2, 4]
}

スプリットの再分配#

POST /api/datasets/{datasetId}/splits/redistribute

トレーニング、検証、およびテストの分割間で画像をランダムに再割り当てします。パーセンテージの合計は100である必要があります。

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

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

GET /api/datasets/{datasetId}/embeddings
POST /api/datasets/{datasetId}/embeddings
DELETE /api/datasets/{datasetId}/embeddings

GETは現在のUMAP分析サマリーとアクティブなジョブステータスを返し、POSTは埋め込み分析ジョブをキューに入れ、DELETEはアクティブなジョブをキャンセルします。

画像クラスタリング#

GET /api/datasets/{datasetId}/images/clustering

クラスタリング散布図ビュー用のUMAP 2Dレイアウトおよび画像ごとのメタデータを返します（ページ分割され、レート制限があります）。

データセットでトレーニングされたモデルを取得#

GET /api/datasets/{datasetId}/models

このデータセットを使用してトレーニングされたモデルを返します。

レスポンス:

{
    "models": [
        {
            "_id": "model_abc123",
            "name": "experiment-1",
            "slug": "experiment-1",
            "status": "completed",
            "task": "detect",
            "epochs": 100,
            "bestEpoch": 87,
            "projectId": "project_xyz",
            "projectSlug": "my-project",
            "projectIconColor": "#3b82f6",
            "projectIconLetter": "M",
            "username": "johndoe",
            "startedAt": "2024-01-14T22:00:00Z",
            "completedAt": "2024-01-15T10:00:00Z",
            "createdAt": "2024-01-14T21:55:00Z",
            "metrics": {
                "mAP50": 0.85,
                "mAP50-95": 0.72,
                "precision": 0.88,
                "recall": 0.81
            }
        }
    ],
    "count": 1
}

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

POST /api/datasets/{datasetId}/predict

データセット画像でYOLO推論を実行し、アノテーションを自動生成します。選択したモデルを使用して、アノテーションのない画像のラベルを予測します。

ボディ:

フィールド	タイプ	必須	説明
`imageHash`	string	はい	アノテーション対象画像のハッシュ
`modelId`	string	いいえ	推論に使用するモデル。`ul://` URI（例：`ul://username/project/model`）として指定します。省略した場合は、データセットのタスク固有のデフォルトモデルが使用されます。
`confidence`	float	いいえ	信頼度のしきい値（デフォルト: 0.25）
`iou`	float	いいえ	IoUのしきい値（デフォルト: 0.7）

データセット取り込み#

POST /api/datasets/ingest

既存のデータセットに対するデータセットのインジェストジョブを作成します。ターゲットのデータセットはURLパスではなく、常にJSONボディ内のdatasetIdとして渡されます。

リクエストボディには、datasetIdに加え、sessionId（アップロードされたアーカイブのアップロードセッション）またはsourceUrl（リモートのZIP、TAR、TAR.GZ、TGZ、またはNDJSONのURL）のいずれか1つが必須です。アーカイブの分割構造を上書きするには、オプションのtargetSplit（train、val、またはtest）を追加します。カスタムメタデータを添付するには、各画像のアーカイブ相対パスまたはNDJSONのfileの値をキーとしたimageMetadataを使用します。

For uploaded archives, the upload session is already bound to the dataset by the assetId passed to POST /api/upload/signed-url; ingest validates that assetId matches the body datasetId. Optional classMapping entries map each incoming class name to an existing zero-based class index, a class name to reuse or create, or null to skip the class. For remote sourceUrl imports, create the dataset first, then pass its datasetId to ingest.

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

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

ボディ（メタデータ付きの単一または複数の画像）：

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

ローカル画像では、アーカイブに1枚の画像が含まれているか多数含まれているかにかかわらず、既存のアーカイブアップロードフローを使用します。キーは、フォルダを含むアーカイブ内の正規化されたパスと一致している必要があります。NDJSONインポートの場合、各画像レコードに独自のmetadataオブジェクトを代わりに含めることができます。レコードローカルのmetadataは、一致するimageMetadataのエントリよりも優先されます。

メタデータはJSONであり、ネストされた値をサポートしています。アーカイブパスは1,024文字、トップレベルのメタデータキーは128文字、各メタデータオブジェクトはシリアライズされた文字数で500,000文字に制限されています。完全なimageMetadataマップ、またはNDJSONインポート全体で結合された有効なメタデータも、シリアライズされた文字数で500,000文字に制限されています。これらの制限は、対話型OpenAPIスキーマに含まれています。

Pythonを使用してメタデータ付きの画像を1枚アップロードする

同じコードで画像のグループを処理できます。ZIPに追加のファイルを追加し、imageMetadataに対応するエントリを追加します。

import io
import zipfile
from pathlib import Path

import requests

api = "https://platform.ultralytics.com/api"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
dataset_id = "dataset_abc123"
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/ingest",
    headers=headers,
    json={
        "datasetId": dataset_id,
        "sessionId": upload["sessionId"],
        "imageMetadata": {
            "airbus-wing.jpg": {
                "aircraft": {"family": "A350", "section": "wing"},
                "inspectionStatus": "reviewed",
            }
        },
    },
)
ingest.raise_for_status()
print(ingest.json())

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

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

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

{
    "datasetId": "dataset_abc123",
    "sessionId": "session_abc123",
    "classMapping": { "person": 0, "automobile": "car", "background": null }
}

クラスマッピング

最初のインジェストでは、アーカイブからクラスが自動的に作成されます。後続のインジェストでは、classMappingから省略されたアーカイブクラスは、まず既存のデータセットクラスとの大文字小文字を区別しない一致にフォールバックします。ラベルは、nullに明示的にマッピングされたクラス、または一致する既存のクラスがないクラスでのみスキップされます。

レスポンス:

{
    "jobId": "job_abc123",
    "datasetId": "dataset_abc123",
    "status": "queued"
}

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

データセット画像#

画像一覧を取得#

GET /api/datasets/{datasetId}/images

クエリパラメータ:

パラメータ	タイプ	説明
`split`	string	分割によるフィルタ：`train`、`val`、`test`
`offset`	int	ページネーションのオフセット（デフォルト: 0）
`limit`	int	ページあたりのアイテム数（デフォルト: 50、最大: 5000）
`sort`	string	ソート順：`newest`、`oldest`、`name-asc`、`name-desc`、`height-asc`、`height-desc`、`width-asc`、`width-desc`、`size-asc`、`size-desc`、`labels-asc`、`labels-desc`（10万画像を超えるデータセットでは一部が無効になります）
`hasLabel`	string	ラベルステータスによるフィルタ（`true`または`false`）
`hasError`	string	エラー状態によるフィルタ（`true`または`false`）
`search`	string	ファイル名およびカスタムメタデータのキー、スカラー値、配列エントリに対する部分一致検索（サブオブジェクト内にネストされた値は一致しません）。32文字の16進数文字列は、正確な画像ハッシュルックアップになります。
`classIds`	string	カンマ区切りのクラスID。指定されたクラスのいずれかを含む画像を返します。
`includeThumbnails`	string	署名付きサムネイルURLを含めます（デフォルト：`true`）
`includeImageUrls`	string	署名付きの完全な画像のURLを含めます（デフォルト：`false`）

選択した画像の取得#

POST /api/datasets/{datasetId}/images

最大1,000個の提供された画像IDに対して、同じ画像形状を返します。リスト操作と同じURLおよびラベルクエリ制御を受け付けます。

{
    "imageIds": ["IMAGE_OBJECT_ID"]
}

署名付き画像URLを取得#

POST /api/datasets/{datasetId}/images/urls

画像ハッシュのバッチに対する署名付きURLを取得します（ブラウザでの表示用）。

画像を削除#

DELETE /api/datasets/{datasetId}/images/{hash}

画像ラベルを取得#

GET /api/datasets/{datasetId}/images/{hash}/labels

特定の画像のアノテーションとクラス名を返します。

画像ラベルを更新#

PUT /api/datasets/{datasetId}/images/{hash}/labels

ボディ:

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

座標形式

ラベルの座標には、0から1の間のYOLO正規化値を使用します。バウンディングボックスには[x_center, y_center, width, height]を使用します。セグメンテーションラベルにはsegmentsを使用し、これはポリゴン頂点の平坦化されたリストである[x1, y1, x2, y2, ...]です。

一括画像操作#

データセット内の分割（train/val/test）間で画像を移動します：

PATCH /api/datasets/{datasetId}/images/bulk

画像の一括削除：

DELETE /api/datasets/{datasetId}/images/bulk

Projects API#

モデルをプロジェクトごとに整理します。各モデルは1つのプロジェクトに属します。詳細はProjects documentationをご覧ください。

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

GET /api/projects

クエリパラメータ:

パラメータ	タイプ	説明
`username`	string	ユーザー名でフィルタリング
`limit`	int	ページあたりのアイテム数
`owner`	string	ワークスペース所有者のユーザー名

プロジェクトを取得#

GET /api/projects/{projectId}

プロジェクトを作成#

POST /api/projects

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

プロジェクトを更新#

PATCH /api/projects/{projectId}

ボディ（部分更新）:

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

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

プロジェクトメタデータの取得#

GET /api/projects/{projectId}/metadata

カスタムメタデータオブジェクトと、Ultralyticsが管理する読み取り専用のフィールド/値のペアを返します。認証とプロジェクトのワークスペースアクセスが必要です。

プロジェクトを削除#

DELETE /api/projects/{projectId}

プロジェクトをソフト削除します（trashに移動されます）。

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

POST /api/projects/{projectId}/clone

公開されている、所有している、または編集可能なワークスペースプロジェクトとそのモデルを、ご自身のアカウントまたはワークスペースにクローンします。オプションのJSONボディで、name、slug、description、visibility、license、および宛先のownerの上書きを受け付けます。

プロジェクトアイコン#

POST /api/projects/{projectId}/icon
DELETE /api/projects/{projectId}/icon

マルチパートフォームフィールドimageとして最大5 MBのWebPアイコンをアップロードするか、現在のアイコンを削除します。

Models API#

トレーニング済みのYOLOモデルを管理します（メトリクスの表示、重みのダウンロード、推論の実行、他の形式へのエクスポート）。詳細はModels documentationをご覧ください。

モデルの一覧表示#

GET /api/models

クエリパラメータ:

パラメータ	タイプ	必須	説明
`projectId`	string	はい	プロジェクトID（必須）
`fields`	string	いいえ	フィールドセット：`summary`、`charts`
`ids`	string	いいえ	カンマ区切りのモデルID
`limit`	int	いいえ	最大結果数（デフォルト20、最大100）

完了したモデルの一覧表示#

GET /api/models/completed

トレーニングとデプロイメントに使用可能な重みを持つ、すべてのプロジェクトから最大1,000個のモデルを返します。ワークスペースを指定するには、ownerを渡します。

モデルの取得#

GET /api/models/{modelId}

モデルの作成#

POST /api/models

JSON Body:

フィールド	タイプ	必須	説明
`projectId`	string	はい	対象プロジェクトID
`slug`	string	いいえ	URLスラッグ（英数字小文字およびハイフン）
`name`	string	いいえ	表示名（最大100文字）
`description`	string	いいえ	モデルの説明（最大1000文字）
`metadata`	オブジェクト	いいえ	カスタムJSONメタデータ
`task`	string	いいえ	タスクタイプ (detect、segment、semantic、depth、pose、obb、classify)

モデルファイルのアップロード

To attach .pt weights, request a signed upload URL with assetType: models and this model's ID as assetId, upload the file, then call POST /api/upload/complete with the returned sessionId.

モデルの更新#

PATCH /api/models/{modelId}

ボディ（部分更新）:

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

クリアするには、空の metadata オブジェクト（{}）を送信します。モデルのカスタムメタデータは、トレーニングが所有するモデル情報、環境詳細、トレーニング引数とは別個のものであり、データセットメタデータと同じシリアライズ済みオブジェクトおよびトップレベルキーの制限が適用されます。

モデルメタデータの取得#

GET /api/models/{modelId}/metadata

カスタムメタデータオブジェクトと、Ultralyticsが管理する読み取り専用のフィールド/値のペアを返します。認証とモデルのワークスペースアクセスが必要です。

モデルの削除#

DELETE /api/models/{modelId}

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

GET /api/models/{modelId}/files

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

モデルをクローンする#

POST /api/models/{modelId}/clone

パブリック、所有、または編集可能なワークスペースモデルを自分のプロジェクトの1つにクローンします。

ボディ:

{
    "targetProjectSlug": "my-project",
    "modelName": "cloned-model",
    "description": "Cloned from public model",
    "owner": "team-username"
}

フィールド	タイプ	必須	説明
`targetProjectSlug`	string	はい	宛先プロジェクトのスラッグ
`modelName`	string	いいえ	クローンモデルの名称
`description`	string	いいえ	モデルの説明
`owner`	string	いいえ	チームのユーザー名（ワークスペースクローン用）

ダウンロードの追跡#

POST /api/models/{modelId}/track-download

モデルダウンロードの分析を追跡します。

推論を実行します#

POST /api/models/{modelId}/predict

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

Multipart Form:

パラメータ	タイプ	デフォルト	範囲	説明
`file`	ファイル	-	-	画像または動画ファイル（`source` が設定されている場合を除き必須）
`conf`	float	0.25	0.01 – 1.0	最小信頼度しきい値
`iou`	float	0.7	0.0 – 0.95	NMS IoUしきい値
`imgsz`	int	640	32 – 1280	入力画像のサイズ（ピクセル単位）
`normalize`	bool	false	-	バウンディングボックスの座標を0～1で返します
`decimals`	int	5	0 – 10	座標値の小数点以下の精度
`source`	string	-	-	画像 URL または base64 文字列（`file` の代替）

fileまたはsourceのいずれかを指定してください。最大アップロードサイズは100 MBです。

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

レスポンス:

Responses contain per-image shape, speed, results, and optional dense pixel-map data (a semantic class map, or a depth map where depth = pixel × max / divisor — divisor 255 for the default 8-bit map, 65535 with bits=12|16), plus metadata with image count, function timing, task, and service versions. Internal model paths are never returned.

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                }
            ]
        }
    ],
    "metadata": {
        "imageCount": 1
    }
}

Training API#

クラウドGPU（RTX 2000 AdaからB300までの26種類のGPU）でYOLOトレーニングを開始し、リアルタイムで進行状況を監視します。詳細はCloud Training documentationをご覧ください。

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

トレーニングの開始#

POST /api/training/start

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

GPUタイプ

利用可能なGPUタイプには、rtx-4090、a100-80gb-pcie、a100-80gb-sxm、h100-sxm、rtx-pro-6000、b300などがあります。価格を含む完全なリストについては、Cloud Trainingをご覧ください。

GPU可用性の取得#

GET /api/training/gpu-availability

GPUタイプIDをキーとした現在のGPUの在庫状況（High、Medium、Low、またはnull）を返します。公開されており、認証は不要です。5分間キャッシュされます。

トレーニングステータスの取得#

GET /api/models/{modelId}/training

現在のトレーニングジョブのステータス、メトリクス、進捗、タイミング、GPU詳細、およびエラーを返します。パブリックプロジェクトは認証なしでアクセス可能ですが、プライベートプロジェクトおよび共有プロジェクトにはアクセス権を持つAPIキーが必要です。

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

DELETE /api/models/{modelId}/training

実行中のコンピュートインスタンスを終了し、ジョブをキャンセル済みとしてマークします。

Deployments API#

ヘルスチェックと監視機能を備えた専用の推論エンドポイントにモデルをデプロイします。新規デプロイメントではデフォルトでスケールツーゼロが使用され、APIではオプションのresourcesオブジェクトを受け付けます。詳細はEndpoints documentationをご覧ください。

ルートごとのAPIキーサポート

以下のすべてのデプロイメントルートでは、APIキー認証を受け付けます。スループットの高い推論を行うには、デプロイメント独自のエンドポイントURL（例：https://predict-abc123.run.app/predict）をご自身のAPIキーで直接呼び出してください。Dedicated endpointsにはレート制限がありません。

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

クエリパラメータ:

パラメータ	タイプ	説明
`modelId`	string	モデルによるフィルタリング
`status`	string	ステータスによるフィルタリング
`limit`	int	最大結果数（デフォルト: 20、最大: 100）
`owner`	string	ワークスペース所有者のユーザー名

デプロイメントの作成#

POST /api/deployments

ボディ:

{
    "modelId": "model_abc123",
    "name": "my-deployment",
    "region": "us-central1",
    "resources": {
        "cpu": 1,
        "memoryGi": 2,
        "minInstances": 0,
        "maxInstances": 1
    }
}

フィールド	タイプ	必須	説明
`modelId`	string	はい	デプロイするモデルID
`name`	string	はい	デプロイメント名
`region`	string	はい	デプロイメントリージョン
`resources`	オブジェクト	いいえ	リソース設定（`cpu`、`memoryGi`、`minInstances`、`maxInstances`）

指定したリージョンに専用の推論エンドポイントを作成します。エンドポイントは固有のURLを介してグローバルにアクセス可能です。

デフォルトリソース

デプロイメントダイアログでは現在、cpu=1、memoryGi=2、minInstances=0、maxInstances=1の固定されたデフォルトが送信されます。APIルートではresourcesオブジェクトを受け付けますが、プランの制限により、minInstancesの上限は0まで、maxInstancesの上限は1までとなります。

リージョン選択

レイテンシを最小限に抑えるため、ユーザーに近いリージョンを選択してください。プラットフォームのUIでは、利用可能な42の全リージョンのレイテンシ推定値が表示されます。

デプロイメントの取得#

GET /api/deployments/{deploymentId}

デプロイメントの削除#

DELETE /api/deployments/{deploymentId}

デプロイメントの開始#

POST /api/deployments/{deploymentId}/start

停止中のデプロイメントを再開します。

デプロイメントの停止#

POST /api/deployments/{deploymentId}/stop

サービスの最小インスタンス数と最大インスタンス数をゼロに設定して、リクエストの処理を停止します。

ヘルスチェック#

GET /api/deployments/{deploymentId}/health

デプロイメントエンドポイントの健全性ステータスを返します。

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

POST /api/deployments/{deploymentId}/predict

画像をデプロイメントエンドポイントに直接送信して推論します。機能的にはモデルの予測と同じですが、低レイテンシのために専用エンドポイントを経由します。

Multipart Form:

パラメータ	タイプ	デフォルト	範囲	説明
`file`	ファイル	-	-	画像または動画ファイル（`source` が設定されている場合を除き必須）
`conf`	float	0.25	0.01 – 1.0	最小信頼度しきい値
`iou`	float	0.7	0.0 – 0.95	NMS IoUしきい値
`imgsz`	int	640	32 – 1280	入力画像のサイズ（ピクセル単位）
`normalize`	bool	false	-	バウンディングボックスの座標を0～1で返します
`decimals`	int	5	0 – 10	座標値の小数点以下の精度
`source`	string	-	-	画像 URL または base64 文字列（`file` の代替）

fileまたはsourceのいずれかを指定してください。レスポンスはモデル予測と同じ画像およびメタデータの契約を使用し、内部モデルのパスを返すことはありません。

メトリクスの取得#

GET /api/deployments/{deploymentId}/metrics

リクエスト数、レイテンシ、エラー率のメトリクスをスパークラインデータとともに返します。

クエリパラメータ:

パラメータ	タイプ	説明
`range`	string	時間範囲：`1h`、`6h`、`24h`（デフォルト）、`7d`、`30d`
`sparkline`	string	ダッシュボードビュー用の最適化されたスパークラインデータを含めるには、`true`に設定します

ログの取得#

GET /api/deployments/{deploymentId}/logs

クエリパラメータ:

パラメータ	タイプ	説明
`severity`	string	カンマ区切りのフィルタ：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`
`limit`	int	エントリー数（デフォルト: 50、最大: 200）
`pageToken`	string	前回のレスポンスからのページネーショントークン

エクスポートAPI#

エッジデプロイメントのために、モデルをONNX、TensorRT、CoreML、LiteRTなどの最適化されたフォーマットに変換します。詳細はDeploy documentationをご覧ください。

エクスポート一覧#

GET /api/exports

クエリパラメータ:

パラメータ	タイプ	説明
`modelId`	string	モデルID（必須）
`status`	string	ステータスによるフィルタリング
`limit`	int	最大結果数（デフォルト: 20、最大: 100）

エクスポート作成#

POST /api/exports

ボディ:

フィールド	タイプ	必須	説明
`modelId`	string	はい	ソースモデルID
`format`	string	はい	エクスポート形式（下表参照）
`gpuType`	string	条件付き	`format`が`engine`である場合に必須です。サポートされているGPUまたはJetsonのターゲットを使用してください。
`args`	オブジェクト	いいえ	エクスポート引数（`imgsz`、`quantize`、`dynamic`など）

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelId": "MODEL_ID", "format": "onnx"}' \
  https://platform.ultralytics.com/api/exports

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

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

形式	`format` 引数	モデル	メタデータ	引数
PyTorch	-	`yolo26n.pt`	✅	-
TorchScript	`torchscript`	`yolo26n.torchscript`	✅	`imgsz`, `quantize`, `dynamic`, `nms`, `batch`, `device`
ONNX	`onnx`	`yolo26n.onnx`	✅	`imgsz`、`quantize`、`dynamic`、`simplify`、`opset`、`nms`、`batch`、`data`、`fraction`、`device`
OpenVINO	`openvino`	`yolo26n_openvino_model/`	✅	`imgsz`、`quantize`、`dynamic`、`nms`、`batch`、`data`、`fraction`、`device`
TensorRT	`engine`	`yolo26n.engine`	✅	`imgsz`、`quantize`、`dynamic`、`simplify`、`opset`、`workspace`、`nms`、`batch`、`data`、`fraction`、`device`
CoreML	`coreml`	`yolo26n.mlpackage`	✅	`imgsz`, `dynamic`, `quantize`, `nms`, `batch`, `device`
TF SavedModel	`saved_model`	`yolo26n_saved_model/`	✅	`imgsz`、`keras`、`quantize`、`opset`、`nms`、`batch`、`data`、`fraction`、`device`
TF GraphDef	`pb`	`yolo26n.pb`	❌	`imgsz`, `opset`, `batch`, `device`
TF Edge TPU	`edgetpu`	`yolo26n_edgetpu.tflite`	✅	`imgsz`, `quantize`, `opset`, `data`, `fraction`, `device`
PaddlePaddle	`paddle`	`yolo26n_paddle_model/`	✅	`imgsz`、`batch`、`device`
MNN	`mnn`	`yolo26n.mnn`	✅	`imgsz`、`batch`、`dynamic`、`quantize`、`simplify`、`opset`、`nms`、`device`
NCNN	`ncnn`	`yolo26n_ncnn_model/`	✅	`imgsz`, `quantize`, `batch`, `device`
IMX500	`imx`	`yolo26n_imx_model/`	✅	`imgsz`, `quantize`, `data`, `fraction`, `nms`, `device`
RKNN	`rknn`	`yolo26n_rknn_model/`	✅	`imgsz`、`batch`、`name`、`quantize`、`simplify`、`opset`、`data`、`fraction`、`device`
ExecuTorch	`executorch`	`yolo26n_executorch_model/`	✅	`imgsz`、`batch`、`device`
Axelera	`axelera`	`yolo26n_axelera_model/`	✅	`imgsz`, `batch`, `quantize`, `data`, `fraction`, `device`
DEEPX	`deepx`	`yolo26n_deepx_model/`	✅	`imgsz`, `quantize`, `simplify`, `opset`, `data`, `optimize`, `device`
Qualcomm QNN	`qnn`	`yolo26n_qnn.onnx`	✅	`imgsz`、`batch`、`name`、`quantize`、`simplify`、`opset`、`data`、`fraction`、`device`
LiteRT	`litert`	`yolo26n.tflite`	✅	`imgsz`, `quantize`, `batch`, `data`, `fraction`, `device`
Hailo	`hailo`	`yolo26n_hailo_model/`	✅	`imgsz`、`name`、`quantize`、`data`、`fraction`、`simplify`、`conf`、`iou`
Huawei Ascend	`ascend`	`yolo26n_ascend_model/`	✅	`imgsz`, `batch`, `name`, `quantize`, `opset`, `simplify`, `nms`

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

GET /api/exports/{exportId}

エクスポートのキャンセル#

DELETE /api/exports/{exportId}

エクスポートダウンロードの追跡#

POST /api/exports/{exportId}/track-download

アクティビティAPI#

アカウントに関する最近のアクション（トレーニングの実行、アップロードなど）のフィードを表示します。詳細はActivity documentationをご覧ください。

ルートごとのAPIキーサポート

以下のすべてのアクティビティルートはAPIキー認証を受け付けます。

アクティビティ一覧#

GET /api/activity

クエリパラメータ:

パラメータ	タイプ	説明
`limit`	int	ページサイズ（デフォルト: 20、最大: 100）
`page`	int	ページ番号（デフォルト: 1）
`archived`	boolean	アーカイブタブの場合は`true`、受信トレイの場合は`false`
`search`	string	イベントフィールドの大文字と小文字を区別しない検索
`start`	日付	この日付以降のイベントを含める
`end`	日付	この日付以前のイベントを含める
`export`	boolean	一致するすべてのイベントをJSONとして返す
`owner`	string	ワークスペースのユーザー名

イベントを既読にする#

POST /api/activity/mark-seen

ボディ:

{
    "all": true
}

または特定のIDを渡す:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"]
}

ワークスペース内のイベントにマークを付けるには、オプションのownerクエリパラメータを渡します。

イベントのアーカイブ#

POST /api/activity/archive

ボディ:

{
    "all": true,
    "archive": true
}

または特定のIDを渡す:

{
    "eventIds": ["EVENT_ID_1", "EVENT_ID_2"],
    "archive": false
}

ワークスペースのイベントをアーカイブまたは復元するには、オプションのownerクエリパラメータを渡します。

ゴミ箱API#

削除されたアイテムの表示と復元を行います。アイテムは30日後に完全に削除されます。詳細はTrash documentationをご覧ください。

ゴミ箱一覧#

GET /api/trash

クエリパラメータ:

パラメータ	タイプ	説明
`type`	string	フィルタ：`all`、`project`、`dataset`、`model`
`page`	int	ページ番号（デフォルト: 1）
`limit`	int	ページあたりのアイテム数（デフォルト: 50、最大: 200）
`owner`	string	ワークスペース所有者のユーザー名

アイテムの復元#

POST /api/trash

ボディ:

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

アイテムの完全削除#

DELETE /api/trash

ボディ:

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

元に戻せません

完全削除は取り消すことができません。リソースおよびすべての関連データが削除されます。

ゴミ箱を空にする#

DELETE /api/trash/empty

ゴミ箱内のすべてのアイテムを完全に削除します。

認証

DELETE /api/trash/emptyではAPIキー認証を受け付け、選択されたアカウントまたはワークスペースのゴミ箱にあるすべてのアイテムを完全に削除します。

請求API#

クレジット残高、プランの使用状況、取引履歴を確認します。詳細はBilling documentationをご覧ください。

残高および取引のエンドポイントでは、ワークスペースの所有者のユーザー名を指定したオプションのownerクエリパラメータを受け付けます。

通貨単位

請求金額はセント単位（creditsCents）を使用します（ここで100 = $1.00）。

残高取得#

GET /api/billing/balance

レスポンス:

{
    "creditsCents": 2500,
    "plan": "free"
}

利用状況サマリーの取得#

GET /api/billing/usage-summary

プランの詳細、制限、使用メトリクスを返します。

取引履歴の取得#

GET /api/billing/transactions

取引履歴（最新のものから順に）を返します。

トランザクションには、金額、最終残高、日付、オプションのモデルコンテキスト、領収書URLなどのクライアント向け台帳フィールドが含まれます。内部メモ、Stripeの支払い/返金ID、およびべき等キーは返されません。

ストレージAPI#

カテゴリ別（データセット、モデル、エクスポート）のストレージ使用状況の内訳を確認し、容量の大きい項目を表示します。

APIキーアクセス

GET /api/storageではAPIキー認証を受け付けます。同様のインタラクティブな内訳を表示するには、Settings > Profileページを使用してください。

ストレージ情報の取得#

GET /api/storage

クエリパラメータ:

パラメータ	タイプ	説明
`details`	boolean	Set to `true` to include `topItems` (largest datasets, models, exports).
`owner`	string	ワークスペースのユーザー名。

レスポンス:

{
    "tier": "free",
    "usage": {
        "storage": {
            "current": 1073741824,
            "limit": 107374182400,
            "percent": 1.0
        }
    },
    "region": "us",
    "username": "johndoe",
    "updatedAt": "2024-01-15T10:00:00Z",
    "breakdown": {
        "byCategory": {
            "datasets": { "bytes": 536870912, "count": 2 },
            "models": { "bytes": 268435456, "count": 4 },
            "exports": { "bytes": 268435456, "count": 3 }
        },
        "topItems": [
            {
                "_id": "dataset_abc123",
                "name": "my-dataset",
                "slug": "my-dataset",
                "sizeBytes": 536870912,
                "type": "dataset"
            },
            {
                "_id": "model_def456",
                "name": "experiment-1",
                "slug": "experiment-1",
                "sizeBytes": 134217728,
                "type": "model",
                "parentName": "My Project",
                "parentSlug": "my-project"
            }
        ]
    }
}

クラウドストレージの統合#

読み取り専用のGCS、S3、またはAzure Blobストレージ統合を接続して参照します。

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

4つの操作すべてにおいて、ワークスペースを指定するオプションのownerクエリパラメータを受け付けます。オブジェクトの閲覧ではさらに、必須のtargetに加え、オプションのprefixおよびプロバイダーのcursorクエリパラメータを受け付けます。接続および検出のリクエストボディには、インタラクティブなOpenAPIリファレンスにあるプロバイダー資格情報のスキーマを使用します。資格情報が返されることはありません。

アップロードAPI#

署名付きURLを使用してファイルをクラウドストレージに直接アップロードし、高速で信頼性の高い転送を行います。モデルのアップロードを完了すると、その重みが添付されます。データセットアーカイブのアップロードを完了するとセッションが記録されます。そのsessionIdをPOST /api/datasets/ingestに渡して処理を開始してください。詳細はData documentationをご覧ください。

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

POST /api/upload/signed-url

ファイルをクラウドストレージに直接アップロードするための署名付きURLを要求します。署名付きURLを使用することで、大容量ファイルの転送時にAPIサーバーを介さずに済みます。

ボディ:

{
    "assetType": "datasets",
    "assetId": "dataset_abc123",
    "filename": "my-dataset.zip",
    "contentType": "application/zip",
    "totalBytes": 52428800
}

フィールド	タイプ	説明
`assetType`	string	アセットタイプ：`models`、`datasets`、`images`、`videos`
`assetId`	string	ターゲットアセットのID
`filename`	string	元のファイル名
`contentType`	string	MIMEタイプ
`totalBytes`	int	バイト単位のファイルサイズ

レスポンス:

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

アップロードの完了#

POST /api/upload/complete

ファイルのアップロードが完了したことをプラットフォームに通知します。モデルの場合は、これによりアップロードされた重みが添付されます。データセットアーカイブの場合は、これによりアップロードセッションが検証および記録されます。データセットの処理を開始するには、その後でPOST /api/datasets/ingestを呼び出してください。

ボディ:

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

インテグレーションAPI#

サードパーティサービスからデータセットをインポートします。詳細はIntegrations documentationをご覧ください。

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

POST /api/integrations/roboflow/preview

Roboflow APIキーをバルクインポート計画に解決します。ワークスペース情報、新しくインポートされるプロジェクト、すでにインポート済みのバージョン数（スキップ）、およびサポートされていないプロジェクトタイプが対象です。Roboflow APIキーはボディで渡され、永続化されません。

Roboflowからのインポート#

POST /api/integrations/roboflow/import

選択したRoboflowプロジェクトをワークスペースにインポートするためのデータセット取り込みジョブをキューに入れます。ストレージの余裕が必要であり、各データセットはプランごとのインポートサイズ制限内に収まる必要があります。

APIキーAPI#

プログラムによるアクセスのためにAPIキーを管理します。詳細はAPI Keys documentationをご覧ください。

APIキーの一覧表示#

GET /api/api-keys

APIキーで認証されたクライアントはキーのメタデータを受け取り、既存のキーの値が復号されて返されることはありません。新しく作成されたキーは、POST /api/api-keysによって一度だけ返されます。

編集者権限を持つワークスペースのキーを管理するには、オプションのownerクエリパラメータを渡します。

APIキーの作成#

POST /api/api-keys

ボディ:

{
    "name": "training-server"
}

APIキーの削除#

DELETE /api/api-keys

クエリパラメータ:

パラメータ	タイプ	説明
`keyId`	string	取り消すAPIキーのID
`owner`	string	オプションのワークスペースユーザー名。

例:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/api-keys?keyId=KEY_ID"

チーム＆メンバーAPI#

チームワークスペースを作成し、メンバーを招待し、コラボレーションのためのロールを管理します。詳細はTeams documentationをご覧ください。

チームの一覧表示#

GET /api/teams

チームの作成#

POST /api/teams/create

ボディ:

{
    "username": "my-team",
    "fullName": "My Team"
}

メンバーの一覧表示#

GET /api/members

現在のワークスペースのメンバーを返します。

メンバーの招待#

POST /api/members

ボディ:

{
    "email": "user@example.com",
    "role": "editor"
}

メンバーのロール

ロール	権限
`viewer`	ワークスペースリソースへの読み取り専用アクセス
`editor`	リソースの作成、編集、削除
`admin`	メンバー、請求、およびすべてのリソースの管理（チームオーナーのみ割り当て可能）

チームのownerは作成者であり、招待することはできません。所有者の移行は、POST /api/members/transfer-ownershipを介して個別に実行されます。ロールの詳細については、Teamsをご覧ください。

メンバーロールの更新#

PATCH /api/members/{userId}

メンバーの削除#

DELETE /api/members/{userId}

所有権の譲渡#

POST /api/members/transfer-ownership

探索API#

コミュニティによって共有された公開データセットやプロジェクトを検索・閲覧します。詳細はExplore documentationをご覧ください。

公開コンテンツの検索#

GET /api/explore/search

クエリパラメータ:

パラメータ	タイプ	説明
`q`	string	検索クエリ
`type`	string	リソースタイプ：`all`（デフォルト）、`projects`、`datasets`
`sort`	string	ソート順：`newest`（デフォルト）、`stars`、`oldest`、`name-asc`、`name-desc`、`count-desc`、`count-asc`
`offset`	int	ページネーションのオフセット（デフォルト: 0）。結果は1ページあたり20項目を返します。
`task`	string	オプション：データセットをフィルタリングするためのカンマ区切りのYOLOタスクタイプ（`detect`、`segment`、`semantic`、`classify`、`pose`、`obb`）
`author`	string	オプションの所有者ユーザー名フィルター。
`starred`	boolean	認証された呼び出し元がスターを付けたコンテンツを返すには、`true`を設定します。APIキーが必要です。

サイドバーデータ#

GET /api/explore/sidebar

探索サイドバー用の厳選されたコンテンツを返します。

ユーザー＆設定API#

プロフィール、APIキー、ストレージの使用量、チームワークスペースを管理します。詳細はSettings documentationをご覧ください。

アカウントの概要#

GET /api/account/summary

認証されたアカウントのプラン、クレジット残高、リソース数、およびチームワークスペースを返します。

ユーザー名によるユーザー取得#

GET /api/users

クエリパラメータ:

パラメータ	タイプ	説明
`username`	string	検索するユーザー名

ユーザーのフォローまたはフォロー解除#

PATCH /api/users

ボディ:

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

ユーザー名の利用可否確認#

GET /api/username/check

クエリパラメータ:

パラメータ	タイプ	説明
`username`	string	確認するユーザー名
`suggest`	bool	オプション：すでに使用されている場合に提案を含めるための`true`

設定#

GET /api/settings
POST /api/settings

ユーザープロファイル設定（表示名、バイオ、ソーシャルリンクなど）の取得または更新。

ワークスペースアイコン#

POST /api/settings/icon
DELETE /api/settings/icon

マルチパートフォームフィールドimageとして最大5 MBのWebPプロファイル/ワークスペースアイコンをアップロードするか、削除します。チームワークスペースの場合は、オプションのownerを渡します。

Pythonの統合#

より簡単に統合するには、認証、アップロード、リアルタイムのメトリクスストリーミングを自動的に処理するUltralytics Pythonパッケージを使用してください。

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

pip install "ultralytics>=8.4.104"

インストールの確認:

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

パターン	説明
`ul://username/datasets/slug`	データセット
`ul://username/project-name`	プロジェクト
`ul://username/project/model-name`	特定のモデル
`ul://ultralytics/yolo26/yolo26n`	公式モデル

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

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

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

大量の結果をページネーションするにはどうすればよいですか？#

ほとんどのエンドポイントでは、リクエストごとに返される結果の数を制御するためにlimitパラメータを使用します：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/datasets?limit=50"

ActivityおよびTrashのエンドポイントでは、ページベースのページネーション用のpageパラメータもサポートしています：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.ultralytics.com/api/activity?page=2&limit=20"

The Explore Search endpoint uses offset instead of page, with a fixed page size of 20:

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

SDKなしでAPIを使用できますか？#

上記でドキュメント化されている公開REST操作は、Python SDKなしでも利用可能です。SDKは、リアルタイムのメトリクスストリーミングや自動モデルアップロードなどの機能を追加する便利なラッパーです。機械読み取り可能な契約をplatform.ultralytics.com/api/docsでインタラクティブに確認できます。ブラウザセッション専用のアカウントフローはPlatform UIに残ります。

APIクライアントライブラリはありますか？#

Ultralytics Pythonパッケージを使用するか、任意の言語から直接HTTPリクエストを行います。

レート制限にはどのように対処すればよいですか？#

適切な時間待機するには、429レスポンスからのRetry-Afterヘッダーを使用します：

import time

import requests

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

モデルまたはデータセットのIDはどこで確認できますか？#

リソースIDは、作成、一覧取得、および取得のAPIレスポンスによって返されます。PlatformのページURLはデータベースIDではなく、人間が読めるスラッグを使用します：

https://platform.ultralytics.com/username/project/model-name
                                  ^^^^^^^^ ^^^^^^^ ^^^^^^^^^^
                                  username project   model

リストエンドポイントを使用して、モデル、データセット、プロジェクト、デプロイメント、またはその他のリソースに対応する_idを見つけてください。

貢献者

GLglenn-jocher³⁵ SEsergiuwaxmann² MYmykolaxboiko² AMamanharshx¹ AMambitious-octopus¹ ONonuralpszr¹ LAlaodouya¹ RAraimbekovm¹ LALaughing-q¹

作成日 2026年1月14日更新日昨日