ComfyUI-OpenRouter-Simple Introduction
ComfyUI-OpenRouter-Simple adds one node that lets you send a prompt—and, optionally, images, video, or audio—to an OpenRouter model and receive text in your ComfyUI workflow. You can use it to ask questions about visual or audio material, describe a reference image, or turn media context into text for a later step in your graph.
The node is designed to keep model selection and media preparation manageable:
- Its model menu shows text-output models compatible with the kinds of media you have connected.
- It prepares connected media locally to meet size and format limits before sending a request.
- It provides controls for instructions, reasoning, output length, response format, and request timing.
- It treats ComfyUI’s Stop action and timeouts as cancellation, rather than leaving local preparation or an active request running in the background.
This is a text-output node. Images, videos, and audio are context for the model; the node does not generate media. Its outputs are text, compact JSON info, and credits.
How ComfyUI-OpenRouter-Simple Works
Think of the node as a way to hand an assistant both a written question and reference material. You write a user_prompt, optionally add a system_prompt describing how you want it to respond, and connect any media you want it to consider. For example, you might connect a reference image and ask, “Describe its lighting and color palette.”
The node then follows this sequence:
- Find compatible models. It checks OpenRouter’s model information for models that produce text and accept every type of media currently connected. An image and a video require a model that accepts both image and video input. Connecting a second image does not add a new media type.
- Let you choose the model. If your current selection is no longer compatible after you change the connections, the node asks you to choose again. It does not quietly switch to a different paid model.
- Prepare media locally. Connected files are converted or compressed as needed. If any item cannot safely fit the applicable size limit, the node stops before sending the chat request.
- Send the request and return text. Once the inputs are ready, the node sends the prompt and media to OpenRouter. Its request explicitly asks for text output, even when the input contains media.
The same compatibility check runs again when the workflow executes. The model menu helps you choose, but it is not the only safeguard.
ComfyUI-OpenRouter-Simple Features
Prompts, key, and model
| Control | What it does |
|---|---|
system_prompt | Optional overall instruction for the response, such as asking for a concise description or a particular style of analysis. |
user_prompt | The message you want to send, together with any connected media. |
api_key | An optional OpenRouter key. You can enter it in the node or connect a STRING/API Key box. If left blank, the node checks the ComfyUI environment for OPENROUTER_API_KEY, then the older LLM_KEY. An explicitly supplied key takes priority. |
model | Lets you select from live OpenRouter text-output models filtered for your connected input types. |
Protect your key when sharing artwork or workflows. Keys entered directly in the node or supplied through a connected box can appear in saved workflows, generated-media metadata, or ComfyUI error reports. Clear them before sharing those files. Keeping the key in ComfyUI’s environment avoids placing it in graph inputs.
Response controls
| Control | What you can change |
|---|---|
reasoning_effort | Choose auto, none, minimal, low, medium, high, xhigh, or max. The node checks whether the model supports an explicitly requested reasoning level and stops before submission if it does not. |
temperature | Adjust this control when the selected model supports it. The node sends the setting only to models that advertise support. |
max_tokens | Set one total output budget shared by hidden reasoning and the visible answer. A small budget can leave less room for the text you see, especially when reasoning also uses that budget. |
response_format | Choose text or json_object. JSON mode requires a model that advertises structured-output support; otherwise, the node stops before submission. |
zdr | Off by default. When enabled, the node requests OpenRouter provider routing with provider.zdr: true. |
timeout_seconds | Set one deadline covering model-catalog refresh, media preparation, and the chat request. A short deadline may end the workflow before a large video finishes preparing. |
regenerate | On by default, making a fresh request each time you queue the workflow. Turn it off to let ComfyUI reuse the node’s output while the node and all upstream inputs remain unchanged. |
With regenerate=false, changing a prompt, setting, connected media item, or another upstream input causes the node to run again. Reuse comes from ComfyUI’s normal in-memory execution cache, not a separate saved cache; restarting ComfyUI may clear it.
Media inputs and outputs
The optional image*, video*, and audio* inputs grow from one visible socket to up to three per media type, for a maximum of nine connected items. They supply context to the selected model; none becomes an image, video, or audio output.
Before submission, the node prepares each connected item within these limits. Sizes are measured before the media is encoded for the request.
| Input | Prepared format and maximum size | What happens when preparation is needed |
|---|---|---|
| Image | WebP, 1 MB | The node reduces quality first, then dimensions if necessary, while preserving the image’s aspect ratio. |
| Video | MP4 with H.264 video and AAC audio, 10 MB | An already-compatible, untrimmed MP4 under the limit is kept unchanged. Otherwise, the node converts or trims it and may reduce its dimensions; it lowers frame rate only when the available bitrate is unusually small. |
| Audio | MP3, 1 MB | The node chooses a bitrate based on the audio’s duration. |
Up to three items of each type are prepared concurrently. The chat request does not start until every connected item is within its limit. If one item cannot safely meet the limit, preparation stops and the request is not sent.
The outputs are:
text— the model’s written response.info— compact JSON information about the result.credits— credit or key-limit information, depending on which key is available.
An optional OPENROUTER_MANAGEMENT_KEY enables an account-credit lookup. Without it, credits reports the generation key’s remaining limit from OpenRouter’s current-key endpoint and labels it as an API-key limit, not account credit. If that lookup fails after a successful text response, the text response is still returned.
Cancellation and request behavior
The node checks for ComfyUI’s Stop action during network and media-preparation work. It cancels active HTTP work, stops active media-conversion processes, and removes temporary preparation files on success, rejection, timeout, or Stop.
A paid chat request is not automatically retried. This avoids making a second request when it is uncertain whether the first one was charged. Provider errors appear as ComfyUI execution errors, with diagnostic text sanitized to remove secrets and inline media.
ComfyUI-OpenRouter-Simple Models
The extension does not include a fixed set of named models. Its model menu is populated from OpenRouter’s current model information, so available choices can change.
The menu includes models whose output supports text, then narrows them according to your connections:
- Prompt only: a text-output model needs to accept text input.
- Prompt + image: it must accept text and image input.
- Prompt + video + audio: it must accept text, video, and audio input.
If you change the connected media and your selected model no longer qualifies, the selection returns to “choose a compatible OpenRouter model.” This protects you from unknowingly sending a request to a different model.
A compatible media type is not a guarantee that a provider accepts every number of attachments. The node allows up to three items per type, but OpenRouter notes that file-count limits vary by provider and model. If a provider rejects the attachments, the node reports the rejection rather than silently removing items.
When live model information is unavailable, the node can use a previously saved catalog and mark it as stale. If neither live nor saved information exists, it stops instead of guessing which model can accept your media.
Troubleshooting ComfyUI-OpenRouter-Simple
| What you see | What to try |
|---|---|
| The model selection returns to “choose a compatible OpenRouter model.” | Check which image, video, and audio cables are connected, then select a model from the updated menu. Your earlier choice may not accept the new combination. |
| No suitable model appears. | Check whether you have connected a media type you do not need. A model must accept every connected type and produce text. If model information cannot be retrieved and no saved catalog exists, wait until it is available rather than assuming a model is compatible. |
| A media item fails before a response is generated. | Check the failing input against the prepared limits: 1 MB for an image, 10 MB for a video, or 1 MB for audio. Try a shorter or smaller source item, then queue the workflow again. The paid chat request does not begin when local preparation fails. |
| Video or audio preparation does not work. | These inputs require ffmpeg and ffprobe to be available to ComfyUI. Check that your ComfyUI environment can access them. |
| The workflow times out. | Increase timeout_seconds, particularly when working with media that takes time to prepare. The same deadline covers catalog work, preparation, and the chat request. |
| A reasoning or JSON setting is rejected before submission. | Choose a model that supports the requested option, or change reasoning_effort or response_format. The node checks explicit reasoning and JSON support before sending the chat request. |
| OpenRouter rejects a request even though the model appeared compatible. | Read the sanitized ComfyUI error. Model compatibility checks media types, while provider-specific attachment-count rules may still reject the number of files supplied. Try fewer attachments. |
credits does not show account credit. | Without OPENROUTER_MANAGEMENT_KEY, it shows the generation key’s remaining API-key limit instead. A credit-lookup failure does not discard a successful text completion. |
Frequently asked questions
Can this node create an image, video, or audio clip?
No. It accepts those media types as context but requests and returns text only.
Will it pick another model for me if I connect a new media type?
No. If your selected model becomes incompatible, you must choose a compatible model yourself.
Does turning off regenerate permanently save responses?
No. It uses ComfyUI’s normal in-memory cache while the node and its upstream inputs remain unchanged. A restart may clear the reusable result.
Does the three-per-type limit mean every model accepts three files?
No. It limits the node’s inputs, but providers and models can impose their own attachment-count limits.
What does Stop do while the node is working?
The node cancels active network work and media preparation, cleans up temporary files, and reports the workflow as interrupted through ComfyUI.
Learn More about ComfyUI-OpenRouter-Simple
- Extension source and README on GitHub — the author’s project page for the node.
- OpenRouter image understanding (https://openrouter.ai/docs/guides/overview/multimodal/image-understanding), video inputs (https://openrouter.ai/docs/guides/overview/multimodal/videos), and audio inputs (https://openrouter.ai/docs/guides/overview/multimodal/audio) — useful when deciding what reference material to connect.
- OpenRouter model information (https://openrouter.ai/docs/api/api-reference/models/list-all-models-and-their-properties) — explains the model properties used for compatibility filtering.
- Reasoning controls (https://openrouter.ai/docs/guides/best-practices/reasoning-tokens) and provider routing and ZDR (https://openrouter.ai/docs/guides/routing/provider-selection) — background for two of the node’s more specialized settings.
- OpenRouter chat completions (https://openrouter.ai/docs/api/api-reference/chat/create-a-chat-completion) — details of the request behind the node’s text responses.
