Comfy Router API リファレンス

Comfy API 契約から生成済みの、Comfy Router のすべてのエンドポイント、パラメータ、レスポンスボディ、エラーバケット。

モデル ID でアドレス指定される Comfy Router の正規ルート。

ベース URL: https://api.comfy.org

以下のすべてのエンドポイントは認証が必要です。X-API-Key: <api-key> または Authorization: Bearer <jwt> を送信してください。

​

エンドポイント

​

GET /v1/models

Comfy Router が実行できるモデルを一覧表示します。

Comfy Router のモデルカタログ。POST /v1/models/{provider}/{model} が受け付ける正規モデル ID の 1 ページ分です。SDK はコールドスタート時にこの API を呼び出して実行可能なモデルを検出し、model_not_found の提案も同じカタログから取得されます。したがって、ここに掲載されている ID が呼び出し時に 404 になる場合は、どちらか一方の失敗だけよりも悪い結果になります。この一致は約束ではなく構造上のものです。エントリの provider と model は、呼び出しルートの2つのパスセグメントであり、そのルートのパスパラメータと同じスキーマコンポーネントを参照します。また、id はそれらの2つのセグメントを / で連結したものです。

パラメータ

名前	場所	必須	型	制約	説明
cursor	クエリ	いいえ	RouterPageCursor	pattern: ^[A-Za-z0-9._~+/=-]+$, minLength: 1, maxLength: 512	不透明なページネーションカーソル。前のページの next_cursor を渡すと次のページを取得できます。最初のページでは省略します。値が不透明である理由と、このルートがオフセットではなくカーソルでページネーションする理由については、RouterPageCursor を参照してください。
limit	クエリ	いいえ	integer	maximum: 100, default: 20	1 ページで返すモデル数。宣言された最大値を超える値は契約外ですが、このルートはそれらを拒否しません。代わりに最大値を返し、実際に返されるページサイズはレスポンスの limit としてエコーバックされるため、クランプは常に呼び出し側が検出できます。最大値を実際のページストライドとして扱ってください。より多くを要求し、より多くを受け取ったと想定するクライアントは行を失います。0 と負の値も受け入れられ、デフォルトを選択します。そのため minimum は宣言されていません。1 未満はここでは意味があり、無効ではありません。

レスポンス

ステータス	ボディ	ヘッダー	説明
200	RouterModelListResponse	X-Comfy-Request-Id	OK: モデルカタログの 1 ページ分。
400	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Router のリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type に繰り返されます。
401	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Router のリクエストレベルの失敗。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type に繰り返されます。	### GET /v1/models/{provider}/{model}

正規のモデル ID で、パートナーモデルのカタログエントリを 1 件読み取ります。

単一の Comfy Router モデルに対するモデル単位の詳細です。呼び出し元は、ページ分割されたカタログ全体を走査しなくても、1 つのモデルを確認できます。SDK はモデルを呼び出す直前に、このエンドポイントを使用してモデルを検索します。

パラメータ

名前	場所	必須	型	制約	説明
provider	パス	はい	RouterProviderSegment	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 64	正規の {provider}/{model}[/{variant}] モデル ID における小文字のプロバイダーセグメントです。実行されるモデルのパートナーを示します。
model	パス	はい	RouterModelSegment	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 128	正規の {provider}/{model}[/{variant}] モデル ID における小文字のモデルセグメントです。そのプロバイダー内で実行するモデルを示します。

レスポンス

ステータス	ボディ	ヘッダー	説明
200	RouterModelDetail	X-Comfy-Request-Id	OK: モデルのカタログエントリです。
403	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Router のリクエストレベルでの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗したことを示します。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type ヘッダーにも繰り返し含まれます。
404	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Router のリクエストレベルでの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗したことを示します。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type ヘッダーにも繰り返し含まれます。
503	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Router のリクエストレベルでの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗したことを示します。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type ヘッダーにも繰り返し含まれます。	### POST /v1/models/{provider}/{model}

正規モデルIDでパートナーモデルを同期的に実行します。

