Comfy Router API reference

Comfy Router’s canonical, model-ID-addressed routes. Base URL: https://api.comfy.org Every endpoint below is authenticated. Send X-API-Key: <api-key> or Authorization: Bearer <jwt>. Comfy API keys can also be sent as Bearer tokens. X-API-Key takes precedence when both credential headers are supplied. See authentication headers for the key/JWT distinction and the Quickstart for access requirements.

Endpoints

`GET /v2/models`

List the models Comfy Router can run. List available model IDs and billing facts. Use next_cursor while has_more is true. Parameters

Name	In	Required	Type	Constraints	Description
`cursor`	query	no	`RouterPageCursor`	Opaque cursor returned as `next_cursor`, 1–512 characters	Opaque pagination cursor.
`limit`	query	no	integer	Up to 100, Default: 20	Number of models to return in one page.

Responses

Status	Body	Headers	Description
`200`	`RouterModelListResponse`	`X-Comfy-Request-Id`	OK - one page of the model catalog.
`400`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Invalid request. Check the error type and request body.
`401`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Missing or invalid credentials.
`403`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The request is not allowed for this caller or model.
`503`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Router is temporarily unavailable. Retry with backoff.

`GET /v2/models/{provider}/{model}`

Read one partner model’s catalog entry by canonical model ID. Read details for one model without listing the full catalog. Parameters

Name	In	Required	Type	Constraints	Description
`provider`	path	yes	`RouterProviderSegment`	Alphanumeric slug, e.g. `anthropic`, Up to 64 characters	Provider portion of the canonical `{provider}/{model}` model ID.
`model`	path	yes	`RouterModelSegment`	Alphanumeric slug, e.g. `claude-opus-4-6`, Up to 128 characters	Model portion of the canonical `{provider}/{model}` model ID.

Responses

Status	Body	Headers	Description
`200`	`RouterModelDetail`	`X-Comfy-Request-Id`	OK - the model’s catalog entry.
`401`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Missing or invalid credentials.
`403`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The request is not allowed for this caller or model.
`404`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The model ID was not found.
`503`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Router is temporarily unavailable. Retry with backoff.

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

Run a partner model synchronously by canonical model ID. Run a model and receive its finished result in the same response. Parameters

Name	In	Required	Type	Constraints	Description
`provider`	path	yes	`RouterProviderSegment`	Alphanumeric slug, e.g. `anthropic`, Up to 64 characters	Provider portion of the canonical `{provider}/{model}` model ID.
`model`	path	yes	`RouterModelSegment`	Alphanumeric slug, e.g. `claude-opus-4-6`, Up to 128 characters	Model portion of the canonical `{provider}/{model}` model ID.
`Idempotency-Key`	header	no	string	1–255 characters	Caller-generated key that makes retrying ONE logical call safe.

Request body application/json — RouterModelInput (required) The partner model’s native JSON input, forwarded to the provider unchanged. Responses

