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 は無意味で、何も変わりません）。model_provider が代替プロバイダーを選択し、strict_mode=false（デフォルト）の場合、ボディは送信前にそのプロバイダーの実際のスキーマに変換されます。正確に表現できないネイティブフィールドは破棄され、レスポンスの X-Comfy-Router-Dropped-Params ヘッダーで開示されます。決して暗黙には行われません。model_provider が代替プロバイダーを選択し、strict_mode=true の場合、変換は実行されません。ボディは、このモデルのネイティブなものではなく、すでにその代替プロバイダー自身の実際のスキーマでなければならず（strict_mode を参照）、変更されずに転送されます。ボディ自身のフィールドは、複数の操作をサポートするモデルで Router がどの操作を実行するかも選択します。編集可能な画像モデルの場合、入力画像を含めるとテキストから画像へから画像から画像へ（編集）操作に切り替わります。Seedance ビデオモデルの場合、先頭フレームの画像は画像から動画へを選択し、参照画像またはクリップは参照から動画を選択します。条件付きの各操作は、基本のテキストから画像へやテキストから動画へのレートではなく、独自のレートで計量されます。 レスポンス

​

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 入力です。このモデルに対して同期ルートが受け付けるボディと同一であり、操作を選択し、同じ方法で課金されます。ボディ自身のフィールドが、複数の操作をサポートするモデルで Router が実行する操作を選択し（入力画像は編集可能な画像モデルを画像から画像へ切り替え、Seedance の先頭フレーム画像は画像から動画へ、参照画像またはクリップは参照から動画を選択します）、条件付けされた各操作は、ベースのテキストから画像へやテキストから動画へのレートではなく、それぞれ独自のレートで課金されます。ディスパッチ時にも同じプロバイダー選択の契約が適用されます。model_provider がない場合、または model_provider があり strict_mode=false（デフォルト）の場合、ボディはモデルのネイティブドキュメントであり、実行が受理される前にモデル自身の入力スキーマに対して検証されるため、モデルが拒否するボディは、数分後に失敗するキュー中のリクエストではなく、ここで 422 になります。非 strict の代替プロバイダーのボディは、さらにディスパッチ時にそのプロバイダーの実際のスキーマへ変換されます。strict_mode=true の場合、ボディはすでに代替プロバイダー自身のスキーマでなければならず、変更されずに転送されます。ネイティブスキーマの検証は、同期ルートとまったく同じようにスキップされます（model_provider と strict_mode を参照）。 レスポンス

​

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

送信した 1 件のリクエストの結果を収集します。 収集エンドポイントです。正常に完了したリクエストに対しては、パートナーモデル自身のネイティブ出力を返します。これは同じモデルと同じ入力に対して同期ルートの 200 が返す内容とバイト単位で同一です。つまり、2 つの配信モードは 1 つの結果形状を生成し、呼び出し元は 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 から読み取ります。この呼び出しには APIキーが必要です。スキーマが作成されているすべてのモデルについて、同じドキュメントが APIキーなしでこのサイトの /router-schemas/{provider}/{model}.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。 型: string。モデル 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 として宣言され、その制約はクライアントが見られる場所に明記されています。 型: 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 を参照してください。 フィールド