Comfy Routerの正規のエントリポイントであり、モデルIDでアドレス指定されます。リクエストボディはパートナーモデル自身のネイティブなJSON入力であり、成功レスポンスはそのモデル自身のネイティブなJSON出力です。RouterはComfy形式のエンベロープを押し付けるのではなく、両方をそのまま転送するため、呼び出し元はホストを変更するだけでパートナーのAPIとRouterを切り替えることができます。これは同期パスであり、POST https://fal.run/{id} をミラーリングします。レスポンスには完了した結果が含まれます。キュー処理用の対応エンドポイントである /v1/queue/models/{provider}/{model} が計画されており、falの fal.run と queue.fal.run の分割を単一のホストにまとめることになります。ただし、これはまだこの契約の一部ではありません。

パラメータ

名前	場所	必須	型	制約	説明
provider	path	yes	RouterProviderSegment	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 64	正規の {provider}/{model}[/{variant}] モデルIDの小文字のプロバイダーセグメント。モデルが実行されるパートナーを示します。
model	path	yes	RouterModelSegment	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 128	正規の {provider}/{model}[/{variant}] モデルIDの小文字のモデルセグメント。そのプロバイダー内で実行するモデルを示します。

リクエストボディ

application/json - RouterModelInput（必須）

パートナーモデルのネイティブなJSON入力で、プロバイダーにそのまま転送されます。

レスポンス

ステータス	ボディ	ヘッダー	説明
200	RouterModelOutput	X-Comfy-Request-Id	OK。パートナーモデルのネイティブなJSON出力がそのまま返されます。
401	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。
403	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。
404	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。
422	RouterValidationErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	リクエストはモデルに到達しましたが、モデルはその内容を拒否しました。ボディは RouterValidationErrorResponse であり、fal/FastAPIの detail[] 形状です。そのため、各問題のあるフィールドは独自の type と ctx を保持します。X-Comfy-Error-Type はレスポンス全体の大まかなバケットを伝えます。
429	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。
500	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。
503	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。
504	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗です。リクエストがモデルに到達しなかったか、モデル自身が報告しない理由で失敗しました。ボディは RouterErrorResponse であり、そのバケットは X-Comfy-Error-Type にも繰り返し記載されます。	### GET /v1/models/{provider}/{model}/openapi.json

1つのパートナーモデルの入力スキーマをOpenAPIドキュメントとして読み取ります。

単一のComfy Routerモデルのモデルごとの入力スキーマは、スタンドアロンのOpenAPIドキュメントとして提供されます。これにより、呼び出し側（SDK、コード生成ツール、またはエージェント）は、Comfyの解説ドキュメントを読まなくてもモデルの引数を発見できます。これはfalのモデルごとのスキーマエンドポイントを反映したものであり、SDKクイックスタートが依存する発見メカニズムです。

パラメータ

名前	場所	必須	型	制約	説明
provider	path	yes	RouterProviderSegment	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 64	正規の {provider}/{model}[/{variant}] モデルIDの小文字のプロバイダーセグメント。実行されるモデルのパートナーです。
model	path	yes	RouterModelSegment	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 128	正規の {provider}/{model}[/{variant}] モデルIDの小文字のモデルセグメント。そのプロバイダー内で実行するモデルです。

レスポンス

ステータス	ボディ	ヘッダー	説明
200	RouterModelInputSchemaDocument	X-Comfy-Request-Id, ETag, Cache-Control	OK: モデルの入力スキーマをスタンドアロンのOpenAPIドキュメントとして返します。
304	-	X-Comfy-Request-Id, ETag, Cache-Control	Not Modified: 呼び出し側が If-None-Match で送信した ETag 以降、ドキュメントは変更されていません。ボディは返されません。
404	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗: リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗しました。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type に繰り返されます。
500	RouterErrorResponse	X-Comfy-Error-Type, X-Comfy-Request-Id	Routerのリクエストレベルの失敗: リクエストがモデルに到達しなかったか、モデル自身が報告しなかった理由で失敗しました。ボディは RouterErrorResponse で、バケットは X-Comfy-Error-Type に繰り返されます。

​

エラーバケット

Router の失敗を示す、粗い粒度の機械可読バケットです。X-Comfy-Error-Type レスポンスヘッダーにもミラーリングされるため、呼び出し側はボディを解析せずに分岐できます。セットは15個の値で固定されています。リクエストレベルの6つのバケット invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits、model_not_found に加え、トランスポートレベルの unauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable、rate_limited です。

​

リクエストレベルバケット

Router が受け付けたものの完了できなかったリクエストに対して発生します。

