ComfyUI-OpenRouter-Studio

<p align="center"> <img src="assets/banner.svg" alt="OpenRouter Studio — image and video generation for ComfyUI" width="100%"> </p>

ComfyUI OpenRouter Studio

A catalogue-driven OpenRouter image and video production suite for ComfyUI. Install it, restart ComfyUI, and paste one OpenRouter API key into the first-run connection screen. Every supported model then gets controls that follow its published capabilities instead of a single lowest-common-denominator form.

OpenRouter Studio is an independent community integration. It is not affiliated with or endorsed by OpenRouter or Comfy Org.

OpenRouter Studio is designed for real production work: credentials never enter the workflow, video task IDs are recorded before polling, and interrupted video jobs can be resumed without submitting a duplicate generation.

Highlights

• Easy Studio Mode. A focused image/video workspace puts prompt, references, format, model choice, and Create in one place; Open in Canvas keeps the full model-specific node editable without generating.
• Visual model and recipe discovery. Search the live catalogue by media, speed, pricing availability, resolution, duration, native audio, or reference support; save favorites, reuse recents, or let the deterministic Auto rule choose a compatible model.
• Production continuity. Packaged product, character, image-to-video, first/last-frame, storyboard, and social-format recipes become real editable Comfy subgraphs. The Job & Asset Center adds visual history, reusable assets, resume actions, and canvas drag/drop.
• Image and video in one coherent pack. Image responses become native ComfyUI IMAGE and MASK batches; completed videos become native ComfyUI VIDEO values with a poster frame.
• Live catalogue, offline-safe. At startup the pack merges OpenRouter's live media catalogue with a bundled snapshot. The current snapshot, captured 2026-08-03, contains 38 image models and 20 video models.
• Model-specific controls. Resolution, aspect ratio, duration, audio, seed, reference limits, output format, quality, background, compression, and provider passthrough fields appear only where relevant.
• Serious reference support. Images can be used as image-generation references or video first/last frames. Models whose declared input architecture supports them can also accept image, video, and audio references.
• Reference Inspector with honest evidence. Open Inspect refs on a Studio job to compare an available local reference with the result and review locally recorded attachment, request-encoding, and OpenRouter-response evidence. It cannot prove that a model used a reference or measure its influence.
• Provider-aware routing. A specific OpenRouter provider endpoint can be selected while preserving the distinction between routing tags and provider-option slugs.
• Safe advanced mode. Friendly typed controls cover documented special parameters. A raw JSON escape hatch remains available, with strict allowlist validation enabled by default.
• Native vector preservation. SVG outputs, including Recraft vector results, are saved as raw .svg artifacts and rasterized with resvg-py for ComfyUI preview.
• Durable job history. A private SQLite ledger stores local and provider job IDs, prompt and request hashes, status, output path, and estimated/actual cost when available. Prompt text and embedded reference bytes are not written to the ledger.

Video model spotlight

| OpenRouter model | What the catalogue exposes | |---|---| | minimax/hailuo-3 | MiniMax H3 (not Higgsfield): 2K, 5–15 seconds, six aspect ratios, first/last frames, multimodal references, native audio, and aigc_watermark provider control. | | bytedance/seedance-2.0 | 480p through 4K, 4–15 seconds, seven aspect ratios, first/last frames, image/video/audio references, generated audio, seed, watermark, and request-key controls. | | bytedance/seedance-2.0-fast | Seedance 2 Fast: the same reference-oriented workflow at 480p or 720p, with its own lower published video-token price. |

The catalogue also drives all other currently advertised OpenRouter image and video models. Availability, prices, capabilities, and provider endpoints can change upstream; refresh the catalogue before making an important production decision.

Installation

You need only ComfyUI and one OpenRouter API key. No key belongs in a workflow, config node, or command.

OpenRouter Studio requires ComfyUI 0.28.0 or newer. Manager will show the compatibility requirement before installation.

ComfyUI Manager — recommended

1. Open Manager in ComfyUI.
2. Search node packs for OpenRouter Studio and select Install.
3. Restart ComfyUI. The “One key. The whole studio.” screen opens automatically.
4. Paste your own OpenRouter key and select Connect OpenRouter.

That is all; no model downloads are required. Manager also handles future updates. If the first-run screen is dismissed, use Add your API key at the bottom-right of ComfyUI or right-click any OpenRouter Studio node and choose Set up OpenRouter API key.

