メインコンテンツへスキップ
Router はパートナーモデルを、1回の同期 HTTP 呼び出し、または送信して後で結果を取得するキュー中のリクエストを通じて実行します。アプリケーションが完了した結果を待つことができ、あるいは後で結果を取得でき、さらにモデル自身の入力フィールドと出力フィールドを処理できる場合に使用します。

Router がサポートするもの

キューによる送信

同期ルートは、モデルの実行中も接続を開いたまま保持します。非同期プロバイダーの場合、Router はジョブを送信し、内部的にポーリングします。代替となるのはキューによる配信(送信し、request_id を取得し、ポーリングし、収集する)です。詳しくはキュー配信を参照してください。これは認証情報の背後にあるワークスペースにスコープされるため、Comfy ワークスペースで作成したキーが必要です。ワークスペースを持たないレガシーキー、bring-your-own-key リクエスト、またはキューで実行できないモデルは、送信ルートで not_enabled とともに 403 を返します。どちらのモードもコールバックや Webhook は提供しません。 リクエストを十分な時間開いたままにできない場合は、キューに投入してください。プロバイダー自身の送信とポーリングの制御が必要な場合は、パートナープロキシを使用してください。 現在、4 つのモデルが同期専用であり、キューに送信すると 403 / not_enabled で拒否されます。elevenlabs/eleven_sfx_v2、elevenlabs/eleven_v3、elevenlabs/eleven_v4、elevenlabs/eleven_v4_turbo です。これらは JSON の結果ドキュメントではなく生のオーディオバイト列を返すため、キューによる配信にはそれを保存する場所がありません。同期ルートで実行してください。同期ルートはこれらのバイト列を通常どおり返します。 4 つのモデルはキュー専用であり、同期ルートでは 403 / not_enabled で拒否されます。ltx/ltx-video-alpha-gen、ltx/ltx-video-to-video-hdr、ltx/ltx-video-to-video-reframe、ltx/ltx-video-upscale です。これらのジョブは、同期呼び出しが保持される時間を超えて実行されることがあります。同じボディを POST /v2/models/ltx/{model}/requests に送信し、結果をキューから収集してください。 LTX v1 のテキストから動画へ、および画像から動画への操作も同じ理由で生のビデオバイト列を返すため、キューによる配信ではそれらを保存できません。ただし、これらに到達できるのは /proxy/ltx/v1/… のパートナープロキシ経由のみであり、Router のモデル id からは到達できません。すべての ltx/* カタログモデルは、キューに投入可能な v2 の送信とポーリングの操作に解決されるためです。

サーバーのデッドラインで呼び出しが打ち切られます

Router のデフォルトのデッドラインは 10 分で、デプロイメントごとに設定できます。この時間はリクエストが到着した時点からカウントされるため、リクエストのアップロードもその範囲に含まれます。それまでにボディが完全に到着しなかった場合は、プロバイダーへの呼び出しが行われる前に 504 / deadline_exceeded が返され、完了するのに残り時間が足りない呼び出しも同様に拒否されます。Router が先にエラーとリクエスト ID を返せるよう、クライアントのタイムアウトをデッドラインより長く設定してください。 504 / deadline_exceeded は Router が待機を停止したことを意味し、504 / provider_timeout はプロバイダーがタイムアウトしたことを意味します。タイムアウトや接続の喪失は、生成が課金されなかったことを証明するものではなく、受け入れ済みのプロバイダー側の処理をキャンセルするものでもありません。再試行する前にタイムアウトと収集をお読みください。

リカバリはプロバイダーに依存する

Router は、プロバイダーが送信を承認するとすぐに、送信とポーリング形式の生成に対するプロバイダーハンドルを保持します。その後で接続が失われた場合、同じ Idempotency-Key と同じボディで再送すると、2 つ目の生成を開始する代わりに元の生成を回収し、再度課金されることはありません。これは Router が呼び出しを終了した場合(その期限、またはクライアントが切断した場合)に当てはまり、またほとんどすべてのケースで、呼び出しを処理している Router サーバーが呼び出し途中で再起動した場合にも当てはまります。例外は、プロバイダーが送信を承認してから Router がそれを記録するまでの短い間の再起動です。その場合キーは最大 15 分間保持され、その後再送すると新しい生成が開始され、課金されます。再起動後、Router が元のハンドラーが存在しないことを確認するまで最大約 1 分間、再送すると Retry-After 付きで 409 / concurrency_limit_exceeded が返されることがあります。同じキーで再送し続ければ、結果を回収できます。完了した再生可能なレスポンスも、キーの記録から取得できます。 切断されたすべての呼び出しがリカバリできるわけではありません。送信する前にリクエストとキーを保存しておき、リトライ結果テーブルを使用してください。新しいキーは新しい呼び出しを作成し、別途課金が発生する可能性があります。

リクエストボディの上限

Router は、ボディが 100 MiB (104,857,600 bytes) を超えるリクエストを拒否します。この上限は送信する生のバイト数に対して適用され、Router があらゆる解析を行う前に測定されるため、すべてのルート、および同期配信とキュー配信の両方に適用されます。 インラインのメディアが、呼び出し元がこの上限に直面する場面です。Base64 エンコードはバイナリデータを約 4/3 に膨らませるため、エンコードされたメディアを含むボディは、実際の画像・オーディオ・ビデオのバイト数がおよそ 75 MB で上限に達します。ディスク上のファイルではなく、エンコード後の文字列のサイズを見積もってください。また、1 回の呼び出しに含まれるすべての入力を数えてください。参照画像を 2 枚含むリクエストは両方にこの許容量を消費し、プロンプト、パラメータ、JSON 構造も同様にカウントされます。 拒否される場合の挙動。 413 で、他のレスポンスと同様に X-Comfy-Error-Type に invalid_input が設定され、X-Comfy-Request-Id も設定されます。ボディは RouterErrorResponse で、その detail に超過した上限が記述されます。detail を解析するのではなく error_type で分岐し、このページと API の返す内容が食い違う場合は API の返す内容を正としてください。Router は何かをディスパッチする前に拒否を発生させるため、生成は実行されておらず、課金もされていません。 この上限は、Idempotency-Key を伴うかどうかに関係なく、すべてのリクエストに適用されます。これは冪等性の制限ではなく、同じキーを再送しても結果は変わりません。大きすぎるボディは何度試しても大きすぎるのです。 プロバイダーが独自の、より低い制限を課すことがあり、この上限では通常そうなります。 プロバイダーはインラインのメディアについて独自の上限を公開しており、より小さいほうが拘束条件となります。たとえば Google のモデルは、インラインペイロードとして最大 20 MB (10 進数で 20,000,000 bytes) を受け付けます。Google のモデルページにある Size limit: 20MB の行は、Google 自身の仕様から引用したフィールド単位の Google の上限であり、リクエストボディ全体に対する Router の上限ではありません。Router の上限は、それが前面に立つすべてのパートナーの上限より意図的に高く設定されているため、単一のインラインアセットについては通常プロバイダー自身の制限に先に達します。Router の上限が効いてくるのは、1 つのボディに複数のアセットが含まれる場合です。Router の上限は超えないもののプロバイダー自身の制限を超えるボディは、Router ではなくプロバイダーによって拒否され、413 ではなくプロバイダーのエラーとして返されます。

リクエストは呼び出し元ごとにレート制限される

リクエストレートの制限は、すべての Router 操作に適用されます。呼び出し、カタログとスキーマの読み取り、コスト見積もり、そしてキュー中の送信・ステータス・結果・キャンセルの各呼び出しが対象で、生成前に拒否されたリクエストも含まれます。この制限はソース IP ではなく、認証された呼び出し元に従います。呼び出し元のプロバイダーキーを使用した呼び出しは対象外ですが、プロバイダーの制限は引き続き適用されます。キュー中のリクエストをポーリングすると、他の呼び出しと同じ割り当てを消費するため、タイトループで回すのではなく、ステータス読み取りが示す間隔でポーリングしてください。rate_limited による拒否はキュー中のリクエストに何の変化ももたらしません。リクエストは実行を続け、拒否されたキャンセルは何もキャンセルしていないので、Retry-After の後に再度送信してください。 カタログとスキーマの読み取りはキャッシュしてください。ETag と If-None-Match で再検証してください。再試行とコミット済み支出のフィールドについてはヘッダーを参照してください。

呼び出しの実行中は進捗が表示されない

Router は最終レスポンスのみを返し、ストリーミングされるトークン、サーバー送信イベント、パーセンテージの更新、中間プレビューフレームはありません。プロバイダーの内部ポーリング状態は、リクエスト中に転送されません。 不確定な進捗インジケーターを表示してください。進捗やストリーミングが必要な場合は、それを公開しているパートナープロキシ操作を使用してください。

Comfy の課金と使用量

レスポンスにはプロバイダーの使用量またはコストのフィールドが含まれる場合があります。これらは Comfy の一律の課金を表すものではありません。X-Comfy-Credits-Used はオプションです。ヘッダーが不足している場合は、コストが報告されなかったことを意味し、実行が無料だったことを意味するものではありません。リプレイされたレスポンス(Idempotent-Replayed: true)に対して再度課金されることはありませんが、オリジナルの実行の金額が再掲される場合があるため、1 つの Idempotency-Key のリトライをまたいでこのヘッダーを合算しないでください。残高、使用量、請求書については Comfy プラットフォームを使用してください。 カタログは billing.charges_on_policy_rejection を含む請求に関する事実を提供しますが、価格は提供しません。yes、no、unknown を明示的に処理してください。yes の場合、同期の content_policy_violation エラーに X-Comfy-Credits-Used が付くことがあります。プロバイダーがモデルの生成済み出力を拒否し、Comfy がその拒否された生成に対して使用量を記録したときに付き、その金額が示されます。入力側の拒否、同一キーのリプレイ、およびヘッダーの小数 2 桁では表示できないほど少額の課金には付きません。ヘッダーのない拒否は報告されていないだけであり、無料ではありません。詳細は billing を参照してください。 実行前に価格を確認するには、POST /v2/models/{provider}/{model}/estimate を呼び出すか、キュー中の送信の 201 にある estimate オブジェクトを読み取ってください。デプロイメントで見積もりが無効化されている場合、このルートは error_type: not_enabled とともに 403 を返し、送信には estimate が含まれません。それぞれの価格は Comfy の標準定価で算出され(ベンダーが報告するコストで課金されるモデルは、代わりにベンダーの公開価格表から価格が決まります。その価格表が金額を完全に決定する場合、オプトインした少数のモデルでは exact、それ以外では estimated となり、価格表で完全に決定できるはずの一部の見積もりも estimated に含まれます)、契約や顧客固有のレートは反映されません。交渉された価格設定を持つワークスペースには定価が提示され、契約レートが請求されます。その金額は見積もりであり最終的な請求額ではなく、ワークスペースの使用量と請求の記録にある確定した請求額が最終となります。また、価格を固定するものでもありません。独自のプロバイダーキーでの実行は、/estimate がその実行の金額を返したとしても Comfy からは請求されません。また、unknown の見積もりには金額が含まれておらず、それは無料を意味するものではありません。X-Comfy-Credits-Used は、実行に対する事後的な丸められた数値のままですが、領収書ではありません。exact、estimated、unknown の読み取り方については、実行前のコスト見積もり を参照してください。実行前に価格を算出できないモデルは、事前見積もりのないモデル に一覧されています。

事前見積もりのないモデル

Router は、以下のモデルへの呼び出しを実行前に確実に価格算出することがまだできません。そのため、これらのモデルについては /estimate およびキュー中の送信の estimate が source: unknown を返します。ただし、特定のリクエストボディに対して数値を返す場合もあります。unknown は数値が提示されなかったことを意味し、実行が無料であることを意味するものではありません。Comfy の課金と使用量 のルールは引き続き適用されます。自身のプロバイダーキーでの実行は Comfy から課金されず、X-Comfy-Credits-Used は任意であるため、ヘッダーが不足している場合はコストが報告されなかったことを意味します。ここに記載されていないモデルでも、特定のリクエストボディに対して unknown を返すことがあるため、すべての見積もりで source を確認してください。 このリストは見積もりカバレッジの拡大に伴い縮小していきます。これは Router 自身の価格算出コードから生成されており、公開されていないモデルは決して掲載されません。
  • bfl: bfl/erase-v1, bfl/video-edit-v1, bfl/video-upscale-v1, bfl/vto-v1
  • fal: fal/fal-seedance-2.0, fal/fal-seedance-2.5
  • freepik: freepik/ai-image-upscaler-precision-v2, freepik/ai-skin-enhancer-creative, freepik/ai-skin-enhancer-faithful, freepik/ai-skin-enhancer-flexible
  • heygen: heygen/starfish
  • ideogram: ideogram/ideogram-v3, ideogram/ideogram-v4
  • kelly: kelly/kelly-seedance-2.0, kelly/kelly-seedance-2.0-fast, kelly/kelly-seedance-2.5
  • kling: kling/kling-4.0, kling/kling-image-o1, kling/videos-avatar-image2video, kling/videos-lip-sync
  • ltx: ltx/ltx-video-alpha-gen, ltx/ltx-video-to-video-hdr, ltx/ltx-video-to-video-reframe, ltx/ltx-video-upscale
  • luma: luma/photon-1, luma/photon-flash-1
  • minimax: minimax/minimax-gpt-image-2, minimax/minimax-gpt-image-2.5-flare, minimax/minimax-gpt-image-2.5-sunburst, minimax/minimax-gpt-image-2.6-flare, minimax/minimax-gpt-image-2.6-sunburst, minimax/minimax-h3-image, minimax/minimax-h3-image-highspeed
  • moonvalley: moonvalley/image-to-video, moonvalley/text-to-video, moonvalley/video-to-video
  • openai: openai/gpt-image-1.5
  • openrouter: openrouter/chat-completions
  • pika: pika/pika-gpt-image-2, pika/pika-nano-banana-2, pika/pika-nano-banana-pro
  • pixverse: pixverse/v3.5, pixverse/v6, pixverse/v6-max
  • quiver: quiver/arrow-2, quiver/arrow-2-telos
  • runware: runware/runware-gpt-image-2, runware/runware-gpt-image-2.5-flare, runware/runware-gpt-image-2.5-sunburst, runware/runware-nano-banana-2, runware/runware-nano-banana-pro, runware/runware-seedance-2.0, runware/runware-seedance-2.5
  • synclabs: synclabs/sync-3
  • veed: veed/video-background-removal, veed/video-background-removal-fast, veed/video-background-removal-green-screen
  • wavespeed: wavespeed/wavespeed-gpt-image-2, wavespeed/wavespeed-gpt-image-2.5-flare, wavespeed/wavespeed-gpt-image-2.5-sunburst
openai/gpt-image-2、openai/gpt-image-2.5-flare、openai/gpt-image-2.5-sunburst、openai/gpt-image-2.6-flare、openai/gpt-image-2.6-sunburst での編集にも事前見積もりはありません。これらのモデルへの編集呼び出し、または入力画像を伴う生成呼び出しは source: unknown を返します。これらのモデルへのテキストのみの生成呼び出しは見積もりされるため、上記のリストには含まれていません。

Router はすべてのパートナー操作をカバーするわけではない

Router はモデルを実行します。ファイルのアップロード、アカウントの読み取り、アセット管理、ストリーミング、プロバイダーのジョブ制御には、/proxy/… 配下のパートナープロキシルートが必要になる場合があり、これらは Router の外側にあり、そのコントラクトでは説明されていません。Router 自身のサーフェスは Comfy Router 仕様です。サポートはプロバイダーによって異なります。

Krea 3 の参照画像: 先にアップロードするか、公開 https URL を使用する

krea/krea-3 の image_urls では、POST /proxy/krea/assets が返す image_url(https://app-uploads.krea.ai/... の URL)は常に受け付けられます。他のリンクが受け付けられるかどうかは環境によって異なります。api.comfy.org では現在受け付けられます。8 件を超えるエントリは、リクエストのスキーマチェックにより、フェッチが行われる前に 422 で拒否されます。
  • 他のリンクが受け付けられる場合、公開された任意の https 画像 URL が使用できます。Router はモデルを実行する前に、各参照を自身でフェッチしてサイズを読み取ります。修正が必要な参照は、そのホスト名を示す 400 invalid_input で拒否されます。対象は、存在しないホストまたは公開到達できないホスト、408 または 429 以外の 4xx を返すオリジン、リダイレクトが多すぎる場合、https でないリンクまたは公開到達できないホストへのリダイレクト、サポートされていない画像であるコンテンツ、画像のサイズヘッダーの前に終了してしまう長さのないレスポンス、サイズヘッダーが最初の 2 MiB 以内にない画像(下記参照)です。それ以外のフェッチ失敗は代わりに 5xx エラーになります(Router では 500 internal_error)。これらの一部は自然に解消されます(DNS リゾルバーのエラー、タイムアウト、切断された接続、5xx、408、429 を返すオリジン、または Router のホストチェックと接続の間に DNS 応答が非公開アドレスに切り替わるホストで、再試行時には成功するか非公開ホストに対する 400 で拒否される場合があります)。そのため、後で再試行してください。その他のものは毎回同じように失敗します。たとえば、フェッチが信頼しない TLS 証明書(自己署名、期限切れ、または誤ったホスト名に対するもの)、または 200 以外の 2xx やフェッチがフォローしない 3xx(204、206、300、304、305、または Location のない 301、302、303、307、308 など)を返すオリジンです。再試行が同じように失敗する場合は、まず画像をアップロードしてください。POST /v2/models/krea/krea-3/requests でキューに入れられたリクエストは、そのリンクのいずれかが app-uploads.krea.ai のリンクでない場合、そのような 5xx では再試行されないため、原因が解消し得るならご自身で再送信してください。実際のアップロードではない app-uploads.krea.ai のリンクは、他の到達不能な参照と同様に 400 で拒否されます。キューに入れられたリクエストの 400 は汎用的な invalid_input の詳細のみを含むため、ホスト名を示しません。また、キューはそれを再試行しません。キューに入れられた 400 は image_urls だけでなく任意のフィールド(たとえばサポートされていない resolution や thinking_mode)に起因する可能性があるため、まず他のフィールドを確認してください。それらが有効であれば、各画像を POST /proxy/krea/assets でアップロードし、それらの image_url 値と新しい Idempotency-Key(またはなし)で再送信してください。変更されたボディでキーを再利用すると 409 invalid_input で拒否されますが、これは画像について何も示しません。同じボディで再利用すると、元の request_id と Idempotent-Replayed: true を伴う 201 で応答されるため、新しい実行は開始されず、その結果 URL(GET /v2/models/krea/krea-3/requests/{request_id})は同じ 400 を返します(そのステータス URL は error_type invalid_input を伴う 200 で応答します)。その再送信も 400 で失敗する場合、問題は画像自体にあります(たとえば、サポートされていない画像である、またはそのサイズヘッダーが最初の 2 MiB 以内にない)。
  • 他のリンクが受け付けられない場合、すべてのエントリはアップロードが返した image_url でなければなりません。Router は、そのリンクがホストが正確に app-uploads.krea.ai である https URL としてパースできることのみをチェックします(他のホストや明示的なポートは不可)。他のリンク、たとえばご自身でホストする公開 https URL は、モデルを実行する前に「image_urls must be image_url values returned by POST /proxy/krea/assets」と述べる 400 invalid_input で拒否されるため、代わりに画像をアップロードしてください。そのチェックを通過しても実際のアップロードではないリンク(期限切れ、削除済み、または誤記)は依然として通過し、Router は画像のサイズを読み取れずに 5xx エラーで応答します(400 ではありません)。Router が読み取れないアップロード済みの画像(たとえば、サポートされていない画像である、またはそのサイズヘッダーが最初の 2 MiB 以内にない)も、ここでは 400 ではなく 5xx(Router では 500 internal_error)で失敗し、問題は依然として画像にあるため、再度アップロードしても役に立ちません。
  • サーバーの起動直後、どのルールが適用されるかを学習する前は、app-uploads.krea.ai のリンクでない任意の https URL が 503(Router では service_unavailable)で失敗する可能性があり、これは再試行しても安全です(キューに入れられたリクエストは自動的に再試行されます)。
Router は各参照のサイズを見つけるために最初の 2 MiB のみを読み取るため、そのウィンドウ内でサイズ情報を読み取り完了できない画像(たとえば、2 MiB を超える埋め込みメタデータを含む JPEG、または透過データ、それがなければ最初の画像データチャンクの先頭が 2 MiB を超えた位置にあるパレット PNG。たとえば 2 MiB を超えるテキストやカラープロファイルチャンクの後など)は、サイズヘッダーが最初の 2 MiB 以内にないと述べる 400 で拒否され、アップロードしても役に立ちません。まず大きなメタデータを含めずに再保存するか、パレット PNG を非パレット(トゥルーカラー)PNG として保存してください。国際化されたホスト名は ASCII(punycode)形式で送信してください。たとえば bücher.de ではなく xn--bcher-kva.de です。Router は記述されたとおりにホストを検索し、非 ASCII の名前は存在しないホストとして拒否されます。 アップロードはすべての環境で機能するため、移植性のある選択肢です。常にアップロードが返したとおりに image_url を渡してください。画像がまだ公開 https URL にない場合は、まずアップロードしてください:
  1. 各参照画像を multipart/form-data としてアップロードします。画像はフォームフィールド file に含めます(JPEG、PNG、または WebP、最大 75 MB)。Router と同じ方法で、X-API-Key または Authorization: Bearer を使用して認証します。
  2. JSON レスポンスから image_url を読み取り、image_urls に渡します:
テキストから画像への呼び出しでは image_urls を省略し、アップロードは不要です。

モデルの出力と保存されたアセット

入力フィールドと出力フィールドはモデルによって異なります。プロバイダー SDK やプロキシから移行すると、ルートと結果の読み取り方法の両方が変わる可能性があります。 一部のアセットは Comfy ストレージに再ホストされます。その他はプロバイダーの URL またはインラインバイトです。有効期間とリプレイ動作については、結果アセット を参照してください。

次のステップ

クイックスタート

Comfy Router を通じて最初の画像を生成します。

Router API の使用

モデルを選択し、そのスキーマを確認して、結果と再試行を処理します。