error_type	意味
invalid_input	リクエストがモデルに到達する前に拒否されました。不正な形式のボディ、不正または期限切れのページネーションカーソル、またはモデル自身のスキーマが受け付けない入力が原因です。
content_policy_violation	プロバイダーがコンテンツポリシーを理由にリクエストを拒否しました。この拒否は決定的です。同じ入力を再送信しても再び拒否されます。
provider_error	パートナープロバイダーが自身の障害を報告したか、Router が結果として解釈できないレスポンスを返しました。
provider_timeout	パートナープロバイダーが期限までに応答しませんでした。このバケットはプロバイダーのタイムアウトであり、Router 自身のサーバー側の期限ではありません。サーバー側の期限は deadline_exceeded として報告されます。両者は 504 を共有しますが、原因が異なるため区別されます。こちらはパートナーが失敗したことを示し、あちらは Comfy が接続の維持を停止したことを示します。
insufficient_credits	呼び出し元のワークスペースに、モデルを実行するための十分なクレジットがありません。
model_not_found	{provider}/{model} という ID が、Router で実行できるモデルを指していません。不明なプロバイダーもここに分類されます。detail には、呼び出し側が閲覧を許可されているモデルから抽出された最大3件の提案が含まれます。

​

トランスポートレベルバケット

モデルへの呼び出しの前またはその周辺で、Router 自身によって発生します。

error_type	意味
unauthorized	リクエストに利用可能な認証情報が含まれていませんでした。
forbidden	認証情報は有効ですが、このモデルまたはこの操作に対する権限がありません。
concurrency_limit_exceeded	ワークスペースはすでに許可された数の呼び出しを実行中です。いずれかが完了したら再試行してください。
client_disconnected	呼び出し側が、Router が結果を返す前に接続を閉じました。これは配信ではなくログに記録されます。書き込むソケットが残っていないためです。また、これは課金結果ではなく原因の帰属を示すものです。完了したプロバイダーによる生成は、呼び出し側がレスポンスを受信したかどうかに関係なく請求されます。
internal_error	Router 自体が失敗しました。これは、クライアントが認識できないバケットを扱う際の値でもあります。これにより、後でセットに追加が行われても、それ以前に生成されたクライアントが壊れることはありません。
deadline_exceeded	回答が到着する前に、Comfy が自身の設定済みの上限で接続の維持を停止しました。provider_timeout と 504 を共有し、このペアはどちらの側が時間切れになったかを示します。こちらは Comfy 自身の上限であるため、リクエストのいかなる部分も拒否されておらず、同じリクエストを再試行できます。課金については何も示しません。完了したプロバイダーによる生成は、呼び出し側がレスポンスを受信したかどうかに関係なく請求されます。
not_enabled	この呼び出し側に対して Comfy Router がまだ有効になっていません。リクエストに問題はなく、モデルも存在するため、model_not_found ではありません。forbidden と 403 を共有しますが、同じものではありません。forbidden は呼び出し側に関する権限の判断であるのに対し、こちらはロールアウトの状態だからです。これは終端状態です。再試行せず、また障害として扱わないでください。
service_unavailable	Comfy Router が依存するサービスが一時的に利用できず、呼び出し側に問題はありません。バックオフを伴って再試行してください。これは、呼び出し側がリクエストを変更することなく、また並行処理スロットが解放されることもなく、条件が自動的に解消される唯一のバケットです。これが他の再試行可能な応答 (concurrency_limit_exceeded、deadline_exceeded) との違いです。また、internal_error とは区別されます。internal_error は 500 で、Router 自体が失敗したことを意味します。これにより、クライアントは「すぐに再試行してください」と「この呼び出しは成功しない」を区別できます。
rate_limited	呼び出し側がウィンドウ単位で測定される割り当てを消費し、そのウィンドウが経過するのを待つ必要があります。concurrency_limit_exceeded と 429 を共有しますが、同じものではありません。concurrency_limit_exceeded は、呼び出し側自身の実行中の呼び出しが1つ完了した時点で解消されるため、数秒以内の再試行が適切です。一方、こちらは呼び出し側が何をしても早く解消されません。detail はウィンドウを示します。

​

レスポンスヘッダー

