Skip to main content
Comfy Router gives you one API for hosted image and video models at https://api.comfy.org. Create an API key in your Comfy workspace, then call any model with the official Python and TypeScript SDKs or over plain HTTP. Billing is pay per use: by default each request draws credits from your workspace balance, with no subscription. See Router pricing for rates and other billing options.
Tracking spend with LiteLLM? Router reports a synchronous run’s USD cost in the header LiteLLM reads, so you don’t maintain a price table. See Using Comfy Router with LiteLLM.
1

Create an API key

Create a key in your Comfy workspace. In a Bash-compatible terminal, set:
Keep API keys on your server or in your local environment. These examples are for a terminal or server, not browser JavaScript.Router charges credits per request. If your workspace has no credit balance, the first live call returns 402 with error_type: insufficient_credits. This check runs before body validation, so an unfunded workspace can return 402 even for an invalid request. Add credits at workspace billing before debugging the request body.
2

Queue a request

Choose your language and run the example. Generation can take a few minutes.
Each SDK submit call creates an idempotency key and reuses it for automatic retries. The cURL example creates one with uuidgen. If it is unavailable, use another UUID generator. For status, cancellation, and collection details, see Queued delivery.

Image-to-video and reference-to-video

The same Seedance request takes image, video, and audio inputs. Add items to content and set each one’s role. The roles you send decide the operation Router runs. Pricing follows the media kinds in content, not the roles: a request with any video input bills as video-to-video, otherwise one with any image bills as image-to-video, and a text-only request bills as text-to-video. Some models charge the same rate for text-to-video and image-to-video. An image url can be a public URL or a data:image/<format>;base64,<content> string. Submit, poll, and collect exactly as in the quickstart above. Only the body changes.
Image-to-video
Reference-to-video
On Seedance 2.5, first-frame and first-and-last-frame requests take the output aspect ratio from the first frame. Leave ratio out or send adaptive, because a concrete ratio is refused with a 400. The request schema is shared across the Seedance family and can list roles a model ignores, so check the x-comfy-router-input-modalities field in each model’s input schema for the input kinds that model accepts. For example, reference_video and reference_audio need a model that lists video or audio there.

Edit or extend a reference video

On Seedance 2.5, omni_reference_task_type tells the model what to do with the reference media: reference makes a new video guided by it, edit changes a reference_video clip, and extend continues one. Without the field the model picks the task from the prompt, and an edit keeps the clip’s own length and aspect ratio and ignores duration and ratio. On the native BytePlus leg, an explicit value that does not fit the request is refused before generation starts, so it is not billed. An alternate provider leg, used on fallback or picked with model_provider, has no task-type field: it drops the value and lets that provider infer the task as if the field were left out. The drop is disclosed in X-Comfy-Router-Dropped-Params, on a synchronous run route response and on the queued submit’s 201. The queued route has no fallback, so it reaches an alternate leg only through model_provider.
Edit a reference video
An edit keeps the source clip’s length, so send "duration": -1 and leave ratio out. An extend request returns only the newly generated segment, of the duration you send.

Next steps

Browse models

Explore available models and find model-specific request examples.

Using the Router API

Learn about model discovery, schemas, queued requests, errors, and billing.