Release ZIP — no Git required

1. Download and unzip the latest GitHub release anywhere.

2. Double-click the installer for your computer:

   • macOS: setup_mac.command
   • Windows: setup_windows.bat

   The installer finds common Desktop, portable, and source-checkout locations, uses ComfyUI's own Python, installs the pack safely, and pauses so you can read the result. It does not ask for or receive your key. On Windows Portable and common ComfyUI Desktop layouts, the launcher can use ComfyUI's bundled Python even when system Python is not installed.

3. Restart ComfyUI. The “One key. The whole studio.” screen opens automatically. Paste the key and select Connect OpenRouter.

That is the complete local setup. Select Open Studio at the bottom-right of ComfyUI for the beginner workspace, or add one of the five nodes under OpenRouter Studio. If you dismiss the first-run screen, use the persistent Add your API key button. You can also right-click any OpenRouter Studio node and choose Set up OpenRouter API key.

Terminal fallback

The terminal wizard is included in the GitHub release ZIP and source repository, but not in the lean Comfy Registry/Manager archive. Manager users normally need only the local first-run connection screen. From an extracted release ZIP or clone, open a terminal in that folder and run:

python3 scripts/quick_setup.py

On Windows, use py scripts\quick_setup.py. This terminal version can also request the key with hidden input; pasted characters intentionally do not appear on screen.

The wizard submits no generation and never prints the API key. It will not overwrite a conflicting custom_nodes/ComfyUI-OpenRouter-Studio directory. If automatic discovery chooses the wrong installation, specify it explicitly:

python3 scripts/quick_setup.py --comfy-root /path/to/ComfyUI

Useful safety and automation options include --dry-run, --skip-key, --skip-dependencies, --python /path/to/python, --user-dir /path/to/user, and --install-method symlink. See them all with python3 scripts/quick_setup.py --help.

Updating

Manager users can select Update on the OpenRouter Studio node pack. The ZIP installer deliberately does not overwrite an existing node folder. Manual-install users should read the release notes, back up or rename the old folder, install the new release, and restart ComfyUI. Credentials and the video-job ledger live in ComfyUI's user directory rather than the node folder, but keeping an ordinary backup is still recommended.

Manual install

Clone or copy the repository to <ComfyUI>/custom_nodes/ComfyUI-OpenRouter-Studio, install requirements.txt with the same Python executable that launches ComfyUI, and restart. Use the local first-run screen, or run python3 scripts/quick_setup.py --skip-dependencies for terminal-only key setup. Never replace an existing directory without inspecting it first.

Configure or share your OpenRouter key

The double-click installers leave the key for ComfyUI's local first-run screen. In a GitHub release ZIP or clone, the terminal wizard asks for it automatically when no key is configured. To configure only the credential later from one of those source folders, rerun the wizard without reinstalling dependencies:

python3 scripts/quick_setup.py --skip-dependencies

Alternatively, set OPENROUTER_API_KEY in the environment that starts ComfyUI. The environment variable has priority over the stored file.

If another trusted local tool already owns a mode-0600 OpenRouter key file, reference it without copying the secret:

python3 scripts/quick_setup.py --skip-dependencies \
  --shared-key-file /absolute/path/to/existing-openrouter-key

The setup command validates file type, ownership, permissions, and size using metadata, then stores only the absolute path. Studio reads the protected file when checking credential status or authenticating a request. Symlinks and group/world-readable files are rejected.

Never paste an API key into a node widget, prompt, workflow JSON, screenshot, or bug report. When Studio stores a key or shared-file reference, its private configuration is located at:

<ComfyUI user directory>/__openrouter_studio/credentials.json

On macOS and Linux the pack refuses to read that file if group or other users have access. Repair its permissions with chmod 600 <path>.

Optional environment variables:

| Variable | Purpose | |---|---| | OPENROUTER_APP_TITLE | Attribution title sent to OpenRouter; defaults to ComfyUI OpenRouter Studio. | | OPENROUTER_APP_REFERER | Optional attribution URL sent as HTTP-Referer. | | OPENROUTER_STUDIO_DATA_DIR | Overrides the private data directory for credentials, catalogue cache, and ledger. | | OPENROUTER_STUDIO_OFFLINE=1 | Skips live catalogue fetches and uses cache/snapshot data. Generation still needs network access. |

