Comfy Router API リファレンス

モデル ID でアドレス指定される Comfy Router の正規ルート。 ベース URL: https://api.comfy.org 以下のすべてのエンドポイントは認証が必要です。X-API-Key: <api-key> または Authorization: Bearer <jwt> を送信してください。 Comfy API キーは Bearer トークンとして送信することもできます。両方の認証ヘッダーが指定された場合、X-API-Key が優先されます。キーと JWT の違いについては認証ヘッダーを、アクセス要件についてはクイックスタートを参照してください。

​

エンドポイント

​

GET /v2/models

Comfy Router が実行できるモデルを一覧表示します。 利用可能なモデル ID と課金情報を一覧表示します。has_more が true の間は next_cursor を使用します。 パラメータ レスポンス

​

GET /v2/models/{provider}/{model}

正規のモデル ID でパートナーモデル 1 件のカタログエントリを読み取ります。 カタログ全体を一覧表示せずに、1 つのモデルの詳細を読み取ります。 パラメータ レスポンス

​

POST /v2/models/{provider}/{model}

正規のモデル ID を指定してパートナーモデルを同期的に実行します。 モデルを実行し、完了した結果を同じレスポンスで受け取ります。 パラメータ リクエストボディ application/json: RouterModelInput（必須） パートナーモデル固有の JSON 入力。model_provider を指定しない場合、または strict_mode=true の場合は、そのままプロバイダーに転送されます。strict_mode=true の場合、ボディはすでに代替プロバイダー自身の実際のスキーマである必要があり、このモデル固有のスキーマではありません（strict_mode を参照）。model_provider で代替プロバイダーを選択し、strict_mode=false（デフォルト）の場合は、送信前にボディがそのプロバイダーの実際のスキーマへ変換されます。正確に表現できない固有のフィールドは破棄され、レスポンスの X-Comfy-Router-Dropped-Params ヘッダーで開示されます。決して黙って破棄されることはありません。 レスポンス

​

GET /v2/models/{provider}/{model}/openapi.json

1 つのパートナーモデルの入力スキーマと出力スキーマを OpenAPI ドキュメントとして読み取ります。 1 つのモデルの入力スキーマと出力スキーマを単体の OpenAPI ドキュメントとして読み取ります。 パラメータ レスポンス

​

POST /v2/models/{provider}/{model}/requests

パートナーモデルの実行をキューに送信し、即座に応答を返します。 Comfy Router のキュー配信モードです。リクエストボディは、このモデルに対して POST /v2/models/{provider}/{model} が受け付けるものと同じパートナー固有の JSON 入力です（1つのボディ形状、モデルごとに1つのスキーマ、2つの配信モード）。ただしこのルートは結果を待つ間コネクションを保持しません。実行を受け付けてハンドルとともに 201 を返し、呼び出し元は後述の3つの読み取りを通じて後で結果を取得します。 パラメータ リクエストボディ application/json — RouterModelInput（必須） パートナーモデル固有の JSON 入力で、このモデルに対して同期ルートが受け付けるボディと同一です。実行が受け付けられる前にモデル自身の入力スキーマに対して検証されるため、モデルが拒否するボディは、数分後に失敗するキュー中のリクエストではなく、ここで 422 となります。 レスポンス

​

GET /v2/models/{provider}/{model}/requests/{request_id}

送信済みリクエスト1件の結果を収集します。 収集エンドポイントです。正常に完了したリクエストに対しては、パートナーモデル自身のネイティブ出力を返します。これは同じモデルと同じ入力に対して同期ルートの 200 が返す内容とバイト単位で同一であり、2つの配信モードが同一の結果形状を生成するため、呼び出し側は2つ目のパーサーを用意することなく両者を切り替えられます。 パラメータ レスポンス

​

PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel

送信済みのリクエスト 1 件のキャンセルを要求します。 Comfy に、まだ完了していないリクエストを停止するよう要求します。これは要求であり、保証ではありません。202 はまさにそのことを示しています。CANCELLATION_REQUESTED は要求が受け入れられたことを意味し、実行が停止したことを意味するものではありません。パートナー側ですでに送信中の実行は、そのまま完了してしまう可能性があります。そして完了したパートナー生成は、誰かが結果を受け取ったかどうかに関わらず課金されます。そのため、実際に何が起きたかを知る必要がある呼び出し元は、後でステータスエンドポイントを読み取ってください。そこで有効になったキャンセルは、他のすべてのターミナルな結果と同様に、error_type を伴う COMPLETED として表されます。 パラメータ レスポンス

​

GET /v2/models/{provider}/{model}/requests/{request_id}/status