ヘッダー	型	説明
Cache-Control	string	提供されるスキーマドキュメントの鮮度ディレクティブ。ルートが認証済みのため private です。ドキュメント自体は呼び出し元固有ではありませんが、共有キャッシュは認証済みリクエストへのレスポンスを保持してはなりません。また、must-revalidate により、古いコピーはそのまま提供されるのではなく ETag に対して再検証されます。
ETag	string	GET /v1/models/{provider}/{model}/openapi.json で提供されるドキュメントのバイト列に対する強力なエンティティタグ。モデルごとのスキーマはほとんど変更されず、SDK が頻繁に再取得するため、呼び出し元はこの値を保存し、If-None-Match として送り返すことで、ドキュメントの代わりに 304 を受け取るべきです。
X-Comfy-Error-Type	RouterErrorType	障害の大まかな機械可読バケットで、Router がすべてのエラーレスポンスに設定します。RouterErrorResponse.error_type と同じ値を保持し、422 では唯一の機械可読バケットです。これは、そのボディが fal/FastAPI の detail[] 形状であり、独自の error_type フィールドを持たないためです。したがって、クライアントは、受信した 2 つの Router エラーボディのどちらであるかを判断する前に、このヘッダーだけで分岐できます。
X-Comfy-Request-Id	string	この呼び出しのサーバー生成識別子で、成功、4xx、5xx を問わず、すべての Router レスポンスに存在します。エラーレスポンスこそ、ユーザーがサポートリクエストで引用する ID を必要とするタイミングだからです。同じ値が呼び出しの使用状況/監査イベントにも書き込まれるため、課金に関する苦情をタイムスタンプで検索する代わりに、課金自体に結び付けることができます。

​

モデルごとの入力スキーマ

モデル独自の入力フィールドはここでは再掲しません。それらは GET /v1/models/{provider}/{model}/openapi.json から直接取得できます。このエンドポイントは、サーバーが呼び出しの検証に使用するのと同じドキュメントを提供するため、公開されている内容と実際に適用される内容が乖離することはありません。GET /v1/models からモデルIDを取得し、その呼び出しパスに /openapi.json を追加して、返されたドキュメントに基づいて生成します。

​

スキーマ

​

RouterChargesOnPolicyRejection

このモデルがコンテンツポリシー上の理由で拒否する呼び出しが、それでも呼び出し元に課金されるかどうか。プロバイダーによって異なり、その違いは呼び出し時に判別できません。同じ呼び出しでエラーと課金の両方を目にしたユーザーには、事前にそれを知る手段がありません。そのため、プロバイダーごとの暗黙の了解に委ねるのではなく、呼び出しの前にモデルごとに明記されています。

型: string

​

RouterErrorResponse

Routerのリクエストレベルのエラーボディ: リクエストがモデルに到達しなかった場合、またはモデル自身が報告しなかった理由(認証、クォータ、不明なモデルID、プロバイダーのトランスポート)で失敗した場合に返されるものです。モデルレベルの検証失敗には独自の形状RouterValidationErrorResponseがあります。FastAPIのdetail[]配列をこのdetail文字列に平坦化すると、SDKが分岐の判断に使用するフィールド単位の粒度が失われるためです。

フィールド	型	必須	制約	説明
detail	string	はい	-	失敗の人間が読める説明で、エンドユーザーに表示しても安全です。機械解析されません。代わりにerror_typeで分岐してください。
error_type	RouterErrorType	はい	-	Routerの失敗を示す大まかな機械可読バケットで、X-Comfy-Error-Typeレスポンスヘッダーにも反映されるため、呼び出し元はボディを解析せずに分岐できます。このセットは15個の値に固定されています。リクエストレベルの6つのバケット(invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits、model_not_found)に加え、トランスポートレベルの9つのバケット(unauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable、rate_limited)があります。

​

RouterErrorType

Router障害の大まかで機械可読なバケットであり、X-Comfy-Error-Type レスポンスヘッダーにもミラーリングされるため、呼び出し元はボディを解析せずに分岐できます。このセットは15個の値に限定されており、リクエストレベルの6つのバケット（invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits、model_not_found）と、トランスポートレベルのunauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable、rate_limitedです。

型: string

​

RouterModelBilling

呼び出し前に呼び出し元が把握しておくべき、価格ではなくモデル単位の課金に関する事実です。利用量やコストの数値がここに記載されることはありません。