Studio Mode — recommended

1. Select Open Studio, choose Image or Video, and write the creative direction.
2. Keep Auto — best fit, or open the visual Model Explorer. Add references from the Asset Center and choose only the format controls the selected catalogue model advertises.
3. Select Create to queue only the new Studio output branch. Select Open in Canvas to add the configured node, references, and preview/save sink without generating.

The Techniques page builds complete editable subgraphs for product photos, character sheets, image-to-video, first/last-frame animation, six-beat storyboards, and social variants. A technique may contain several generation nodes; Studio shows the node/output count before Create.

Completed jobs and reusable images appear in the Job & Asset Center with previews, cost/status metadata, resume actions, and Open in Canvas. Saved assets are local to that ComfyUI profile and can be dragged onto the graph.

The non-destructive image workspace supports crops, layers, opacity, composition, outpaint canvas expansion, and painted inpaint/removal masks. Each save creates a new asset branch and preserves the source. OpenRouter's dedicated Image API currently advertises reference images but no explicit mask parameter, so Save & Canvas exposes native IMAGE and MASK outputs for a real ComfyUI inpaint workflow; Studio does not pretend a reference-only request is mask-accurate.

Reference images and prompts

A reference image is visual context; it does not replace the required text prompt. Connect one source image once, starting at reference_1, then describe what the model should preserve and what it should change.

References are ordered. reference_1 is the first reference image, reference_2 is the second, and so on. OpenRouter sends that order through input_references[]; there is no provider-side reference ID that must be typed into the prompt. The most portable wording is ordinary language:

Keep the identity, face, and clothing from the first reference image. Place the character in a snowy forest at blue hour, medium portrait, soft rim light. Do not change age, hairstyle, or costume colors.

For multiple inputs, give every image one explicit job:

Use the person from the first reference image as the subject and the second reference image only as the lighting and color reference. Preserve the subject's identity and clothing; do not copy objects from the style image.

OpenRouter Studio also accepts @image_ref1, @image_ref2, and higher numbered shortcuts in image prompts. These are local conveniences, not OpenRouter syntax: the node expands them into “the first reference image,” “the second reference image,” and so on before submission. An out-of-range shortcut is rejected before a request is sent, and exact duplicate references are uploaded only once.

For video, keep all selected images in Auto/general guidance roles, or use only explicit First frame and Last frame roles. Studio blocks a mixed frame-plus-guidance request because providers may ignore one of those two modes; the dedicated first-frame and first-to-last Techniques configure the frame roles automatically.

For reliable reference edits, state (1) each reference's role, (2) the details that must stay unchanged, (3) the requested change, and (4) composition, camera, lighting, or output constraints. This follows the ordered-image patterns in the official OpenRouter image API, Gemini image-generation guide, and OpenAI image guide.

Reference Inspector

Jobs that contain references show Inspect refs in the Job & Asset Center. The inspector provides a before/after view when the local source asset and generated result are still available, plus a three-step local trail: assets attached in Studio, unique references encoded into the redacted request summary, and whether a definitive OpenRouter response was recorded.

This evidence is deliberately conservative. It does not expose prompts, reference URLs, hashes, or embedded media, and it cannot prove that OpenRouter decoded every reference or that the selected model used it. If the provider response is unknown, check OpenRouter activity before retrying to avoid a possible duplicate generation.

Advanced nodes

• OpenRouter Studio · Image — catalogue-driven image generation and reference editing.
• OpenRouter Studio · Video — text/image/video/audio-guided video generation.
• OpenRouter Studio · Resume Video — continue polling an existing task without resubmitting it.
• OpenRouter Studio · Asset — load a Studio image plus its saved/alpha-derived mask into the graph.
• OpenRouter Studio · Status — inspect credential, catalogue, and credit status without generating.

Select the model first on generation nodes; its panel repopulates with the normalized and provider-specific options known for that model. Leave a control at provider default unless you need to override it.

Billing and retry semantics

Image generation is synchronous; video generation is an asynchronous task. OpenRouter Studio deliberately does not retry either generation POST, because OpenRouter does not document an idempotency contract for these endpoints and an automatic retry could create a duplicate result.

Read-only status polling and completed-media downloads use bounded retries for transient failures. Cost shown before generation is an estimate from current catalogue SKUs, not a quote; provider billing remains authoritative.

