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 ビデオモデルの場合、content[].role が操作を選択します（最初のフレームの画像は画像から動画へ、参照画像またはクリップは参照から動画を選択します）。ネイティブディスパッチでは、Seedance の課金は役割ではなく content 内のメディア種別に従います。ビデオ入力が少しでもあるリクエストは動画から動画へとして課金され、そうでなければ画像があるものは画像から動画へとして、それもなければテキストから動画へとして課金されます。ただし、draft_task 項目からの最終レンダーは、それがレンダリングする Draft の操作として課金されます。テキストから動画へと画像から動画へで同じレートを請求するモデルもあります。model_provider が代替プロバイダーを選択している場合、条件付きの各操作はそのプロバイダー独自のレートで課金される場合があります。 レスポンス

​

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

モデル呼び出しを実行する前に、実行せずに価格を見積もります。 このボディをこのモデルで実行した場合のコストを、米ドルで事前に見積もって返します。価格は、実行時の請求に使われるのと同じレートカードから算出されます。これは見積もりであり、最終的な請求額ではありません。実際に支払うのは、ワークスペースの使用状況および請求記録に確定した請求額です。ボディはまずモデルの入力スキーマに対して検証されます。これはデフォルトの実行（strict_mode なし、reject_unknown_fields なし）が検証するのと同じ方法です。そのため、モデルのスキーマに適合しないボディは、実行時と同じ 422 になります。プロバイダーには何も送信されず、課金も発生しません。この回答は価格の固定ではありません。pricing_as_of の時点で有効なレートで算出され、実行は評価時点で有効なレートで請求されます。機能のロールアウト中は、このルートは 403 を返し、error_type: not_enabled となります。 パラメータ リクエストボディ application/json：RouterModelInput（必須） パートナーモデルのネイティブ JSON 入力で、このモデルに対して同期ルートが受け付けるボディと同一です。デフォルトの実行が検証するのと同じく、モデル自身の入力スキーマに対して検証され（このルートは strict_mode も reject_unknown_fields も受け付けません）、その独自のフィールド（出力数、入力画像が選択する操作）が、何の価格を算出するかを決めます。 レスポンス

​

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の最初のフレーム画像は画像から動画へを選択し、参照画像またはクリップは参照から動画を選択します）。ネイティブディスパッチでは、Seedanceリクエストはロールではなく content 内のメディア種別で課金されます。つまり、ビデオ入力があれば動画から動画へとして課金され、そうでなければ画像があれば画像から動画へ、それもなければテキストから動画へとして課金されます。ただし、draft_task アイテムからの最終レンダーは、それがレンダーするDraftの操作として課金されます。一部のモデルはテキストから動画へと画像から動画へに同じレートを課金します。model_provider で代替プロバイダーを選択している場合、条件付きの各操作はそのプロバイダー独自のレートで課金される場合があります。同じプロバイダー選択の契約がディスパッチ時にも適用されます。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 つの配信モードは同じ結果形状を生成するため、呼び出し側は別のパーサーを用意することなく両者を切り替えられます。 パラメータ レスポンス

​

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 自身によって発生します。

​

レスポンスヘッダー

​

事前のコスト見積もり

POST /v2/models/{provider}/{model}/estimate は、リクエストボディを実行せずにその価格を見積もります。また、キュー中の送信 (POST /v2/models/{provider}/{model}/requests) は、その 201 で estimate と同じ RouterCostEstimate を返します。どちらも、Comfy がその実行の請求に用いるレートカードから価格が決まります。どちらが返す数値も見積もりであり、最終的な請求額ではありません。ワークスペースの利用状況および請求記録にある確定額が最終です。自分のプロバイダーキーでの実行は Comfy から課金されません（後述）。見積もりの展開中は、このルートは error_type: not_enabled を伴う 403 を返し、送信レスポンスは estimate を省略します。カタログには依然として価格が含まれていません。 金額を確認する前に source を読んでください。数値が不足していても、決して無料という意味ではありません。 unknown の見積もりの reason は次のいずれかです。

• not_quotable: Router はこの呼び出しが実行される前に価格を算出できません。プロバイダーが後から報告する数量で課金され、ボディがその範囲を定めていないか、送信されたままの内容では価格を算出できないためです。認識できない reason はすべて not_quotable として扱ってください。
• unpriced_model: レートカードがこのリクエストの価格を定めていません。
• byok（キュー中の送信のみ）: 実行が自分のプロバイダーキーを使用するため、Comfy はその実行に対して何も課金しません。
• pricing_unavailable（キュー中の送信のみ）: リクエストを受け付けた時点でレートカードを読み取れませんでした。送信はそれでも受け入れられ、実行は通常どおり課金されます。

Router が実行前にまだ価格を算出できないモデルは、事前見積もりのないモデル に一覧されています。そこに一覧されていないモデルでも、特定のボディに対しては unknown を返すことがあるため、すべての見積もりで source を読んでください。 見積もりがフェイルクローズするのは、次の場合です。

• 数値を出すためにレートカードが必要で、カードが読み込まれていないか古い場合、/estimate は推測ではなく 503 を返します。キュー中の送信が見積もりを理由に拒否されることはありません。代わりに reason: pricing_unavailable を伴う source: unknown を返します。実行前にまったく価格を算出できない呼び出し（not_quotable）、または自分のプロバイダーキーでのキュー中の送信（byok）は、カードを読まずに応答されるため、その 200 はカードが新しいかどうかについて何も示しません。
• /estimate は、デフォルトの実行と同様に、モデル自身の入力スキーマに対してボディを検証します。そのため、モデルのスキーマに適合しないボディには、実行が返すのと同じ 422 が、同じ detail[] の形状で返ります。価格の算出もディスパッチも行われません。
• キュー中の送信の冪等な再生（Idempotent-Replayed: true）は estimate を省略します。元の見積もりは保存されないためです。