Status	Body	Headers	Description
`200`	`RouterModelOutput`	`X-Comfy-Request-Id`, `Idempotent-Replayed`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining`	OK - the partner model’s native JSON output, returned unchanged.
`400`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed`	Invalid request. Check the error type and request body.
`401`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Missing or invalid credentials.
`403`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The request is not allowed for this caller or model.
`404`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The model ID was not found.
`409`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` (when `concurrency_limit_exceeded`)	Inspect `X-Comfy-Error-Type`: `concurrency_limit_exceeded` means the original call is still running, so wait for `Retry-After` and reuse the same key; `invalid_input` requires a new key.
`413`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The request body is too large.
`422`	`RouterValidationErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed`	The request’s contents were rejected against the model’s schema.
`429`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining`	Inspect `X-Comfy-Error-Type`: `concurrency_limit_exceeded` means reduce in-flight calls; `rate_limited` means wait for the allowance window.
`503`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Router is temporarily unavailable. Retry with backoff.
`504`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After`	The request exceeded a deadline. Check the error type before retrying.

`GET /v2/models/{provider}/{model}/openapi.json`

Read one partner model’s input and output schemas as an OpenAPI document. Read one model’s input and output schemas as a standalone OpenAPI document. Parameters

Name	In	Required	Type	Constraints	Description
`provider`	path	yes	`RouterProviderSegment`	Alphanumeric slug, e.g. `anthropic`, Up to 64 characters	Provider portion of the canonical `{provider}/{model}` model ID.
`model`	path	yes	`RouterModelSegment`	Alphanumeric slug, e.g. `claude-opus-4-6`, Up to 128 characters	Model portion of the canonical `{provider}/{model}` model ID.
`If-None-Match`	header	no	string	-	The `ETag` a caller holds from an earlier `200`.

Responses

Status	Body	Headers	Description
`200`	`RouterModelInputSchemaDocument`	`X-Comfy-Request-Id`, `ETag`, `Cache-Control`	OK - the model’s input AND output schemas, as a standalone OpenAPI document.
`304`	-	`X-Comfy-Request-Id`, `ETag`, `Cache-Control`	Not Modified - the document is unchanged since the `ETag` the caller sent in `If-None-Match`.
`401`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Missing or invalid credentials.
`403`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The request is not allowed for this caller or model.
`404`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The model ID was not found.
`500`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Router could not complete the request.
`503`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	Router is temporarily unavailable. Retry with backoff.

Table descriptions are brief. Use Using the Comfy Router API for model selection, validation, retries, and billing, and Headers for header behavior.

Error buckets

Machine-readable Router error category, also sent in the X-Comfy-Error-Type header.

Request-level buckets

Raised for a request Router accepted and then could not complete.

`error_type`	Meaning
`invalid_input`	The request was rejected before it reached the model - a malformed body, a malformed or expired pagination cursor, an input the model’s own schema does not accept, or an `Idempotency-Key` that cannot serve this request (already used for a different request - the method, the path and query, or the body differ - or already consumed by a call whose response cannot be replayed).
`content_policy_violation`	The provider refused the request on content-policy grounds.
`provider_error`	The partner provider reported a failure of its own, or returned a response Router could not interpret as a result.
`provider_timeout`	The partner provider did not answer within its deadline.
`insufficient_credits`	The calling workspace does not have enough credits to run the model.
`model_not_found`	The `{provider}/{model}` ID names no model Router can run; an unknown provider lands here too.

Transport-level buckets

Raised by Router itself, before or around the call to the model.

`error_type`	Meaning
`unauthorized`	The request carried no usable credential.
`forbidden`	The credential is valid but is not entitled to this model or this operation.
`concurrency_limit_exceeded`	The workspace already has as many calls in flight as it is allowed; retry once one of them finishes.
`client_disconnected`	The caller closed the connection before Router could return a result.
`internal_error`	Router itself failed.
`deadline_exceeded`	Comfy stopped holding the connection at its own configured bound before an answer arrived.
`not_enabled`	Comfy Router is not switched on for this caller yet.
`service_unavailable`	A service Comfy Router depends on is temporarily unavailable and the caller did nothing wrong.
`rate_limited`	The caller has spent an allowance measured over a WINDOW and must wait for that window to roll.

Response headers

Header	Type	Description
`Cache-Control`	string	Freshness directives for the served schema document.
`ETag`	string	Strong entity tag over the served document’s bytes, for `GET /v2/models/{provider}/{model}/openapi.json`.
`Idempotent-Replayed`	boolean	Present and `true` when this response was served from an `Idempotency-Key`’s record rather than by running the model again.
`Retry-After`	integer	Seconds to wait before retrying the SAME request with the SAME `Idempotency-Key`.
`X-Comfy-Error-Type`	`RouterErrorType`	Coarse, machine-readable bucket for the failure, set by Router on every error response.
`X-Comfy-Request-Id`	string	Server-generated identifier for this call, present on EVERY Router response - success, 4xx and 5xx alike, because an error response is exactly when a user needs an id to quote in a support request.
`X-Committed-Spend-Current`	integer	The USD cents the caller currently has committed to calls still in flight.
`X-Committed-Spend-Limit`	integer	The ceiling, in USD cents, on the partner spend the caller may have committed to calls still in flight - money held from the moment a call is admitted and released when that call finishes.
`X-Committed-Spend-Remaining`	integer	The USD cents of headroom left under the ceiling, floored at zero.

Result assets

A model can return asset URLs, inline bytes, or both. The providers below copy selected assets onto Comfy storage and replace their URLs. This behavior depends on the model; there is no request header that selects it.

Models	What is copied onto Comfy storage	Maximum Comfy-hosted URL lifetime
`bfl/*`	the finished asset, and the draft-cache asset when the result carries one	24 hours
`byteplus/*` video models (`seedance`, `dreamina-seedance`)	the finished video, and the last-frame image when the result carries one	24 hours
`minimax/*`	the finished video	12 hours
`xai/*`	every generated image, and the finished video	24 hours

These lifetimes start when the URL is signed, not when you open it. Cached or replayed URLs can have less time remaining; replay does not renew them. Download the asset promptly. Only the assets named in each row are copied: byteplus/seedream-* and byteplus/seededit-* images are not covered by the BytePlus video row. Veo (veo/*) has a separate storage path. In response.videos[], read whichever member is present: bytesBase64Encoded contains the clip inline, while gcsUri contains a Comfy-signed HTTPS link when the environment is configured for direct provider writes to Comfy storage. That link is valid for 24 hours from the response. The latter case writes the asset directly rather than copying it, so Veo is not in the rehosting table. Other models return provider asset references or inline bytes. Provider URLs follow the provider’s expiry, which can be much shorter than the lifetimes above and is not specified by the Router contract. Copying is best effort per asset. If one copy fails, that entry keeps its provider reference; the response can contain both Comfy and provider URLs, with no explicit per-asset copy-status field. The generation still succeeds and is charged. Do not infer every URL’s lifetime from one successfully rehosted asset. The xai and minimax adapters serialize through known provider types, so undeclared provider fields may be omitted. Consult the model’s output schema rather than assuming that every field from a provider SDK is preserved. Whether a result is Comfy-hosted also decides whether a completed call can still be replayed from its Idempotency-Key record later; the Idempotency-Key parameter above says what a retry is answered with when it cannot be.

Per-model input and output schemas

Read each model’s fields from GET /v2/models/{provider}/{model}/openapi.json. The operation’s requestBody describes input validation; its 200 response describes the output shape and media type when authored. When x-comfy-input-schema-authored is false, Router accepts any JSON object without model-specific prevalidation. Provider requirements still apply. The output schemas describe results; Router does not validate returned provider payloads against them. An unauthored output may use */* rather than application/json; inspect the response content type before decoding it.

