Comfy Router の機能と制限

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 の結果ドキュメントではなく生のオーディオバイト列を返すため、キューによる配信にはそれを保存する場所がありません。同期ルートで実行してください。同期ルートはこれらのバイト列を通常どおり返します。 LTX v1 のテキストから動画へ、および画像から動画への操作も同じ理由で生のビデオバイト列を返すため、キューによる配信ではそれらを保存できません。ただし、これらに到達できるのは /proxy/ltx/v1/… のパートナープロキシ経由のみであり、Router のモデル id からは到達できません。すべての ltx/* カタログモデルは、キューに投入可能な v2 の送信とポーリングの操作に解決されるためです。

​

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

Router のデフォルトのデッドラインは 10 分で、デプロイメントごとに設定できます。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 ではなくプロバイダーのエラーとして返されます。

​

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

リクエストレートの制限は、呼び出しとカタログ/スキーマの読み取りに適用され、生成前に拒否されたリクエストも含まれます。これはソース IP ではなく、認証された呼び出し元に従います。呼び出し元のプロバイダーキーを使用した呼び出しは対象外ですが、プロバイダーの制限は引き続き適用されます。 カタログとスキーマの読み取りはキャッシュしてください。カタログとスキーマの読み取りは 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 を明示的に処理してください。詳細は billing を参照してください。 実行前に価格を確認するには、POST /v2/models/{provider}/{model}/estimate を呼び出すか、キュー中の送信の 201 にある estimate オブジェクトを読み取ってください。estimate の展開中は、このルートは error_type: not_enabled とともに 403 を返し、送信には estimate が含まれません。それぞれは Comfy がその実行に対して請求するレートカードに基づいて価格が決まりますが、その金額は見積もりであり最終的な請求額ではなく、ワークスペースの使用量と請求の記録に確定した請求額が最終となります。また、価格を固定するものでもありません。独自のプロバイダーキーでの実行は、/estimate がその実行の金額を返したとしても Comfy からは請求されません。また、unknown の estimate には金額が含まれておらず、それは無料を意味するものではありません。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/flux-2-max, bfl/flux-2-pro, bfl/flux-3-image, bfl/flux-3-video, bfl/flux-kontext-max, bfl/flux-kontext-pro, bfl/flux-pro-1.0-expand, bfl/flux-pro-1.0-fill, bfl/flux-pro-1.1, bfl/flux-pro-1.1-ultra, bfl/video-edit-v1, bfl/video-upscale-v1, bfl/vto-v1
• byteplus: byteplus/seed-audio-1.0, byteplus/seed-audio-1.0-multilingual
• elevenlabs: elevenlabs/eleven_sfx_v2
• fal: fal/crystal-upscaler, fal/crystal-video-upscaler, fal/fal-gpt-image-2, fal/fal-gpt-image-2.5-flare, fal/fal-gpt-image-2.5-sunburst, fal/fal-nano-banana-2, fal/fal-nano-banana-pro, fal/fal-seedance-2.0, fal/fal-seedance-2.5, fal/flux-3-max, fal/patina
• 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, ideogram/p-image-ideogram
• kling: kling/kling-3.0-turbo, kling/kling-image-o1, kling/kling-v2-5-turbo, kling/kling-v2-6, kling/kling-v3, kling/kling-v3-omni, kling/kling-video-o1, kling/videos-avatar-image2video, kling/videos-lip-sync, kling/videos-video-extend
• luma: luma/photon-1, luma/photon-flash-1, luma/ray-2, luma/ray-flash-2
• meshy: meshy/animations, meshy/meshy-6, meshy/meshy-7, meshy/meshy-7.1, meshy/remesh, meshy/rigging
• moonvalley: moonvalley/image-to-video, moonvalley/text-to-video, moonvalley/video-to-video
• openrouter: openrouter/chat-completions
• pika: pika/pika-gpt-image-2, pika/pika-nano-banana-2, pika/pika-nano-banana-pro
• recraft: recraft/recraftv2, recraft/recraftv3, recraft/recraftv4, recraft/recraftv4_1, recraft/recraftv4_1_pro, recraft/recraftv4_1_pro_vector, recraft/recraftv4_1_utility, recraft/recraftv4_1_utility_pro, recraft/recraftv4_1_utility_pro_vector, recraft/recraftv4_1_utility_vector, recraft/recraftv4_1_vector, recraft/recraftv4_pro, recraft/recraftv4_styles, recraft/recraftv4_styles_pro, recraft/recraftv4_styles_pro_vector, recraft/recraftv4_styles_vector
• 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
• runway: runway/gen4_image
• synclabs: synclabs/sync-3
• veed: veed/clean-audio, veed/clean-audio-video, veed/fabric-1.0, veed/lipsync-2.0, veed/video-background-removal, veed/video-background-removal-fast, veed/video-background-removal-green-screen
• wavespeed: wavespeed/flashvsr, wavespeed/seedvr2, wavespeed/ultimate-image-upscaler, wavespeed/wavespeed-gpt-image-2, wavespeed/wavespeed-gpt-image-2.5-flare, wavespeed/wavespeed-gpt-image-2.5-sunburst
• xai: xai/grok-imagine-image, xai/grok-imagine-image-2.0, xai/grok-imagine-image-pro, xai/grok-imagine-image-quality, xai/grok-imagine-video, xai/grok-imagine-video-1.5, xai/grok-imagine-video-1.5-lite, xai/grok-imagine-video-1.5-preview

​

Routerはすべてのパートナー操作をカバーしていない

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

​

Krea 3の参照画像は先にアップロードする必要があります

krea/krea-3 は任意の画像リンクを受け付けません。image_urls の各エントリは、POST /proxy/krea/assets が返す image_url（https://app-uploads.krea.ai/... 形式のURL）である必要があります。Routerがチェックするのは、リンクが https URLとしてパースでき、ホストが厳密に app-uploads.krea.ai であること（他のホストや明示的なポートは不可）だけです。それ以外のリンクは、自分でホストしている公開 https URLであっても、モデルの実行前に 400 invalid_input で拒否されます。このチェックを通過しても実際のアップロードではないリンク（期限切れ、削除済み、入力ミス）はそのまま通ってしまい、Routerは画像のサイズを読み取れずに 400 ではなく 5xx エラーを返します。そのため、image_url は必ずアップロードが返したとおりに渡してください。

1. 各参照画像を multipart/form-data としてアップロードし、画像はフォームフィールド file に入れます（JPEG、PNG、WebP、最大75 MB）。認証はRouterの場合と同じく、X-API-Key または Authorization: Bearer を使用します。
   curl -X POST https://api.comfy.org/proxy/krea/assets \
     -H "X-API-Key: $COMFY_API_KEY" \
     -F "file=@reference.png"
   
2. JSONレスポンスから image_url を読み取り、image_urls で渡します。
   {
     "prompt": "Place the product on a clean studio background",
     "resolution": "1k",
     "image_urls": ["<image_url from step 1>"]
   }
   

テキストから画像への呼び出しでは image_urls を省略するため、アップロードは不要です。

​

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

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

​

次のステップ