For video:

• The provider job ID is committed to the local ledger immediately after OpenRouter accepts the task.
• Cancelling or interrupting ComfyUI stops local polling only. OpenRouter currently publishes no remote video-cancel endpoint, so the remote task may continue and may still be billed.
• Use the resume/fetch node with either the local job ID or OpenRouter provider job ID. It polls and downloads the existing task; it does not resubmit generation.
• If the original submission fails before OpenRouter returns a definitive response, the ledger marks it as an ambiguous submission instead of silently retrying.

See Security and recovery before running long or expensive jobs.

Catalogue and special parameters

The normalized OpenRouter fields are rendered as typed controls. Provider passthrough controls are added from each selected endpoint's live allowlist. Examples include:

• FLUX steps, guidance, and safety tolerance
• Krea creativity, intensity, complexity, movement, styles, and moodboards
• Recraft style, controls, and text layout
• OpenAI moderation
• Gemini cached content
• Kling negative prompt and CFG scale
• MiniMax prompt optimizer and fast pretreatment
• Runway content moderation and keyframes
• Seedance watermark and request key
• Google Veo person generation, negative prompt, conditioning scale, and prompt enhancement

OpenRouter's image and video provider-option envelopes differ. The pack handles that distinction for you. See Catalogue and parameters for the routing model, validation policy, and snapshot refresh workflow.

Outputs and local state

Generated artifacts are stored under:

<ComfyUI output directory>/openrouter_studio/

Private operational state is stored under:

<ComfyUI user directory>/__openrouter_studio/
├── catalog_cache.json
├── credentials.json
├── jobs.sqlite3
├── studio_assets.sqlite3
└── studio_assets/

Raw generated files are retained where possible. Raster results can be batched even when their dimensions differ: each image is placed at the top-left of a transparent canvas matching the largest result, and the corresponding alpha-derived mask marks transparent padding.

Privacy notes

• Workflows contain model settings and prompts, but never the API key managed by this pack.
• The ledger stores hashes and redacted summaries, not raw prompts or base64 reference payloads.
• Studio assets and masks remain in the owner-private ComfyUI user directory and are served only to the same-origin loopback Studio page.
• Reference media is encoded locally and sent to OpenRouter when the corresponding generation node is queued.
• OpenRouter's video-generation guide states that video generation is not Zero Data Retention eligible. Apply your own privacy and rights policy before uploading people, client material, or confidential assets.

Troubleshooting

The nodes do not appear. Check ComfyUI's startup log, confirm the symlink/copy is inside the active custom_nodes directory, install dependencies with ComfyUI's own Python, and restart.

The wizard found the wrong ComfyUI. Re-run it with --comfy-root /exact/path/to/ComfyUI. If your launcher uses a nonstandard user directory, add --user-dir /exact/path/to/user.

Windows says python is not recognized. Try py scripts\quick_setup.py. For a portable install, you can also launch the script with its bundled python_embeded\python.exe.

The credential file is “too permissive.” Run chmod 600 on the exact path in the error message. Do not work around this by moving the key into a workflow.

A model or option is missing. Right-click any OpenRouter Studio node and choose Refresh OpenRouter catalogue. If OpenRouter is temporarily unavailable, the pack intentionally falls back to its last cache and then its bundled snapshot; the UI should report which source is active.

An SVG generated but preview failed. The raw SVG should still be in the output directory. Re-run Quick Setup with --skip-key, then restart ComfyUI.

ComfyUI was interrupted while polling a video. Resume by job ID. Do not queue a second generation unless you have checked that the first provider task failed definitively.

Refresh the bundled snapshot

Maintainers can capture current models, endpoint metadata, provider tags/slugs, passthrough allowlists, and video input architectures from the repository root with:

/path/to/comfy-python scripts/update_catalog.py

This is a read-only catalogue operation; it does not submit a generation. Review the resulting diff because upstream model capabilities and pricing are mutable.

Design documents

• Catalogue and parameters
• Security, billing, and recovery
• Example workflow recipes
• Comfy Registry release checklist

Upstream documentation

• OpenRouter image generation
• OpenRouter video generation
• OpenRouter provider-specific video options
• ComfyUI V3 custom-node migration

License

MIT. See LICENSE.

OpenRouter, ComfyUI, and model/provider names belong to their respective owners.