送信済みリクエスト 1 件のキュー状態を読み取ります。 ポーリング用のエンドポイントです。応答にはリクエストの現在の状態のみが含まれ、結果は含まれないため、クライアントはポーリングのたびに出力を転送することなく長時間の生成を監視できます。結果は、このエンドポイントが COMPLETED を返した時点で、後述の読み取りから一度だけ取得されます。 パラメータ レスポンス ここでの説明は簡潔です。モデルの選択、検証、再試行、課金については Comfy Router API の使用 を、ヘッダーの動作については ヘッダー を参照してください。

​

エラーバケット

Router の機械可読なエラーカテゴリで、X-Comfy-Error-Type ヘッダーでも送信されます。

​

リクエストレベルバケット

Router が受け付けたものの、完了できなかったリクエストに対して発生します。

​

トランスポートレベルバケット

モデルへの呼び出しの前またはその周辺で、Router 自身によって発生します。

​

レスポンスヘッダー

​

結果アセット

モデルは、アセット URL、インラインバイト、またはその両方を返すことができます。以下のプロバイダーは、選択済みのアセットを Comfy ストレージにコピーし、その URL を置き換えます。この動作はモデルによって異なります。これを選択するリクエストヘッダーはありません。 これらの有効期間は、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

認証、アクセス、モデル検索、クォータ、およびプロバイダー転送の失敗に対するエラーボディ。 フィールド

​

RouterErrorType

機械可読な Router エラーのカテゴリ。X-Comfy-Error-Type ヘッダーでも送信されます。 型: string

​

RouterModelBilling

モデルを呼び出す前に確認すべき課金の挙動。価格や使用量は含まれません。 フィールド

​

RouterModelDetail

1つの Comfy Router モデルに対するモデル単位の詳細です。カタログ一覧が報告するすべての内容に加えて、単一モデルルートだけが持つモデル単位のフィールドを含みます。 RouterModelListEntry、RouterModelDetailFields を組み合わせます。 型: object

​

RouterModelDetailFields

モデル詳細エンドポイントが返すオプションフィールド。 フィールド

​

RouterModelId

POST /v2/models/{provider}/{model} で使用されるモデル ID。 型: 文字列。モデル ID（例: anthropic/claude-opus-4-6）、最大 193 文字

​

RouterModelInput

モデル入力オブジェクト。フィールドと検証については、選択済みモデルの OpenAPI ドキュメントを参照してください。 型: object

​

RouterModelInputSchemaDocument

1つのモデルの入力と出力に対応するスタンドアロンの OpenAPI ドキュメント。 型: object

​

RouterModelListEntry

モデルのIDと課金に関する事実。 フィールド

​

RouterModelListResponse

Router モデルカタログの 1 ページです。 フィールド

​

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 に対するキャンセル要求への応答です。成功用のエンベロープとエラー用のエンベロープに分けるのではなく、両ステータスで単一のボディ形状をとります。どちらも「キャンセルで何が見つかったか」という同じ内容を伝えるものであり、ステータスコードごとに異なる型をパースしなければならないクライアントにとって、分割による利点は何もないからです。 フィールド

​

RouterQueueCancelStatus

このルートが実際に解決したリクエストを表す2つの結果について、キャンセル要求が見つけた内容です。どちらも HTTP ステータスに反映されるため、クライアントはどちらで分岐してもかまいません。 型: string

​

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 件の識別情報、その現在の状態、そしてその状態がターミナルで実行が成功しなかった場合は、その理由を示す粗い分類です。 フィールド

​

RouterQueueStatusResponse

キュー中のリクエスト1件の現在の状態を、送信時に返されたものと同じ3つのURLと組み合わせたものです。 RouterQueueUrls、RouterQueueStatusFields を構成要素とします。 型: object

​

RouterQueueSubmitFields

RouterQueueSubmitResponse のうち URL ブロックではない半分: 新しいリクエストの識別情報と、それが受け付けられた時点での状態です。 フィールド

​

RouterQueueSubmitResponse

実行がキューに受け入れられたときに返されるハンドルです。リクエストの識別情報と状態を、そのライフサイクルの残りの部分を指す 3 つの URL と合成したものです。 RouterQueueUrls、RouterQueueSubmitFields を合成します。 型: object

​

RouterQueueUrls

キュー中の1つのリクエストの残りのライフタイムに対応する3つのURLです。有効なハンドルを含むすべてのレスポンスで返されるため、クライアントが自分でキューURLを組み立てることはありません。 フィールド

​

RouterValidationErrorContext

失敗した検証ルールについてプロバイダーが提供する詳細。 型: object

​

RouterValidationErrorDetail

1 件のフィールドレベルの検証失敗。 フィールド

​

RouterValidationErrorInput

プロバイダーが含める場合の、拒否された入力値です。

​

RouterValidationErrorResponse

422 検証エラーのレスポンスボディ。カテゴリについては X-Comfy-Error-Type を参照してください。 フィールド