見積もりの限界。200 の数値は、その実行が受け入れられることや、まさにその額が課金されることを約束するものではありません。

• /estimate は strict_mode や reject_unknown_fields を受け取らないため、モデルのネイティブな契約のみを検証します。strict_mode=true の実行が代替プロバイダー自身のスキーマで受け入れるボディも、ここでは 422 になることがあります。また、reject_unknown_fields=true の実行なら拒否するであろう、宣言されていないトップレベルフィールドも、ここでは価格が算出されます。
• pricing_as_of は、レートカードを取得した時刻です（カードを読まなかった場合は、見積もりに応答した時刻）。これは価格の固定ではありません。実行は、評価された時点で有効なレートで課金されます。
• /estimate が見積もるのは、model_provider が指定するレグ、またはネイティブのプロバイダーです。fallback_provider や strict_mode パラメータは受け取りません。フォールバックの再試行が別のプロバイダーに到達した同期実行は、そのプロバイダーのレートで課金され、見積もりはそのレートを示していません。実行のレスポンスにある X-Comfy-Router-Fallback-Provider が、それが発生したことを示します。キュー中の送信にはフォールバックがないため、その estimate は実行されるレグを見積もります。
• /estimate とキュー中の送信の estimate は、model_provider のレグにおける同じボディ、または兄弟オペレーションで実行されるボディに対して、わずかに異なるドキュメントの価格を算出することがあります。送信の estimate は、その実行が送るドキュメントに基づいて価格が算出されます。
• /estimate は常にプラットフォームの請求額を見積もります。自分のプロバイダーキーでの実行は Comfy から課金されませんが、/estimate はそれを検出せず、依然として数値を返します。reason: byok を返すのはキュー中の送信だけです。
• ドルは丸めていないセントから、最大 8 桁の小数で表示され、課金対象となる 1 セント未満の amount が 0 と表示されることはありません。credits は round(amount × 211, 2) で、X-Comfy-Credits-Used が請求額に適用するのと同じ換算です。そのため、非常に小さな非ゼロの価格では credits が 0 にラウンドされることがあります。それが問題になる場合は credits ではなく amount または amount_cents で予算を立ててください。このヘッダーは実行後の数値のままであり、残高は Comfy プラットフォーム上にあります。

​

結果アセット

モデルは、アセット URL、インラインバイト、またはその両方を返すことができます。以下のプロバイダーは、選択済みのアセットを Comfy ストレージにコピーし、その URL を置き換えます。この動作はモデルによって異なります。これを選択するリクエストヘッダーはありません。 これらの有効期間は、URL を開いたときではなく、URL が署名されたときに開始されます。キャッシュされた URL や再利用された URL は残り時間が短い場合があります。再利用しても有効期間は更新されません。アセットは速やかにダウンロードしてください。コピーされるのは各行に記載されたアセットのみです。byteplus/seedream-* と byteplus/seededit-* の画像は BytePlus ビデオの行には含まれません。 コピーを実行するのは、モデルのネイティブプロバイダーのみです。代替プロバイダーによって処理された実行、つまり model_provider が代替プロバイダーを指定している場合、またはネイティブ実行のフォールバック再試行が代替プロバイダーに到達した場合（X-Comfy-Router-Fallback-Provider で開示されます）は、そのプロバイダー自身の URL を返します。これらの URL はプロバイダーの有効期限に従い、コピーされません。model_provider の値 default、comfy、comfyui は代替プロバイダーを指定しないため、それらの実行はネイティブであり、上記と同様にコピーされます。フォールバック再試行がネイティブプロバイダーに戻った model_provider の実行も同様です。 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

​

RouterCostEstimate

この呼び出しにかかる費用を、ディスパッチ前に、実行の課金に用いられるのと同じレートカードから米ドルで見積もった事前見積もりです。最終的な請求額ではありません。実際に支払うのは、ワークスペースの使用量および請求記録にある確定した請求額です。実行後に報告される X-Comfy-Credits-Used は事後に丸められた数値であり、領収書ではありません。source はその数値をどこまで信頼できるかを示します。exact は amount を持ち、estimated は min_amount と max_amount を持ち amount は持ちません。unknown はどちらも持たず reason を持ちます。amount が存在しないことを無料と読み取らないでください。価格の固定ではありません。pricing_as_of を参照してください。 フィールド

​

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

​

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 つのリクエストの識別情報、その現在の状態、そしてその状態がターミナルで実行が成功しなかった場合には、その理由を示す大まかな分類です。 Fields

​

RouterQueueStatusResponse

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

​

RouterQueueSubmitFields

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

​

RouterQueueSubmitResponse

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

​

RouterQueueUrls

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

​

RouterValidationErrorContext

失敗した検証ルールについて、プロバイダーから提供される詳細情報。 型: object

​

RouterValidationErrorDetail

単一のフィールドレベルの検証失敗。 フィールド

​

RouterValidationErrorInput

拒否された入力値です。プロバイダーがこれを含める場合に含まれます。

​

RouterValidationErrorResponse

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