ai-media-router

<h1 align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-wordmark-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-wordmark-light.svg"> <img alt="AI Media Router" src="docs/assets/logo-wordmark-light.svg" width="430"> </picture> </h1> <p align="center"> <strong>One MCP server for AI image and video generation across 40+ providers, with your own keys and a local library that remembers everything.</strong> </p> <p align="center"> <a href="https://github.com/jutsuhq/ai-media-router/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/jutsuhq/ai-media-router/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/jutsuhq/ai-media-router/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/jutsuhq/ai-media-router?sort=semver"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> <a href="https://modelcontextprotocol.io"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-14B8A6.svg"></a> </p>

AI Media Router is an open-source MCP server that lets Claude, Cursor, Codex or any MCP client generate images and videos with Seedance, Kling, Veo, Wan, FLUX, GPT Image, Nano Banana, Seedream and more, through 43 providers: fal, Replicate, kie, Runware, WaveSpeed, OpenRouter, BytePlus and 35 others, or your own ComfyUI server. The agent compares prices across providers before it spends, pays each one with your own key, and gets every result back as a local file it can search, review, reuse as a reference and chain into the next shot. Self-hosted, a single Rust binary, MIT.

For example, on November 1, 2026 the price catalog listed Seedance 2.5 text-to-video at 720p with audio from $0.216 a second (302.AI) to $0.462 (fal) among the providers the router can call: the same 10-second clip for $2.16 or $4.62. search_prices shows the agent that spread before it picks.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/architecture-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/assets/architecture-light.svg"> <img alt="How it works: 1. your AI agent asks for an image or video with one tool call; 2. the router checks price and budget, fills in references and submits to one of 43 providers with your key; 3. the result comes back; 4. it is saved in your local library and the agent gets a local file path. Your keys, no middleman, budgets before spending, nothing gets lost." src="docs/assets/architecture-light.svg" width="100%"> </picture> </p>

Contents:

• Why
• Supported providers
• Compared with other ways to generate from an agent
• Quick start
• How a generation works
• The five pillars
• Production pipelines
• Placeholders
• Costs and budgets
• Checks before spending
• When a job fails
• Interface
• Fixing a provider whose API changed
• Architecture
• Testing
• FAQ

Why

| Without it | With AI Media Router | |---|---| | Every provider has its own API, auth, polling and output format | One generate → get_job loop for all 43; providers are TOML files | | Result URLs expire after hours or days | Every output is downloaded at once, content-hashed, indexed, previewed | | The agent forgets what it made last week | Full-text and similarity search, history, lineage graph, per-model stats | | A character or product drifts between shots | Named references fed into every generation with {{ref:name}} | | "$5 budget" is a promise in a prompt | Budgets refuse a job before it is submitted, from real price estimates | | An API change breaks the integration until a release | The agent reads the raw exchange, fixes the spec, saves it live |

Principles: bring your own keys (no middleman account), the agent chooses provider and price (no hidden routing), model and input pass through unchanged (no lagging unified schema). Details are in docs/concept.md.

Supported providers

43 built-in provider specs, each a TOML file in providers/ with recorded fixtures. ai-media-router providers lists them with the env vars each one still needs.

| Kind | Providers (key) | |---|---| | Inference platforms and API aggregators | fal.ai (fal), Replicate (replicate), Runware (runware), WaveSpeedAI (wavespeed), kie.ai (kie), OpenRouter (openrouter), Vercel AI Gateway (vercel), Together AI (together), DeepInfra (deepinfra), Novita AI (novita), SiliconFlow (siliconflow), Segmind (segmind), Atlas Cloud (atlascloud), each::labs (eachlabs), AI/ML API (aimlapi), 302.AI (ai302), APIMart (apimart), CometAPI (cometapi), EvoLink (evolink), PiAPI (piapi), ModelsLab (modelslab), Makernice (makernice), Pollo AI (pollo), Sume (sume), Unifically (unifically), Yir (yir), Higgsfield (higgsfield), Comfy Router partner models (comfy) | | Model makers' own APIs | BytePlus ModelArk (byteplus) and Volcengine Ark (volcengine) for Seedance and Seedream, Kling (kling), Gemini API (gemini) for Veo and Nano Banana, Google Vertex AI (vertex) for Veo, Imagen and Nano Banana, Alibaba Cloud Model Studio (alibaba, alibaba-cn) for Wan, MiniMax Hailuo (minimax), Runway (runway), Luma (luma), LTX (ltx), PixVerse (pixverse), Vidu (vidu), xAI Grok Imagine (xai) | | Self-hosted | ComfyUI (comfyui): your own server or a rented GPU, any workflow in API format, 0 USD per job |

Models are not a fixed list: model goes to the provider as written, so a model a provider adds today works today. get_provider shows the model id format and an example call. Specs not yet checked against a live response say so in their notes; live verification of every spec is on the roadmap.

Compared with other ways to generate from an agent