Schemas

RouterChargesOnPolicyRejection

Whether a content-policy refusal is charged for this model. Treat an unknown value as potentially charged. Type: string

RouterErrorResponse

Error body for authentication, access, model lookup, quota, and provider transport failures.

Field	Type	Required	Constraints	Description
`detail`	string	yes	-	Human-readable description of the failure, safe to surface to an end user. Not machine-parsed - branch on `error_type` instead.
`error_type`	`RouterErrorType`	yes	-	Coarse, machine-readable bucket for a Router failure, mirrored on the `X-Comfy-Error-Type` response header so a caller can branch without parsing the body. The set is closed at fifteen values: the six request-level buckets `invalid_input`, `content_policy_violation`, `provider_error`, `provider_timeout`, `insufficient_credits` and `model_not_found`, plus the transport-level `unauthorized`, `forbidden`, `concurrency_limit_exceeded`, `client_disconnected`, `internal_error`, `deadline_exceeded`, `not_enabled`, `service_unavailable` and `rate_limited`.

RouterErrorType

Machine-readable Router error category, also sent in the X-Comfy-Error-Type header. Type: string

RouterModelBilling

Billing behavior to check before invoking a model. It does not include prices or usage.

Field	Type	Required	Constraints	Description
`charges_on_policy_rejection`	`RouterChargesOnPolicyRejection`	yes	-	Whether a call this model REFUSES on content-policy grounds is nevertheless charged to the caller. Providers differ, the difference is invisible at call time, and a user who sees an error and a charge for the same call has no way to have known - so it is stated per model, before the call, rather than left to per-provider folklore.

RouterModelDetail

