Comfy Router API reference

Every Comfy Router endpoint, parameter, response body and error bucket, generated from the Comfy API contract.

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.