フィールド	型	必須	制約	説明
charges_on_policy_rejection	RouterChargesOnPolicyRejection	yes	-	このモデルがコンテンツポリシーに基づいて拒否した呼び出しが、それでも呼び出し元に課金されるかどうか。プロバイダーによって対応は異なり、その違いは呼び出し時には見えません。同じ呼び出しに対してエラーと課金の両方を確認したユーザーには、事前にそれを知る手段はありません。そのため、この情報はプロバイダーごとの慣習に委ねられるのではなく、呼び出し前にモデル単位で明記されます。

​

RouterModelDetail

1つのComfy Routerモデルに関するモデルごとの詳細。カタログ一覧で示されるすべての情報に加え、単一モデルルートのみが保持するモデルごとのフィールドを含みます。

RouterModelListEntry と RouterModelDetailFields で構成されます。

型:object

​

RouterModelDetailFields

カタログ一覧が保持しない RouterModelDetail の半分: モデルごとのフィールドで、1回の参照には値するものの、ページ分割されたカタログページのすべてのエントリで繰り返すほどではないものです。

フィールド	型	必須	制約	説明
input_schema_url	文字列	いいえ	format: uri, pattern: ^https://, maxLength: 2048	このモデルの入力スキーマドキュメントへのポインタ: このモデルに対して POST /v1/models/{provider}/{model} が受け付けるボディの説明です。この契約の一部となるのはポインタのみです。ポインタが指すドキュメントは別途作成されます。モデル用のスキーマが作成されていない場合は存在しません。

​

RouterModelId

正規の Comfy Router モデル ID です。{provider}/{model} は、POST /v1/models/{provider}/{model} でモデルを指定する際に使用する正確な値です。そのため、呼び出し元はこの値をそのままパスに埋め込むことができ、他の情報から再導出する必要はありません。pattern は RouterProviderSegment と RouterModelSegment を単一の / で連結したもので、maxLength はそれらの合計にそのセパレータを加えた長さです。

型: string、pattern: ^[a-z0-9]+([._-][a-z0-9]+)*/[a-z0-9]+([._-][a-z0-9]+)*$、maxLength: 193

​

RouterModelInput

パートナーモデルのネイティブな JSON 入力ドキュメントで、プロバイダーにそのまま転送されます。具体的な形状は Comfy ではなくパートナーが所有するため、これはオープンオブジェクトです。Router はフィールドを絞り込んだり、名前を変更したり、再ラップしたりしません。これは名前付きコンポーネントです（インラインの無名オブジェクトにはなりません）。ComfyUI の仕様駆動のコード生成では、生成対象のクラスが必要だからです。

型: object

​

RouterModelInputSchemaDocument

単一の Comfy Router モデルの入力を説明するスタンドアロンの OpenAPI ドキュメントです。これは、そのモデルに対して POST /v1/models/{provider}/{model} が受け付けるボディです。GET /v1/models/{provider}/{model}/openapi.json が返すのはこのドキュメントです。

型: object

​

RouterModelListEntry

Routerモデルカタログの1エントリです。実行可能なモデルの識別情報であり、それ以外の何ものでもありません。モデルごとの詳細ルートは、この同じエントリを再掲するのではなく合成するため、名前は...Summaryではなく...ListEntryとなっています。カタログエントリの定義は正確に1つだけ存在する必要があります。モデルごとの詳細と、モデルごとの入出力スキーマはそれぞれ独自のルートであるため、この形状は、呼び出し元がモデルを呼び出すために必要な最小限のものに留まっています。これは意図的なものであり、SDKがコールドスタート時に取得するペイロードだからです。idはproviderとmodelを/で連結したものです。この2つのフィールドは個別にも保持されるため、呼び出し元は文字列を分割することなく呼び出しパスを構成できます。