Per-model detail for one Comfy Router model: everything the catalog listing reports for it, plus the per-model fields that only the single-model route carries. Composes RouterModelListEntry, RouterModelDetailFields. Type: object

RouterModelDetailFields

Optional fields returned by the model-details endpoint.

Field	Type	Required	Constraints	Description
`input_schema_url`	string	no	HTTPS URL, e.g. `https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json`, Up to 2048 characters	URL of this model’s OpenAPI document, including its input and output schemas.

RouterModelId

The model ID used in POST /v2/models/{provider}/{model}. Type: string — Model ID, e.g. anthropic/claude-opus-4-6, Up to 193 characters

RouterModelInput

The model input object. Read the selected model’s OpenAPI document for fields and validation. Type: object

RouterModelInputSchemaDocument

A standalone OpenAPI document for one model’s input and output. Type: object

RouterModelListEntry

A model’s ID and billing facts.

Field	Type	Required	Constraints	Description
`id`	`RouterModelId`	yes	Model ID, e.g. `anthropic/claude-opus-4-6`, Up to 193 characters	A canonical Comfy Router model ID, `{provider}/{model}` - exactly the value that addresses the model on `POST /v2/models/{provider}/{model}`, so a caller can interpolate it into that path without re-deriving it from anything. Its `pattern` is `RouterProviderSegment` and `RouterModelSegment` joined by a single `/`, and `maxLength` is their sum plus that separator.
`provider`	`RouterProviderSegment`	yes	Alphanumeric slug, e.g. `anthropic`, Up to 64 characters	Lowercase `provider` segment of the canonical `{provider}/{model}[/{variant}]` model ID - the partner whose model is being addressed. The invocation route’s `provider` path parameter and a catalog entry’s `provider` field both reference this one schema, which is what keeps the listed IDs and the accepted IDs from drifting apart.
`model`	`RouterModelSegment`	yes	Alphanumeric slug, e.g. `claude-opus-4-6`, Up to 128 characters	Lowercase `model` segment of the canonical `{provider}/{model}[/{variant}]` model ID - the model to run within that provider. Shared by the invocation route’s `model` path parameter and a catalog entry’s `model` field, for the same no-drift reason as `RouterProviderSegment`.
`billing`	`RouterModelBilling`	yes	-	Per-model billing FACTS a caller needs before invoking - not prices. Usage and cost figures never appear here.

RouterModelListResponse

One page of the Router model catalog.

Field	Type	Required	Constraints	Description
`data`	array of `RouterModelListEntry`	yes	-	The models on this page, at most `limit` of them.
`has_more`	boolean	yes	-	Whether another page exists beyond this one. Keep walking while this is true; do not infer the end of the catalog from a short or empty `data`.
`next_cursor`	`RouterPageCursor`	no	Opaque cursor returned as `next_cursor`, 1–512 characters	An OPAQUE cursor into a Router list. It is produced by the server and only ever round-tripped: it is not an offset, not a model ID, not ordered, and not stable across catalog rebuilds, so parsing one, incrementing one, or persisting one beyond the walk it came from are all outside the contract. Cursor rather than offset because the catalog is a moving list - an offset walk silently skips or repeats entries when entries are added or removed mid-walk, and a caller cannot tell that it happened.
`limit`	integer	yes	1–100	The page size actually served. A requested `limit` above the maximum is CLAMPED down to the maximum rather than rejected, so this can be smaller than the value asked for - paginate with this number, not with the one you sent, or you will assume rows you never received.

RouterModelOutput

The model result object. Read the selected model’s output schema for its exact shape. Type: object

RouterModelSegment

The model portion of a {provider}/{model} model ID. Type: string — Alphanumeric slug, e.g. claude-opus-4-6, Up to 128 characters

RouterPageCursor

An opaque catalog cursor. Pass it back unchanged as cursor. Type: string — Opaque cursor returned as next_cursor, 1–512 characters

RouterProviderSegment

The provider portion of a {provider}/{model} model ID. Type: string — Alphanumeric slug, e.g. anthropic, Up to 64 characters

RouterValidationErrorContext

Provider-supplied details about the validation rule that failed. Type: object

RouterValidationErrorDetail

One field-level validation failure.