| | One provider's own MCP server (for example fal's or Replicate's) | A local ComfyUI | AI Media Router | |---|---|---|---| | Providers | That one | Models you run yourself | 43 providers, plus your ComfyUI as one of them | | Price comparison | Its own prices | Free per job, your GPU | Catalog prices across providers, before the agent picks | | Spending limit | Whatever that provider offers | Not needed | Named USD budgets that refuse a job before it is sent | | Where results end up | That provider's storage or URLs | Your ComfyUI output folder | A local library: search, ratings, references, lineage | | Account | That provider's | None | None of ours: your keys go straight to each provider |

AI Media Router is not a hosted gateway like OpenRouter: there is no account, no balance and no markup, and OpenRouter itself is one of the providers it calls. It does not route to the cheapest provider by itself either; it shows prices and the agent or you choose.

Quick start

1. Install. Prebuilt binaries for Linux (x86_64, arm64), macOS (Apple silicon, Intel) and Windows (x86_64) are on the releases page. You can also build from source with Rust 1.89 or later:

cargo install --git https://github.com/jutsuhq/ai-media-router

Or run the container (stdio MCP; /data holds the library):

docker run -i --rm -v ai-media-router:/data -e KIE_API_KEY ghcr.io/jutsuhq/ai-media-router

2. Add keys in a terminal. The value is read from a hidden prompt, or from stdin, and never passes through an agent or a tool call:

ai-media-router keys set KIE_API_KEY
pbpaste | ai-media-router keys set FAL_KEY

On Windows there is no hidden prompt: pipe the value in (Get-Clipboard | ai-media-router keys set FAL_KEY).

--store auto (the default) keeps the secret in the OS keychain (macOS keychain, Linux Secret Service via secret-tool) when one is available, else in <home>/config.toml under [env], written atomically with mode 0600; --store keychain or --store file forces one. In config.toml a keychain-held key appears as FAL_KEY = "keychain:ai-media-router/<id>", with no secret in the file. The process environment still overrides both, and keys apply without a restart.

ai-media-router keys list shows every key variable, which providers use it, whether it is set, its source (environment, keychain or config file), its last four characters and the exact keys set command. ai-media-router keys test kie makes a free auth check where its spec defines auth_check: accepted, refused, inconclusive, not_supported or not_configured. ai-media-router keys remove FAL_KEY deletes a key.

<home> is set by --home or AI_MEDIA_ROUTER_HOME. By default it is the OS data dir: ~/Library/Application Support/jutsu.ai-media-router on macOS, %APPDATA%\jutsu\ai-media-router\data on Windows, ~/.local/share/ai-media-router on Linux. ai-media-router providers lists every provider and the env vars it still needs.

3. Connect an agent. For Claude Code:

claude mcp add ai-media-router -- ai-media-router mcp

For Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and other clients that take an mcpServers block, use the binary's full path, since these apps may not see your shell's PATH:

{
  "mcpServers": {
    "ai-media-router": {
      "command": "/usr/local/bin/ai-media-router",
      "args": ["mcp"]
    }
  }
}

Then ask the agent something like "find the cheapest Seedance 2.5 offer at 720p among my providers and make a 5-second clip of a paper boat on a rainy street".

| Mode | Command | |---|---| | MCP over stdio (one process per agent session) | ai-media-router mcp | | HTTP: REST /v1/* and MCP /mcp | ai-media-router serve --bind 127.0.0.1:8787 | | CLI | ai-media-router prices seedance --res 1080p, generate, jobs, assets, … (--help) |

serve refuses a non-loopback address unless AI_MEDIA_ROUTER_TOKEN is set. Then every request needs Authorization: Bearer <token>, and save_spec / reset_spec stay disabled unless --allow-spec-writes is given.

4. Save a preset. A preset is a saved single generation; --input merges over its input field by field:

ai-media-router recipes save video-draft --provider fal --model <model> --input '{"prompt": "…"}' --budget ad
ai-media-router generate --recipe video-draft --input '{"prompt": "a bottle on wet stone"}'

The preset supplies provider, model, input, save_to, offer and budget; fields given in the call win. ai-media-router recipes list shows the presets.

Optional extras:

| Install / set | Unlocks | |---|---| | COMFYUI_URL (e.g. http://127.0.0.1:8188), optional COMFYUI_TOKEN | Your own ComfyUI server as provider comfyui: input is the API-format workflow, {{asset:…}} in a LoadImage node uploads the file, jobs cost 0 USD | | ffmpeg and ffprobe on PATH, or FFMPEG / FFPROBE in [env] | Previews; width, height, duration_secs, has_audio on assets; media operations; {{job:…:last_frame}} | | EMBEDDINGS_API_KEY (OpenAI), or EMBEDDINGS_URL + EMBEDDINGS_MODEL for any OpenAI-compatible endpoint such as Ollama | similar_assets |

How a generation works

sequenceDiagram
    autonumber
    participant A as Agent
    participant R as AI Media Router
    participant P as Provider
    participant L as Library
    A->>R: list_recipes
    R-->>A: presets: provider, model, input, offer, budget
    alt a preset fits
        A->>R: generate {recipe, input}
    else choosing a provider or model
        A->>R: search_prices "seedance 1080p"
        R-->>A: offers, cheapest fir