> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-comfy-docs-comfyapi-search.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Comfy Router API リファレンス
> Comfy API 契約から生成済みの、Comfy Router のすべてのエンドポイント、パラメータ、レスポンスボディ、エラーバケット。
モデル ID でアドレス指定される Comfy Router の正規ルート。
ベース URL: `https://api.comfy.org`
以下のすべてのエンドポイントは認証が必要です。`X-API-Key: ` または `Authorization: Bearer ` を送信してください。
Comfy API キーは Bearer トークンとして送信することもできます。両方の認証ヘッダーが指定された場合、`X-API-Key` が優先されます。キーと JWT の違いについては[認証ヘッダー](/ja/development/comfy-router/quickstart)を、アクセス要件については[クイックスタート](/ja/development/comfy-router/quickstart)を参照してください。
## エンドポイント
### `GET /v2/models`
**Comfy Router が実行できるモデルを一覧表示します。**
利用可能なモデル ID と課金情報を一覧表示します。`has_more` が true の間は `next_cursor` を使用します。
**パラメータ**
| 名前 | 場所 | 必須 | 型 | 制約 | 説明 |
| -------- | ----- | --- | --------------------------------------- | ------------------------------------- | ----------------- |
| `cursor` | query | いいえ | [`RouterPageCursor`](#routerpagecursor) | `next_cursor` として返される不透明カーソル、1～512 文字 | 不透明なページネーションカーソル。 |
| `limit` | query | いいえ | integer | 最大 100、デフォルト: 20 | 1 ページで返すモデル数。 |
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| ----- | ----------------------------------------------------- | ------------------------------------------ | ------------------------------------- |
| `200` | [`RouterModelListResponse`](#routermodellistresponse) | `X-Comfy-Request-Id` | OK - モデルカタログの 1 ページ。 |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 無効なリクエスト。エラー種別とリクエストボディを確認してください。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し元またはモデルでは、このリクエストは許可されていません。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router は一時的に利用できません。バックオフして再試行してください。 |
### `GET /v2/models/{provider}/{model}`
**正規のモデル ID でパートナーモデル 1 件のカタログエントリを読み取ります。**
カタログ全体を一覧表示せずに、1 つのモデルの詳細を読み取ります。
**パラメータ**
| 名前 | 場所 | 必須 | 型 | 制約 | 説明 |
| ---------- | ---- | --- | ------------------------------------------------- | ---------------------------------------- | ------------------------------------------ |
| `provider` | path | yes | [`RouterProviderSegment`](#routerprovidersegment) | 英数字のスラッグ（例: `anthropic`）、最大 64 文字 | 正規の `{provider}/{model}` モデル ID のプロバイダー部分。 |
| `model` | path | yes | [`RouterModelSegment`](#routermodelsegment) | 英数字のスラッグ（例: `claude-opus-4-6`）、最大 128 文字 | 正規の `{provider}/{model}` モデル ID のモデル部分。 |
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| ----- | --------------------------------------------- | ------------------------------------------ | ------------------------------------- |
| `200` | [`RouterModelDetail`](#routermodeldetail) | `X-Comfy-Request-Id` | OK - モデルのカタログエントリ。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し元またはモデルに対してリクエストが許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | モデル ID が見つかりませんでした。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router が一時的に利用できません。バックオフして再試行してください。 |
### `POST /v2/models/{provider}/{model}`
**正規のモデル ID を指定してパートナーモデルを同期的に実行します。**
モデルを実行し、完了した結果を同じレスポンスで受け取ります。
**パラメータ**
| 名前 | In | 必須 | 型 | 制約 | 説明 |
| ----------------- | ------ | --- | ------------------------------------------------- | ---------------------------------------- | ------------------------------------------ |
| `provider` | path | yes | [`RouterProviderSegment`](#routerprovidersegment) | 英数字のスラッグ（例: `anthropic`）、最大 64 文字 | 正規の `{provider}/{model}` モデル ID のプロバイダー部分。 |
| `model` | path | yes | [`RouterModelSegment`](#routermodelsegment) | 英数字のスラッグ（例: `claude-opus-4-6`）、最大 128 文字 | 正規の `{provider}/{model}` モデル ID のモデル部分。 |
| `Idempotency-Key` | header | no | string | 1〜255 文字 | 1 回の論理的な呼び出しを安全に再試行できるようにする、呼び出し側が生成するキー。 |
**リクエストボディ**
`application/json`: [`RouterModelInput`](#routermodelinput)（必須）
パートナーモデルのネイティブな JSON 入力。プロバイダーへそのまま転送されます。
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| ----- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | [`RouterModelOutput`](#routermodeloutput) | `X-Comfy-Request-Id`, `X-Content-Type-Options`, `Idempotent-Replayed`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining` | OK: パートナーモデルのネイティブな出力が、パートナー自身のメディアタイプでそのまま返されます。 |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`, `Idempotent-Replayed` | 無効なリクエストです。エラータイプとリクエストボディを確認してください。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し元またはモデルでは、このリクエストは許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | モデル ID が見つかりませんでした。 |
| `409` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After`（`concurrency_limit_exceeded` の場合） | `X-Comfy-Error-Type` を確認してください。`concurrency_limit_exceeded` はオリジナルの呼び出しがまだ実行中であることを意味するため、`Retry-After` を待って同じキーを再利用します。`invalid_input` の場合は新しいキーが必要です。 |
| `413` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | リクエストボディが大きすぎます。 |
| `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed` | リクエストの内容がモデルのスキーマに照らして拒否されました。 |
| `429` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining` | `X-Comfy-Error-Type` を確認してください。`concurrency_limit_exceeded` は実行中の呼び出しを減らすことを意味し、`rate_limited` は許容量のウィンドウを待つことを意味します。 |
| `502` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status` | プロバイダー自身のレスポンスを結果に変換できませんでした（`provider_error`）。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router は一時的に利用できません。バックオフを伴って再試行してください。 |
| `504` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`, `Retry-After` | リクエストがデッドラインを超過しました。再試行する前にエラータイプを確認してください。 |
### `GET /v2/models/{provider}/{model}/openapi.json`
**1つのパートナーモデルの入力スキーマと出力スキーマをOpenAPIドキュメントとして読み取ります。**
1つのモデルの入力スキーマと出力スキーマを単体のOpenAPIドキュメントとして読み取ります。
**パラメータ**
| 名前 | 場所 | 必須 | 型 | 制約 | 説明 |
| --------------- | ------ | --- | ------------------------------------------------- | -------------------------------------- | ---------------------------------------- |
| `provider` | path | はい | [`RouterProviderSegment`](#routerprovidersegment) | 英数字のスラッグ（例: `anthropic`）、最大64文字 | 正規の `{provider}/{model}` モデルIDのプロバイダー部分。 |
| `model` | path | はい | [`RouterModelSegment`](#routermodelsegment) | 英数字のスラッグ（例: `claude-opus-4-6`）、最大128文字 | 正規の `{provider}/{model}` モデルIDのモデル部分。 |
| `If-None-Match` | header | いいえ | 文字列 | - | 呼び出し元が以前の `200` から保持している `ETag`。 |
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| ----- | ------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| `200` | [`RouterModelInputSchemaDocument`](#routermodelinputschemadocument) | `X-Comfy-Request-Id`、`ETag`、`Cache-Control` | OK - モデルの入力と出力の両スキーマを、単体のOpenAPIドキュメントとして返します。 |
| `304` | - | `X-Comfy-Request-Id`、`ETag`、`Cache-Control` | Not Modified - 呼び出し元が `If-None-Match` で送信した `ETag` 以降、ドキュメントは変更されていません。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`、`X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`、`X-Comfy-Request-Id` | この呼び出し元またはモデルに対して、リクエストは許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`、`X-Comfy-Request-Id` | モデルIDが見つかりませんでした。 |
| `500` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`、`X-Comfy-Request-Id` | Routerがリクエストを完了できませんでした。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`、`X-Comfy-Request-Id` | Routerは一時的に利用できません。バックオフして再試行してください。 |
### `POST /v2/models/{provider}/{model}/requests`
**パートナーモデルの実行をキューに送信し、すぐに戻ります。**
Comfy Router の QUEUED 配信モードです。リクエストボディは、`POST /v2/models/{provider}/{model}` がこのモデルに対して受け付けるものと同じパートナー固有の JSON 入力です。1 つのボディ形状、モデルごとに 1 つのスキーマ、2 つの配信モードがありますが、このルートは結果を待つために接続を保持しません。実行を受理し、ハンドルとともに `201` を返します。呼び出し側は後で、以下の 3 つの読み取りを通じて結果を取得します。
**パラメータ**
| 名前 | In | 必須 | 型 | 制約 | 説明 |
| ----------------- | ------ | --- | ------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| `provider` | path | はい | [`RouterProviderSegment`](#routerprovidersegment) | 英数字のスラッグ（例: `anthropic`）、最大 64 文字 | 正規の `{provider}/{model}` モデル ID の小文字のプロバイダーセグメント。実行するモデルを持つパートナーです。 |
| `model` | path | はい | [`RouterModelSegment`](#routermodelsegment) | 英数字のスラッグ（例: `claude-opus-4-6`）、最大 128 文字 | 正規の `{provider}/{model}` モデル ID の小文字のモデルセグメント。そのプロバイダー内で実行するモデルです。 |
| `Idempotency-Key` | header | いいえ | string | 1～255 文字 | 呼び出し側が生成するキーで、1 つの論理的な呼び出しを安全に再試行できるようにします。 |
**リクエストボディ**
`application/json` -- [`RouterModelInput`](#routermodelinput)（必須）
パートナーモデル固有の JSON 入力で、同期ルートがこのモデルに対して受け付けるボディと同一です。実行が受理される前に、モデル自身の入力スキーマに対して検証されます。そのため、モデルが拒否するボディは、数分後に失敗するキュー中のリクエストになるのではなく、ここで `422` となります。
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| ----- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `201` | [`RouterQueueSubmitResponse`](#routerqueuesubmitresponse) | `X-Comfy-Request-Id`, `Idempotent-Replayed` | 作成済み。実行がキューに受理されました。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 無効なリクエストです。エラータイプとリクエストボディを確認してください。 |
| `413` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | リクエストボディが大きすぎます。 |
| `402` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router のリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗しました。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し側またはモデルでは、このリクエストは許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | モデル ID が見つかりませんでした。 |
| `409` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After`（`concurrency_limit_exceeded` の場合） | `X-Comfy-Error-Type` を確認してください。`concurrency_limit_exceeded` は元の呼び出しがまだ実行中であることを意味するため、`Retry-After` を待って同じキーを再利用します。`invalid_input` の場合は新しいキーが必要です。 |
| `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed` | リクエストの内容がモデルのスキーマに対して拒否されました。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router は一時的に利用できません。バックオフして再試行してください。 |
### `GET /v2/models/{provider}/{model}/requests/{request_id}`
**送信済みリクエスト1件の結果を収集します。**
収集エンドポイントです。正常に完了したリクエストでは、パートナーモデル自身のネイティブ出力を返します。これは、同じモデルと同じ入力に対して同期ルートの `200` が返すものとバイト単位で同一です。そのため、2つの配信モードは1つの結果形状を生成し、呼び出し元は2つ目のパーサーなしでそれらの間を行き来できます。
**パラメータ**
| 名前 | 場所 | 必須 | 型 | 制約 | 説明 |
| ------------ | ---- | -- | ------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `provider` | path | はい | [`RouterProviderSegment`](#routerprovidersegment) | 英数字のスラッグ（例: `anthropic`）、最大64文字 | 正規の `{provider}/{model}` モデル ID の小文字プロバイダーセグメント。モデルを実行するパートナーを示します。 |
| `model` | path | はい | [`RouterModelSegment`](#routermodelsegment) | 英数字のスラッグ（例: `claude-opus-4-6`）、最大128文字 | 正規の `{provider}/{model}` モデル ID の小文字モデルセグメント。そのプロバイダー内で実行するモデルです。 |
| `request_id` | path | はい | [`RouterQueueRequestId`](#routerqueuerequestid) | `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`、uuid、最大36文字 | 対象とするキュー中のリクエスト。送信時に返された `request_id` であり、その送信の `X-Comfy-Request-Id` ヘッダーが保持していた値でもあります。 |
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | [`RouterModelOutput`](#routermodeloutput) | `X-Comfy-Request-Id`, `X-Content-Type-Options` | OK: 出力を生成したリクエストに対するパートナーモデルのネイティブ出力です。正常に完了したリクエスト、または記録済みの課金と保存済みの結果の両方を持つターミナルリクエストが該当し、パートナー自身のメディアタイプのまま変更されずに返されます。同期ルートの `200` が返すのとまったく同じです。 |
| `202` | [`RouterQueueStatusResponse`](#routerqueuestatusresponse) | `X-Comfy-Request-Id`, `Retry-After` | Accepted: リクエストはまだ完了していません。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し元またはモデルに対してリクエストが許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | モデル ID が見つかりませんでした。 |
| `410` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router のリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自体が報告しなかった理由で失敗しました。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router は一時的に利用できません。バックオフして再試行してください。 |
| `409` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | リクエストが操作と競合する状態にあります。エラータイプを確認してください。 |
| `504` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | リクエストが期限を超過しました。再試行する前にエラータイプを確認してください。 |
| `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed` | リクエストのコンテンツがモデルのスキーマに照らして拒否されました。 |
| `default` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router のリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自体が報告しなかった理由で失敗しました。 |
### `PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel`
**送信済みのリクエスト1件にキャンセルを要求します。**
まだ完了していないリクエストを停止するよう Comfy に要求します。これは要求であり、保証ではありません。`202` が示しているのはまさにそのとおりで、`CANCELLATION_REQUESTED` は要求が受理されたことを意味するだけで、実行が停止したことを意味するものではありません。すでにパートナー側へ送出された実行はそのまま完了してしまう可能性があります。そして完了したパートナー生成は、誰かが結果を取得したかどうかに関わらず課金されます。そのため、実際に何が起きたかを知る必要がある呼び出し元は、後からステータスエンドポイントを参照します。そこでは、実際に有効になったキャンセルは、他のあらゆるターミナルな結果と同様に `error_type` を伴う `COMPLETED` になります。
**パラメータ**
| 名前 | 場所 | 必須 | 型 | 制約 | 説明 |
| ------------ | -- | -- | ------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `provider` | パス | はい | [`RouterProviderSegment`](#routerprovidersegment) | 英数字スラッグ（例: `anthropic`）、最大64文字 | 正規の `{provider}/{model}` モデル ID の小文字プロバイダーセグメント。実行対象のモデルを持つパートナーです。 |
| `model` | パス | はい | [`RouterModelSegment`](#routermodelsegment) | 英数字スラッグ（例: `claude-opus-4-6`）、最大128文字 | 正規の `{provider}/{model}` モデル ID の小文字モデルセグメント。そのプロバイダー内で実行するモデルです。 |
| `request_id` | パス | はい | [`RouterQueueRequestId`](#routerqueuerequestid) | `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`、uuid、最大36文字 | 対象となるキュー中のリクエスト。送信時に返された `request_id` であり、その送信の `X-Comfy-Request-Id` ヘッダーが保持していた値でもあります。 |
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| --------- | --------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------- |
| `202` | [`RouterQueueCancelResponse`](#routerqueuecancelresponse) | `X-Comfy-Request-Id` | 受理: `CANCELLATION_REQUESTED`。 |
| `409` | [`RouterQueueCancelResponse`](#routerqueuecancelresponse) | `X-Comfy-Request-Id` | 競合: `ALREADY_COMPLETED`。 |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 無効なリクエスト。エラータイプとリクエストボディを確認してください。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し元またはモデルに対して、そのリクエストは許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | モデル ID が見つかりませんでした。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router は一時的に利用できません。バックオフしながら再試行してください。 |
| `default` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router のリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗しました。 |
### `GET /v2/models/{provider}/{model}/requests/{request_id}/status`
**送信済みの1件のリクエストのキュー状態を読み取ります。**
ポーリング用のエンドポイントです。リクエストの現在の状態のみを返し、結果は返しません。そのためクライアントは、ポーリングのたびに出力を転送することなく、長時間かかる生成を監視できます。結果は、これが `COMPLETED` を返したときに、後述の読み取りエンドポイントから一度だけ取得します。
**パラメータ**
| 名前 | 場所 | 必須 | 型 | 制約 | 説明 |
| ------------ | ---- | -- | ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `provider` | path | はい | [`RouterProviderSegment`](#routerprovidersegment) | 英数字のスラッグ（例: `anthropic`）、最大64文字 | 正規の `{provider}/{model}` モデルIDの小文字のプロバイダーセグメント。実行するモデルを持つパートナー。 |
| `model` | path | はい | [`RouterModelSegment`](#routermodelsegment) | 英数字のスラッグ（例: `claude-opus-4-6`）、最大128文字 | 正規の `{provider}/{model}` モデルIDの小文字のモデルセグメント。そのプロバイダー内で実行するモデル。 |
| `request_id` | path | はい | [`RouterQueueRequestId`](#routerqueuerequestid) | `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`、uuid、最大36文字 | 対象とするキュー中のリクエスト。送信時に返された `request_id` であり、その送信の `X-Comfy-Request-Id` ヘッダーが運んだ値でもあります。 |
**レスポンス**
| ステータス | ボディ | ヘッダー | 説明 |
| --------- | --------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- |
| `200` | [`RouterQueueStatusResponse`](#routerqueuestatusresponse) | `X-Comfy-Request-Id`, `Retry-After` | OK。リクエストの現在のキュー状態。 |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 認証情報が不足しているか無効です。 |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | この呼び出し元またはモデルに対してリクエストが許可されていません。 |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | モデルIDが見つかりませんでした。 |
| `410` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Routerのリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗しました。 |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Routerが一時的に利用できません。バックオフして再試行してください。 |
| `default` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Routerのリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗しました。 |
表の説明は簡潔です。モデルの選択、検証、再試行、課金については [Comfy Router API の使用](/ja/development/comfy-router/api) を、ヘッダーの動作については [ヘッダー](/ja/development/comfy-router/headers) を参照してください。
## エラーバケット
Router の機械可読なエラーカテゴリで、`X-Comfy-Error-Type` ヘッダーでも送信されます。
### リクエストレベルバケット
Router が受け付けたものの、完了できなかったリクエストに対して発生します。
| `error_type` | 意味 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_input` | リクエストがモデルに到達する前に拒否されました。ボディの形式が不正、ページネーションカーソルが不正または期限切れ、モデル自身のスキーマが受け付けない入力、またはこのリクエストに使用できない `Idempotency-Key`（別のリクエストで既に使用済み。方法、パスとクエリ、またはボディが異なる。もしくは、レスポンスを再生できない呼び出しによって既に消費済み）です。 |
| `content_policy_violation` | プロバイダーがコンテンツポリシーを理由にリクエストを拒否しました。 |
| `provider_error` | パートナープロバイダーが自身の障害を報告したか、Router が結果として解釈できないレスポンスを返しました。 |
| `provider_timeout` | パートナープロバイダーが期限までに応答しませんでした。 |
| `insufficient_credits` | 呼び出し元のワークスペースに、モデルを実行するための十分なクレジットがありません。 |
| `model_not_found` | `{provider}/{model}` という ID が、Router で実行できるモデルを指していません。不明なプロバイダーもここに分類されます。 |
### トランスポートレベルバケット
モデルへの呼び出しの前またはその周辺で、Router 自身によって発生します。
| `error_type` | 意味 |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| `unauthorized` | リクエストに利用可能な認証情報が含まれていませんでした。 |
| `forbidden` | 認証情報は有効ですが、このモデルまたはこの操作に対する権限がありません。 |
| `concurrency_limit_exceeded` | ワークスペースはすでに許可された数の呼び出しを実行中です。いずれかが完了したら再試行してください。 |
| `client_disconnected` | 呼び出し側が、Router が結果を返す前に接続を閉じました。 |
| `internal_error` | Router 自体が失敗しました。 |
| `deadline_exceeded` | 回答が到着する前に、Comfy が自身の設定済みの上限で接続の維持を停止しました。 |
| `not_enabled` | この呼び出し側に対して Comfy Router がまだ有効になっていません。 |
| `service_unavailable` | Comfy Router が依存するサービスが一時的に利用できず、呼び出し側に問題はありません。 |
| `rate_limited` | 呼び出し側がウィンドウ単位で測定される割り当てを消費し、そのウィンドウが経過するのを待つ必要があります。 |
| `cancelled` | キューに入っていたリクエストが、結果を生成する前に、キャンセルルートまたはオペレーターによって取り消されました。これはターミナルであり、それ自体は課金に関する表明ではありません。 |
| `queue_timeout` | キュー中のリクエストが、受け入れられないままキュータイムアウトを超えて待機し続けました。 |
| `request_not_found` | `request_id` が、このモデルにおける呼び出し元のどのリクエストも指していません。 |
## レスポンスヘッダー
| ヘッダー | 型 | 説明 |
| ----------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Cache-Control` | string | 提供されるスキーマドキュメントの鮮度ディレクティブ。 |
| `ETag` | string | `GET /v2/models/{provider}/{model}/openapi.json` で提供されるドキュメントのバイト列に対する強力なエンティティタグ。 |
| `Idempotent-Replayed` | boolean | このレスポンスがモデルを再度実行した結果ではなく、`Idempotency-Key` の記録から提供された場合に存在し、`true` になります。 |
| `Retry-After` | integer | 同じ `Idempotency-Key` で同じリクエストを再試行するまでに待つべき秒数。 |
| `X-Comfy-Error-Type` | [`RouterErrorType`](#routererrortype) | 障害を表す大まかで機械可読な分類で、Router がすべてのエラーレスポンスに設定します。 |
| `X-Comfy-Request-Id` | string | この呼び出しに対してサーバーが生成する識別子で、成功、4xx、5xx を問わず、すべての Router レスポンスに存在します。エラーレスポンスこそ、ユーザーがサポートリクエストで引用する ID を必要とするまさにその瞬間だからです。 |
| `X-Comfy-Upstream-Status` | integer | この呼び出しに対するモデルプロバイダー自身の HTTP ステータス。 |
| `X-Committed-Spend-Current` | integer | 呼び出し元が現在、まだ実行中の呼び出しに対してコミットしている金額（米ドルのセント単位）。 |
| `X-Committed-Spend-Limit` | integer | 呼び出し元がまだ実行中の呼び出しにコミットできるパートナー支出の上限（米ドルのセント単位）。この金額は呼び出しが受け付けられた時点で確保され、その呼び出しが完了した時点で解放されます。 |
| `X-Committed-Spend-Remaining` | integer | 上限までに残っている余裕（米ドルのセント単位）。下限は 0 です。 |
| `X-Content-Type-Options` | string | Router モデルのすべての成功した実行において、常に `nosniff` です。 |
## 結果アセット
モデルは、アセット URL、インラインバイト、またはその両方を返すことができます。以下のプロバイダーは、選択済みのアセットを Comfy ストレージにコピーし、その URL を置き換えます。この動作はモデルによって異なります。これを選択するリクエストヘッダーはありません。
| モデル | Comfy ストレージにコピーされるもの | Comfy ホスト URL の最大有効期間 |
| ---------------------------------------------------- | -------------------------------------- | --------------------- |
| `bfl/*` | 完了したアセット、および結果に含まれている場合はドラフトキャッシュのアセット | 24 時間 |
| `byteplus/*` ビデオモデル (`seedance`、`dreamina-seedance`) | 完了したビデオ、および結果に含まれている場合はラストフレーム画像 | 24 時間 |
| `minimax/*` | 完了したビデオ | 12 時間 |
| `xai/*` | 生成されたすべての画像、および完了したビデオ | 24 時間 |
これらの有効期間は、URL を開いたときではなく、URL が署名されたときに開始されます。キャッシュされた URL や再生された URL は残り時間が短い場合があります。再生しても有効期間は更新されません。アセットは速やかにダウンロードしてください。コピーされるのは各行に記載されたアセットのみです。`byteplus/seedream-*` と `byteplus/seededit-*` の画像は BytePlus ビデオの行には含まれません。
**Veo (`veo/*`) には別のストレージパスがあります。** `response.videos[]` では、存在する方のメンバーを読み取ってください。`bytesBase64Encoded` はクリップをインラインで含み、`gcsUri` は、プロバイダーから Comfy ストレージへの直接書き込みが環境で構成されている場合に、Comfy が署名した HTTPS リンクを含みます。そのリンクはレスポンスから 24 時間有効です。後者の場合はアセットをコピーするのではなく直接書き込むため、Veo は再ホスティングの表には含まれていません。
その他のモデルは、プロバイダーのアセット参照またはインラインバイトを返します。プロバイダーの URL はプロバイダーの有効期限に従います。これは上記の有効期間よりはるかに短い場合があり、Router の契約では規定されていません。
コピーはアセットごとのベストエフォートです。1 つのコピーが失敗した場合、そのエントリはプロバイダーの参照を保持します。レスポンスには Comfy とプロバイダーの両方の URL が含まれる可能性があり、アセットごとの明示的なコピーステータスフィールドはありません。生成は引き続き成功し、課金されます。1 つの正常に再ホストされたアセットから、すべての URL の有効期間を推測しないでください。
結果が Comfy ホストかどうかは、完了した呼び出しが後でその `Idempotency-Key` レコードから再生できるかどうかも決定します。上記の `Idempotency-Key` パラメーターは、再生できない場合に再試行が何で応答されるかを説明しています。
## モデルごとの入力および出力スキーマ
各モデルのフィールドは `GET /v2/models/{provider}/{model}/openapi.json` から読み取ります。オペレーションの `requestBody` は入力の検証を記述しており、その `200` レスポンスは、スキーマが作成されている場合に出力の形状とメディアタイプを記述しています。`x-comfy-input-schema-authored` が false の場合、Router はモデル固有の事前検証なしで任意の JSON オブジェクトを受け入れます。プロバイダーの要件は引き続き適用されます。出力スキーマは結果を記述するものであり、Router は返されたプロバイダーのペイロードをそれらに対して検証しません。スキーマが作成されていない出力では、`application/json` ではなく `*/*` が使用される場合があります。デコードする前にレスポンスのコンテンツタイプを確認してください。
## スキーマ
### RouterChargesOnPolicyRejection
このモデルでコンテンツポリシーによる拒否が課金されるかどうか。不明な値は課金される可能性があるものとして扱ってください。
型: `string`
### RouterErrorResponse
認証、アクセス、モデル検索、クォータ、およびプロバイダー転送の失敗に対するエラーボディ。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ------------ | ------------------------------------- | --- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detail` | string | yes | - | 失敗内容を人間が読める形式で記述したもの。エンドユーザーに提示しても安全です。機械的にパースされることはありません。分岐には `error_type` を使用してください。 |
| `error_type` | [`RouterErrorType`](#routererrortype) | yes | - | Router の失敗を表す粗い機械可読な分類。レスポンスヘッダー `X-Comfy-Error-Type` にも反映されるため、呼び出し側はボディをパースせずに分岐できます。値の集合は 15 個で固定されています。リクエストレベルの 6 つの分類 `invalid_input`、`content_policy_violation`、`provider_error`、`provider_timeout`、`insufficient_credits`、`model_not_found` に加えて、転送レベルの `unauthorized`、`forbidden`、`concurrency_limit_exceeded`、`client_disconnected`、`internal_error`、`deadline_exceeded`、`not_enabled`、`service_unavailable`、`rate_limited` があります。 |
### RouterErrorType
機械可読な Router エラーのカテゴリ。`X-Comfy-Error-Type` ヘッダーでも送信されます。
型: `string`
### RouterModelBilling
モデルを呼び出す前に確認すべき課金の挙動。価格や使用量は含まれません。
| フィールド | タイプ | 必須 | 制約 | 説明 |
| ----------------------------- | ------------------------------------------------------------------- | -- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `charges_on_policy_rejection` | [`RouterChargesOnPolicyRejection`](#routerchargesonpolicyrejection) | はい | - | このモデルがコンテンツポリシー上の理由で拒否した呼び出しが、それでも呼び出し元に課金されるかどうか。プロバイダーによって異なり、その違いは呼び出し時には見えず、同じ呼び出しに対してエラーと課金の両方を見たユーザーは知りようがありません。そのため、プロバイダーごとの慣習に任せるのではなく、呼び出し前にモデルごとに明記されています。 |
### RouterModelDetail
1つの Comfy Router モデルに対するモデル単位の詳細です。カタログ一覧が報告するすべての内容に加えて、単一モデルルートだけが持つモデル単位のフィールドを含みます。
[`RouterModelListEntry`](#routermodellistentry)、[`RouterModelDetailFields`](#routermodeldetailfields) を組み合わせます。
型: `object`
### RouterModelDetailFields
モデル詳細エンドポイントが返すオプションフィールド。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ------------------ | --- | --- | ------------------------------------------------------------------------------------ | ------------------------------------------- |
| `input_schema_url` | 文字列 | いいえ | HTTPS URL（例: `https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json`）、最大2048文字 | このモデルのOpenAPIドキュメントのURL。入力スキーマと出力スキーマを含みます。 |
### RouterModelId
`POST /v2/models/{provider}/{model}` で使用されるモデル ID。
型: `文字列`。モデル ID（例: `anthropic/claude-opus-4-6`）、最大 193 文字
### RouterModelInput
モデル入力オブジェクト。フィールドと検証については、選択済みモデルの OpenAPI ドキュメントを参照してください。
型: `object`
### RouterModelInputSchemaDocument
1つのモデルの入力と出力に対応するスタンドアロンの OpenAPI ドキュメント。
型: `object`
### RouterModelListEntry
モデルのIDと課金に関する事実。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ---------- | ------------------------------------------------- | -- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | [`RouterModelId`](#routermodelid) | はい | モデルID（例: `anthropic/claude-opus-4-6`）、最大193文字 | 正規の Comfy Router モデルIDである `{provider}/{model}`。これは `POST /v2/models/{provider}/{model}` でモデルを指定する際に使う値そのものなので、呼び出し側は他の情報から再導出することなく、この値をパスにそのまま埋め込むことができます。`pattern` は `RouterProviderSegment` と `RouterModelSegment` を単一の `/` で結合したもので、`maxLength` はそれらの合計にその区切り文字を加えた値です。 |
| `provider` | [`RouterProviderSegment`](#routerprovidersegment) | はい | 英数字のスラッグ（例: `anthropic`）、最大64文字 | 正規の `{provider}/{model}` モデルIDの小文字の `provider` セグメント。モデルを指定する対象のパートナーを表します。呼び出しルートの `provider` パスパラメータとカタログエントリの `provider` フィールドはどちらもこの1つのスキーマを参照しており、これにより一覧に載るIDと受け付けるIDが乖離しないようになっています。 |
| `model` | [`RouterModelSegment`](#routermodelsegment) | はい | 英数字のスラッグ（例: `claude-opus-4-6`）、最大128文字 | 正規の `{provider}/{model}` モデルIDの小文字の `model` セグメント。そのプロバイダー内で実行するモデルを表します。呼び出しルートの `model` パスパラメータとカタログエントリの `model` フィールドで共有されており、`RouterProviderSegment` と同じく乖離を防ぐためのものです。 |
| `billing` | [`RouterModelBilling`](#routermodelbilling) | はい | - | 呼び出しの前に呼び出し側が必要とする、モデルごとの課金に関する事実であり、価格ではありません。使用量やコストの数値はここには決して現れません。 |
### RouterModelListResponse
Router モデルカタログの 1 ページです。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ------------- | --------------------------------------------------- | --- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | [`RouterModelListEntry`](#routermodellistentry) の配列 | はい | - | このページのモデルで、最大 `limit` 件です。 |
| `has_more` | ブール | はい | - | このページより先に別のページが存在するかどうか。これが true の間はページを進め続けてください。`data` が短い、または空であることからカタログの終端を推測しないでください。 |
| `next_cursor` | [`RouterPageCursor`](#routerpagecursor) | いいえ | `next_cursor` として返される不透明なカーソル、1～512 文字 | Router リストへの OPAQUE なカーソル。サーバーによって生成され、そのまま往復されるだけです。オフセットではなく、モデル ID でもなく、順序付けもされておらず、カタログの再構築をまたいで安定もしません。したがって、これを解析したり、インクリメントしたり、取得元の走査を超えて永続化したりすることは、いずれも契約の範囲外です。オフセットではなくカーソルである理由は、カタログが変化するリストだからです。走査の途中でエントリが追加または削除されると、オフセットによる走査はエントリを黙ってスキップしたり繰り返したりしますが、呼び出し側はそれが起きたことを判別できません。 |
| `limit` | 整数 | はい | 1～100 | 実際に提供されたページサイズ。最大値を超える `limit` を要求した場合、拒否されるのではなく最大値に CLAMP されるため、要求した値より小さくなることがあります。ページネーションには送信した値ではなくこの数値を使用してください。そうしないと、受け取っていない行を前提にしてしまいます。 |
### RouterModelOutput
モデルの結果オブジェクトです。正確な形状については、選択済みモデルの出力スキーマを参照してください。
型: `object`
### RouterModelSegment
`{provider}/{model}` モデル ID のモデル部分です。
型: `string`。英数字のスラッグ（例: `claude-opus-4-6`）、最大 128 文字
### RouterPageCursor
不透明なカタログカーソルです。変更を加えずにそのまま `cursor` として渡し直してください。
型: `string`。`next_cursor` として返される不透明なカーソルで、1～512文字です。
### RouterProviderSegment
`{provider}/{model}` というモデル ID のプロバイダー部分です。
型: `string`。英数字のスラッグ（例: `anthropic`）、最大 64 文字
### RouterQueueCancelResponse
このルートが解決したリクエストを表す2つのステータス、すなわち `202` と `400` に対するキャンセル要求への応答です。成功用のエンベロープとエラー用のエンベロープに分けるのではなく、両ステータスで単一のボディ形状をとります。どちらも「キャンセルで何が見つかったか」という同じ内容を伝えるものであり、ステータスコードごとに異なる型をパースしなければならないクライアントにとって、分割による利点は何もないからです。
| Field | Type | Required | Constraints | Description |
| ------------ | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `request_id` | [`RouterQueueRequestId`](#routerqueuerequestid) | 必須 | `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 最大36文字 | キューに入った1件の Router リクエストの識別子。呼び出し側がポーリング、キャンセル、結果取得に使うハンドルです。 |
| `status` | [`RouterQueueCancelStatus`](#routerqueuecancelstatus) | 必須 | - | キャンセル要求で何が見つかったかを示します。このルートが実際に解決したリクエストを表す2つの結果に対応します。どちらも HTTP ステータスに反映されるため、クライアントはどちらで分岐してもかまいません。 |
### RouterQueueCancelStatus
このルートが実際に解決したリクエストを表す2つの結果について、キャンセル要求が見つけた内容です。どちらも HTTP ステータスに反映されるため、クライアントはどちらで分岐してもかまいません。
型: `文字列`
### RouterQueuePosition
レスポンスが構成された時点で、このリクエストより前にキュー内にあるリクエストの数。0 はこのリクエストが先頭であることを意味します。
型: `integer` -- 0 以上
### RouterQueueRequestId
キュー中の Router リクエスト 1 件の識別子。呼び出し元がポーリングやキャンセル、結果の取得に用いるハンドルです。
型: `string`、`pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`、uuid、最大 36 文字
### RouterQueueStatus
キュー中の Router リクエストの状態。値はちょうど 3 つで、`RouterErrorType` とは異なり、これは閉じた `enum` です。2 つのスキーマは意図的に逆方向に閉じられているためです。`RouterErrorType` は失敗を分類するもので、その集合は増えていくことが想定されているため、認識できないバケットをハード拒否する生成済みクライアントは、すでに何かが失敗したまさにその時に最も激しく失敗することになります。一方これはライフサイクルであり、後で 4 つ目の状態が追加されたライフサイクルは、enum として宣言されているかどうかに関わらず、それに対して書かれたすべてのポーリングループにとって破壊的変更となります。そのため enum として宣言され、その制約はクライアントが見られる場所に明記されています。
Type: `string`
### RouterQueueStatusFields
`RouterQueueStatusResponse` のうち URL ブロックではない半分です。キュー中のリクエスト 1 件の識別情報、その現在の状態、そしてその状態がターミナルで実行が成功しなかった場合は、その理由を示す粗い分類を表します。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ---------------- | ----------------------------------------------- | --- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request_id` | [`RouterQueueRequestId`](#routerqueuerequestid) | はい | `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 最大 36 文字 | キュー中の Router リクエスト 1 件の識別子。呼び出し側がポーリング、キャンセル、結果の取得を行うためのハンドルです。 |
| `status` | [`RouterQueueStatus`](#routerqueuestatus) | はい | - | キュー中の Router リクエストの状態。値はちょうど 3 つで、`RouterErrorType` とは異なり、これは閉じた `enum` です。これは 2 つのスキーマが意図的に逆方向に閉じられているためです。`RouterErrorType` は失敗を分類するものであり、その集合は増えていくことが想定されているため、認識されない分類をハード拒否する生成済みクライアントは、すでに何かが失敗したまさにそのときに最も大きく失敗することになります。こちらはライフサイクルであり、後で 4 番目の状態が追加されるライフサイクルは、enum として宣言されているかどうかに関わらず、それに対して書かれたすべてのポーリングループにとって破壊的変更となります。そのため enum として宣言され、その制約はクライアントが見える場所に明記されています。 |
| `queue_position` | [`RouterQueuePosition`](#routerqueueposition) | いいえ | 0 以上 | レスポンスが構成された時点で、キュー内でこのリクエストより前に並んでいるリクエストの数。ゼロはこのリクエストが先頭であることを意味します。 |
| `error_type` | [`RouterErrorType`](#routererrortype) | いいえ | - | 成功しなかった `COMPLETED` リクエストにのみ存在し、その失敗を返すときに結果の読み取りが `X-Comfy-Error-Type` に設定するのと同じ粗い分類を持ちます。これは、成功したターミナルリクエストと、失敗またはキャンセル済みのリクエストを区別するものです。どちらにも別個のターミナルステータスはありません。また、成功時には null ではなく存在しません（ABSENT）。そのため、その有無で分岐してください。 |
### RouterQueueStatusResponse
キュー中のリクエスト1件の現在の状態を、送信時に返されたものと同じ3つのURLと組み合わせたものです。
[`RouterQueueUrls`](#routerqueueurls)、[`RouterQueueStatusFields`](#routerqueuestatusfields) を構成要素とします。
型: `object`
### RouterQueueSubmitFields
`RouterQueueSubmitResponse` のうち URL ブロックではない半分: 新しいリクエストの識別情報と、それが受け付けられた時点での状態です。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ---------------- | ----------------------------------------------- | --- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request_id` | [`RouterQueueRequestId`](#routerqueuerequestid) | はい | `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 最大36文字 | キュー中の Router リクエスト1件の識別子。呼び出し元がポーリング、キャンセル、結果の収集に使うハンドルです。 |
| `status` | [`RouterQueueStatus`](#routerqueuestatus) | はい | - | キュー中の Router リクエストの状態。値はちょうど3つで、`RouterErrorType` とは異なりこちらは閉じた `enum` です。これは2つのスキーマが意図的に逆方向に閉じられているためです。`RouterErrorType` は失敗を分類するものであり、その集合は増えていくことが想定されているため、未知のバケットを厳格に拒否する生成済みクライアントは、すでに何かが失敗したまさにそのときに最も失敗しやすくなります。一方こちらはライフサイクルであり、後で4番目の状態が追加されたライフサイクルは、enum として宣言されているかどうかに関わらず、それに対して書かれたすべてのポーリングループにとって破壊的変更となります。そのため enum として宣言され、その制約はクライアントが見られる場所に明記されています。 |
| `queue_position` | [`RouterQueuePosition`](#routerqueueposition) | いいえ | 0以上 | レスポンスが構成された時点で、キュー内でこのリクエストより前に何件のリクエストがあるか。ゼロはこのリクエストが先頭であることを意味します。 |
### RouterQueueSubmitResponse
実行がキューに受け入れられたときに返されるハンドルです。リクエストの識別情報と状態を、そのライフサイクルの残りの部分を指す 3 つの URL と合成したものです。
[`RouterQueueUrls`](#routerqueueurls)、[`RouterQueueSubmitFields`](#routerqueuesubmitfields) を合成します。
型: `object`
### RouterQueueUrls
キュー中の1つのリクエストの残りのライフタイムに対応する3つのURLです。有効なハンドルを含むすべてのレスポンスで返されるため、クライアントが自分でキューURLを組み立てることはありません。
| フィールド | 型 | 必須 | 制約 | 説明 |
| -------------- | --- | -- | --- | ------------------------ |
| `status_url` | 文字列 | はい | URI | このリクエストのステータス読み取りの絶対URL。 |
| `response_url` | 文字列 | はい | URI | このリクエストの結果を取得する絶対URL。 |
| `cancel_url` | 文字列 | はい | URI | キャンセルを要求する絶対URL。 |
### RouterValidationErrorContext
失敗した検証ルールに関するプロバイダー提供の詳細。
型: `object`
### RouterValidationErrorDetail
1 件のフィールドレベルの検証失敗。
| フィールド | 型 | 必須 | 制約 | 説明 |
| ------- | --------------------------------------------------------------- | --- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loc` | any の配列 | はい | - | 問題のあるフィールドへのパス。最も外側のセグメントが先頭に来ます。たとえば `["body", "image_url"]`、または `["body", "images", 0]` のように、整数は配列のインデックスを表します。 |
| `msg` | 文字列 | はい | - | この単一の失敗についての人間が読める説明。 |
| `type` | 文字列 | はい | - | この失敗の具体的で機械可読な理由。プロバイダーからそのまま渡されます。これは型付き SDK の例外階層が分岐に使う値であり、レスポンスヘッダーの `error_type` はその大まかな分類にすぎません。 |
| `ctx` | [`RouterValidationErrorContext`](#routervalidationerrorcontext) | いいえ | - | 1 件の `RouterValidationErrorDetail` で違反した境界値。プロバイダーからそのまま渡されます。たとえば `greater_than` に対する `{"limit_value": 8}`、`image_too_small` に対する `{"min_width": 512}`、`file_too_large` に対する `{"max_size_bytes": 10485760}` などです。キー集合はプロバイダーとエラータイプに固有であるため、これは意図的にオープンなオブジェクトとしています。固定のフィールドリストに絞り込んだり、`msg` 文字列に畳み込んだりすると、まさに移植された統合がコンパイルは通るものの、その境界値を読んでいた分岐を黙って失うことになります。エラータイプが境界値を持たない場合は省略されます。 |
| `input` | [`RouterValidationErrorInput`](#routervalidationerrorinput) | いいえ | - | 問題のある入力値。呼び出し元が `loc` から再導出することなく、何が拒否されたかを確認できるよう、そのままエコーバックされます。任意の JSON 型（文字列、数値、ブール、配列、オブジェクト、null）であるため、このスキーマは意図的にオブジェクトに絞り込まず、型なしのままにしています。プロバイダーが入力値をエコーバックしない場合は省略されます。 |
### RouterValidationErrorInput
プロバイダーが含めた場合の、拒否された入力値です。
### RouterValidationErrorResponse
`422` 検証エラーのレスポンスボディ。そのカテゴリについては `X-Comfy-Error-Type` を参照してください。
| フィールド | 型 | 必須 | 制約 | 説明 |
| -------- | ----------------------------------------------------------------- | -- | -- | ----------------------------------------- |
| `detail` | [`RouterValidationErrorDetail`](#routervalidationerrordetail) の配列 | はい | - | リクエストで検出されたすべての検証失敗。問題のあるフィールドごとに 1 エントリ。 |