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 はモデルを実行する前に、各参照を自身でフェッチしてサイズを読み取ります。修正が必要な参照は、そのホスト名を示す400invalid_inputで拒否されます。対象は、存在しないホストまたは公開到達できないホスト、408または429以外の4xxを返すオリジン、リダイレクトが多すぎる場合、httpsでないリンクまたは公開到達できないホストへのリダイレクト、サポートされていない画像であるコンテンツ、画像のサイズヘッダーの前に終了してしまう長さのないレスポンス、サイズヘッダーが最初の 2 MiB 以内にない画像(下記参照)です。それ以外のフェッチ失敗は代わりに5xxエラーになります(Router では500internal_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(またはなし)で再送信してください。変更されたボディでキーを再利用すると409invalid_inputで拒否されますが、これは画像について何も示しません。同じボディで再利用すると、元のrequest_idとIdempotent-Replayed: trueを伴う201で応答されるため、新しい実行は開始されず、その結果 URL(GET /v2/models/krea/krea-3/requests/{request_id})は同じ400を返します(そのステータス URL はerror_typeinvalid_inputを伴う200で応答します)。その再送信も400で失敗する場合、問題は画像自体にあります(たとえば、サポートされていない画像である、またはそのサイズヘッダーが最初の 2 MiB 以内にない)。 - 他のリンクが受け付けられない場合、すべてのエントリはアップロードが返した
image_urlでなければなりません。Router は、そのリンクがホストが正確にapp-uploads.krea.aiであるhttpsURL としてパースできることのみをチェックします(他のホストや明示的なポートは不可)。他のリンク、たとえばご自身でホストする公開httpsURL は、モデルを実行する前に「image_urls must be image_url values returned by POST /proxy/krea/assets」と述べる400invalid_inputで拒否されるため、代わりに画像をアップロードしてください。そのチェックを通過しても実際のアップロードではないリンク(期限切れ、削除済み、または誤記)は依然として通過し、Router は画像のサイズを読み取れずに5xxエラーで応答します(400ではありません)。Router が読み取れないアップロード済みの画像(たとえば、サポートされていない画像である、またはそのサイズヘッダーが最初の 2 MiB 以内にない)も、ここでは400ではなく5xx(Router では500internal_error)で失敗し、問題は依然として画像にあるため、再度アップロードしても役に立ちません。 - サーバーの起動直後、どのルールが適用されるかを学習する前は、
app-uploads.krea.aiのリンクでない任意のhttpsURL が503(Router ではservice_unavailable)で失敗する可能性があり、これは再試行しても安全です(キューに入れられたリクエストは自動的に再試行されます)。
400 で拒否され、アップロードしても役に立ちません。まず大きなメタデータを含めずに再保存するか、パレット PNG を非パレット(トゥルーカラー)PNG として保存してください。国際化されたホスト名は ASCII(punycode)形式で送信してください。たとえば bücher.de ではなく xn--bcher-kva.de です。Router は記述されたとおりにホストを検索し、非 ASCII の名前は存在しないホストとして拒否されます。
アップロードはすべての環境で機能するため、移植性のある選択肢です。常にアップロードが返したとおりに image_url を渡してください。画像がまだ公開 https URL にない場合は、まずアップロードしてください:
-
各参照画像を
multipart/form-dataとしてアップロードします。画像はフォームフィールドfileに含めます(JPEG、PNG、または WebP、最大 75 MB)。Router と同じ方法で、X-API-KeyまたはAuthorization: Bearerを使用して認証します。 -
JSON レスポンスから
image_urlを読み取り、image_urlsに渡します:
image_urls を省略し、アップロードは不要です。
モデルの出力と保存されたアセット
入力フィールドと出力フィールドはモデルによって異なります。プロバイダー SDK やプロキシから移行すると、ルートと結果の読み取り方法の両方が変わる可能性があります。 一部のアセットは Comfy ストレージに再ホストされます。その他はプロバイダーの URL またはインラインバイトです。有効期間とリプレイ動作については、結果アセット を参照してください。次のステップ
クイックスタート
Comfy Router を通じて最初の画像を生成します。
Router API の使用
モデルを選択し、そのスキーマを確認して、結果と再試行を処理します。