OpenRouter Gateway

One API key. Every modality. Image generation, text-to-speech, transcription, video generation, and embeddings for Agent Zero — all through your OpenRouter account.

What it does

Agent Zero's chat models already work with OpenRouter out of the box. But OpenRouter offers much more than chat — and those endpoints are not OpenAI-compatible, so the framework cannot reach them. This plugin closes that gap:

Chat/LLM models stay where they are: Settings → Models with the built-in openrouter provider. This plugin never touches them.

Quick start

1. API key: Create a key at openrouter.ai/keys and store it in Agent Zero's secret API_KEY_OPENROUTER (Settings → Secrets). Alternatively paste it directly into the plugin settings.
2. Open the settings: Settings → Agent → OpenRouter Gateway.
3. Pick your default models: Every model field suggests live entries from the OpenRouter catalog as you type — no need to look up model ids. Only configure what you plan to use; everything else can stay empty.

That's it. Now just ask your agent:

"Generate an image of a lighthouse at dawn" "Read this text aloud" "Transcribe /a0/usr/workdir/meeting.mp3" "Make a short video of a paper boat in the rain"

Tools in detail

Image generation — openrouter_image

{
  "tool_name": "openrouter_image",
  "tool_args": {
    "prompt": "A cinematic robot painter in Berlin",
    "size": "1792x1024"
  }
}

• size maps to the closest supported aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)
• Images appear directly in the chat
• Image-to-image: add "reference_images": ["/path/to/photo.jpg"] (local paths or URLs) to transform existing images — e.g. "make this photo a watercolor painting"

Text-to-speech — openrouter_tts

{
  "tool_name": "openrouter_tts",
  "tool_args": { "text": "Hello world", "format": "mp3" }
}

Saves an MP3 (or raw PCM) and returns its path. Uses your default TTS model and voice from the settings; both can be overridden per call.

Transcription — openrouter_transcribe

{
  "tool_name": "openrouter_transcribe",
  "tool_args": { "path": "/a0/usr/workdir/meeting.mp3", "language": "de" }
}

Supports wav, mp3, flac, m4a, ogg, webm, aac. Audio is sent base64-encoded — remote URLs must be downloaded first. Returns the text plus duration/cost.

Video generation — openrouter_video

{
  "tool_name": "openrouter_video",
  "tool_args": {
    "prompt": "A paper boat sailing down a rainy street gutter, cinematic",
    "resolution": "480p",
    "duration": 4
  }
}

Video generation is asynchronous: the tool submits a job, polls until it finishes (typically 1–5 minutes), and saves the MP4. If it times out (video_poll_timeout, default 600s), the job id is reported — the job usually still completes; just ask the agent to check that job id instead of generating again (you'd pay twice).

💡 Video is the most expensive modality — a short 480p clip costs roughly $0.10–0.30 depending on the model.

Embeddings — openrouter_embeddings

{
  "tool_name": "openrouter_embeddings",
  "tool_args": {
    "inputs": ["first text", "/a0/usr/workdir/photo.jpg"],
    "model": "openai/text-embedding-3-small"
  }
}

For similarity search, clustering, deduplication, and image search. Texts embed directly; image paths become multimodal inputs (requires a multimodal embedding model). Vectors are written to a JSON file — the chat only shows count, dimensions, and cost.

Model discovery — openrouter_models

{
  "tool_name": "openrouter_models",
  "tool_args": { "query": "video", "limit": 10 }
}

Searches the live OpenRouter catalog by id or name — useful to find model ids for any of the tools above.

Voice output: let Agent Zero speak with an OpenRouter voice

Once you set a Default TTS model in the plugin settings, the plugin registers itself as a voice provider for Agent Zero's built-in read-aloud feature — the 🔊 button on chat messages then speaks through OpenRouter.

• Pick a model and voice in the settings; the ▶ Preview button plays a short sample so you can choose by ear
• The voice dropdown loads the actual voices supported by your selected model — always current
• A status card appears under Settings → Voice
• No TTS model configured? The plugin stays out of the way and voice output falls back to Kokoro/browser TTS

Settings reference

All model fields auto-suggest live from the OpenRouter catalog — start typing and pick.

Provider routing (optional)

Control how OpenRouter routes your requests across its providers — applies to all tools:

Leave everything empty to let OpenRouter decide (recommended to start with).

Troubleshooting

Automatic cost tracking

When the LLM Cost Tracker plugin is also installed and active, usage and costs from all OpenRouter Gateway tools are automatically captured — no configuration needed.

The integration is fail-open: if the Cost Tracker is disabled or not installed, the OpenRouter Gateway works normally with zero overhead. When both are active, OpenRouter costs appear in the Cost Tracker dashboard alongside your chat model costs.

To see OpenRouter costs in the dashboard, add pricing rules with provider_class: "openrouter" in the Cost Tracker settings, or rely on provider-reported costs when OpenRouter includes them in responses.

Pricing note

All usage is billed by OpenRouter at provider list prices (no markup). Rough orders of magnitude: embeddings are fractions of a cent, images and TTS cents, video tens of cents per clip. Failed requests are not billed.