フィールド	型	必須	制約	説明
id	RouterModelId	はい	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*/[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 193	正規のComfy RouterモデルID、{provider}/{model}です。POST /v1/models/{provider}/{model}でモデルを指定する正確な値であり、呼び出し元は何かから再導出することなく、この値をそのパスに挿入できます。そのpatternはRouterProviderSegmentとRouterModelSegmentを単一の/で連結したものであり、maxLengthはそれらの合計にその区切り文字を加えたものです。
provider	RouterProviderSegment	はい	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 64	正規の{provider}/{model}[/{variant}]モデルIDの小文字のproviderセグメントです。つまり、モデルが指定されているパートナーです。呼び出しルートのproviderパスパラメータとカタログエントリのproviderフィールドは、どちらもこの1つのスキーマを参照しており、これにより、リストされたIDと受け入れられるIDが乖離しないようになっています。
model	RouterModelSegment	はい	pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$, maxLength: 128	正規の{provider}/{model}[/{variant}]モデルIDの小文字のmodelセグメントです。つまり、そのプロバイダー内で実行するモデルです。RouterProviderSegmentと同じ乖離防止の理由により、呼び出しルートのmodelパスパラメータとカタログエントリのmodelフィールドで共有されています。
billing	RouterModelBilling	はい	-	呼び出し元が呼び出し前に必要とするモデルごとの請求の事実です。価格ではありません。使用量やコストの数値がここに現れることはありません。

​

RouterModelListResponse

Routerモデルカタログの1ページ。

フィールド	型	必須	制約	説明
data	RouterModelListEntry の配列	必須	-	このページに含まれるモデル。最大で limit 個。
has_more	ブール	必須	-	このページの先に別のページが存在するかどうか。これが true の間はウォークを続けてください。data が短い、または空だからといって、カタログの終端を推測しないでください。
next_cursor	RouterPageCursor	任意	pattern: ^[A-Za-z0-9._~+/=-]+$, minLength: 1, maxLength: 512	Routerリストへの不透明カーソル。サーバーによって生成され、ラウンドトリップされるだけです。オフセットでもモデルIDでもなく、順序付けもされておらず、カタログの再構築をまたいで安定することもありません。そのため、カーソルを解析したり、インクリメントしたり、取得元のウォークを超えて永続化したりすることは、すべて契約の範囲外です。カーソルがオフセットではなく使用されるのは、カタログが移動するリストだからです。オフセットによるウォークでは、ウォークの途中でエントリが追加または削除されると、エントリが暗黙的にスキップまたは繰り返され、呼び出し元はそれが発生したことを認識できません。
limit	整数	必須	minimum: 1, maximum: 100	実際に提供されたページサイズ。最大値を超える limit のリクエストは拒否されず、最大値にクランプされます。そのため、この値はリクエストされた値より小さくなることがあります。ページングには送信した値ではなくこの値を使用してください。そうしないと、実際には受信していない行があると想定してしまうことになります。

​

RouterModelOutput

パートナーモデルのネイティブなJSON出力ドキュメントであり、呼び出し元にそのまま返されます。その具体的な形状はComfyではなくパートナーが所有しているため、これはオープンなオブジェクトです。Routerはフィールドの絞り込み、名前の変更、再ラップを行いません。これは名前付きコンポーネントです（インラインの匿名オブジェクトではありません）。ComfyUIのスペック駆動のコード生成では、生成対象のクラスが必要になるためです。

型: object

​

RouterModelSegment

正規の {provider}/{model}[/{variant}] モデル ID の小文字の model セグメント。そのプロバイダー内で実行するモデルを指します。RouterProviderSegment と同じくドリフトを防ぐため、呼び出しルートの model パスパラメータとカタログエントリの model フィールドで共有されます。

型: 文字列。pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$、maxLength: 128

​

RouterPageCursor

Router リストに対する不透明なカーソルです。これはサーバーによって生成され、常にラウンドトリップされるだけです。オフセットでもなく、モデルIDでもなく、順序付けもされておらず、カタログの再構築をまたいでも安定しません。そのため、カーソルを解析したり、インクリメントしたり、導出元となった走査を超えて永続化したりすることは、すべて契約の範囲外です。カタログが変動するリストであるため、オフセットではなくカーソルが採用されています。オフセットによる走査では、走査の途中でエントリが追加または削除されると、エントリが暗黙的にスキップまたは繰り返され、呼び出し側はその発生を検知できません。

型: string — pattern: ^[A-Za-z0-9._~+/=-]+$, minLength: 1, maxLength: 512

​

RouterProviderSegment

標準の {provider}/{model}[/{variant}] モデルIDの小文字の provider セグメント。これは、モデルがアドレス指定されるパートナーを示します。呼び出しルートの provider パスパラメータとカタログエントリの provider フィールドは、どちらもこの単一のスキーマを参照します。これにより、リストされたIDと受け入れられるIDが乖離するのを防ぎます。

型: string。pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$、maxLength: 64

​

RouterValidationErrorContext

1つの RouterValidationErrorDetail に対する違反されたバウンドで、プロバイダーからそのまま引き継がれます。例えば、greater_than に付随する {"limit_value": 8}、image_too_small に付随する {"min_width": 512}、file_too_large に付随する {"max_size_bytes": 10485760} などです。キーのセットはプロバイダーとエラータイプに固有であるため、これは意図的にオープンなオブジェクトです。固定のフィールドリストに絞り込んだり、msg 文字列に折り込んだりすることは、移植されたインテグレーションがコンパイルされ、バウンドを読み取るブランチを静かに失う、まさにその方法です。エラータイプがバウンドを持たない場合は存在しません。

型: object

​

RouterValidationErrorDetail

fal/FastAPI 形式のモデルレベルの検証エラー 1 件分です。type は、RouterErrorType の粗いバケットでは表現できない粒度である、プロバイダー固有の具体的な理由（value_error、missing、image_too_small、unsupported_audio_format、greater_than、file_too_large など）を保持します。同じ理由で、これはオープンな文字列であり、enum ではありません。プロバイダーの語彙は 2 つの層にわたって約 48 の値に上り、当社ではなくプロバイダーのリリースサイクルに応じて増えていきます。モデル化されていない値は、デシリアライゼーションに失敗するのではなく、呼び出し元に届かなければなりません。

フィールド	型	必須	制約	説明
loc	any の配列	はい	-	問題のあるフィールドへのパス。最も外側のセグメントが先頭になります。例えば ["body", "image_url"]、または整数が配列のインデックスとなる ["body", "images", 0]。
msg	文字列	はい	-	この 1 件の失敗を人間が読める形式で説明したもの。
type	文字列	はい	-	この失敗の具体的かつ機械可読な理由で、プロバイダーから変更されずにそのまま渡されます。型付き SDK の例外階層が分岐する際に参照する値です。レスポンスヘッダーの error_type は、その粗いバケットにすぎません。
ctx	RouterValidationErrorContext	いいえ	-	1 つの RouterValidationErrorDetail について違反された制約で、プロバイダーからそのまま引き継がれます。例えば、greater_than の場合は {"limit_value": 8}、image_too_small の場合は {"min_width": 512}、file_too_large の場合は {"max_size_bytes": 10485760} などです。キーセットはプロバイダーとエラータイプに固有であるため、これは意図的にオープンなオブジェクトです。固定のフィールドリストに絞り込むこと、または msg 文字列に折り込むことは、移植された統合がコンパイルに成功した後に、制約を読み取っていた分岐を黙って失う、まさにその方法です。エラータイプが制約を伴わない場合は存在しません。
input	RouterValidationErrorInput	いいえ	-	問題となった入力値で、呼び出し元が loc から再導出しなくても何が拒否されたかを確認できるよう、そのままエコーバックされます。文字列、数値、ブール、配列、オブジェクト、null など、あらゆる JSON 型を取り得るため、このスキーマはオブジェクトに絞り込むのではなく、意図的に型付けされないままとなっています。プロバイダーが入力をエコーバックしない場合は存在しません。

​

RouterValidationErrorInput

拒否された入力値をそのままエコーバックしたものです。呼び出し元は loc から値を再導出しなくても、何が拒否されたかを確認できます。値はあらゆるJSON型（文字列、数値、ブール、配列、オブジェクト、null）を取り得るため、このスキーマはオブジェクトに限定せず、意図的に型指定なしとしています。プロバイダーが入力をエコーバックしない場合、このフィールドは存在しません。

​

RouterValidationErrorResponse

Routerのモデルレベルの422ボディ（fal/FastAPI形式）：リクエストはモデルに到達するのに十分な形式であり、モデルがその内容を拒否したことを示します。これ自体にはerror_typeが含まれないことに注意してください。その役割はレスポンスのX-Comfy-Error-Typeヘッダーが担うため、クライアントは2種類のRouterエラーボディのどちらを受信したかを先に判断することなく、ヘッダーから大まかな分類を読み取ることができます。

フィールド	型	必須	制約	説明
detail	RouterValidationErrorDetailの配列	はい	-	リクエストで見つかったすべての検証エラー。問題のあるフィールドごとに1つのエントリ。