Field	Type	Required	Constraints	Description
`loc`	array of any	yes	-	Path to the offending field, outermost segment first - for example `["body", "image_url"]`, or `["body", "images", 0]` where an integer indexes into an array.
`msg`	string	yes	-	Human-readable description of this single failure.
`type`	string	yes	-	Specific, machine-readable reason for this failure, passed through from the provider unchanged. This is the value a typed SDK exception hierarchy branches on; `error_type` on the response header is only its coarse bucket.
`ctx`	`RouterValidationErrorContext`	no	-	The violated bound for one `RouterValidationErrorDetail`, carried from the provider verbatim - for example `{"limit_value": 8}` alongside `greater_than`, `{"min_width": 512}` alongside `image_too_small`, or `{"max_size_bytes": 10485760}` alongside `file_too_large`. The key set is specific to the provider and the error type, so this is deliberately an open object: narrowing it to a fixed field list, or folding it into the `msg` string, is precisely how a ported integration compiles and then silently loses the branch that read the bound. Absent when the error type carries no bound.
`input`	`RouterValidationErrorInput`	no	-	The offending input value, echoed back verbatim so a caller can see what was rejected without re-deriving it from `loc`. Any JSON type - string, number, boolean, array, object or null - so this schema is deliberately left untyped rather than narrowed to an object. Absent when the provider does not echo the input back.

RouterValidationErrorInput

The rejected input value, when the provider includes it.

RouterValidationErrorResponse

The 422 validation error body. Read X-Comfy-Error-Type for its category.

Field	Type	Required	Constraints	Description
`detail`	array of `RouterValidationErrorDetail`	yes	-	Every validation failure found on the request, one entry per offending field.

Develop with Comfy

Deploy ComfyUI

Run Workflows

Comfy Router

Comfy CLI

Specifications

Comfy Router API reference

Endpoints

`GET /v2/models`

`GET /v2/models/{provider}/{model}`

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

`GET /v2/models/{provider}/{model}/openapi.json`

Error buckets

Request-level buckets

Transport-level buckets

Response headers

Result assets

Per-model input and output schemas

Schemas

RouterChargesOnPolicyRejection

RouterErrorResponse

RouterErrorType

RouterModelBilling

RouterModelDetail

RouterModelDetailFields

RouterModelId

RouterModelInput

RouterModelInputSchemaDocument

RouterModelListEntry

RouterModelListResponse

RouterModelOutput

RouterModelSegment

RouterPageCursor

RouterProviderSegment

RouterValidationErrorContext

RouterValidationErrorDetail

RouterValidationErrorInput

RouterValidationErrorResponse

​Endpoints

​GET /v2/models

​GET /v2/models/{provider}/{model}

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

​GET /v2/models/{provider}/{model}/openapi.json

​Error buckets

​Request-level buckets

​Transport-level buckets

​Response headers

​Result assets

​Per-model input and output schemas

​Schemas

​RouterChargesOnPolicyRejection

​RouterErrorResponse

​RouterErrorType

​RouterModelBilling

​RouterModelDetail

​RouterModelDetailFields

​RouterModelId

​RouterModelInput

​RouterModelInputSchemaDocument

​RouterModelListEntry

​RouterModelListResponse

​RouterModelOutput

​RouterModelSegment

​RouterPageCursor

​RouterProviderSegment

​RouterValidationErrorContext

​RouterValidationErrorDetail

​RouterValidationErrorInput

​RouterValidationErrorResponse

Endpoints

`GET /v2/models`

`GET /v2/models/{provider}/{model}`

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

`GET /v2/models/{provider}/{model}/openapi.json`

Error buckets

Request-level buckets

Transport-level buckets

Response headers

Result assets

Per-model input and output schemas

Schemas

RouterChargesOnPolicyRejection

RouterErrorResponse

RouterErrorType

RouterModelBilling

RouterModelDetail

RouterModelDetailFields

RouterModelId

RouterModelInput

RouterModelInputSchemaDocument

RouterModelListEntry

RouterModelListResponse

RouterModelOutput

RouterModelSegment

RouterPageCursor

RouterProviderSegment

RouterValidationErrorContext

RouterValidationErrorDetail

RouterValidationErrorInput

RouterValidationErrorResponse