# Studio Router

> One API for video and image generation models across several providers. The same request parameters work whichever provider serves the model; each job runs on the cheapest capable provider; set `fallback: true` to let a failed job move to the next cheapest. Prepaid credits, charged at provider cost.

- Base URL: `https://api.studiorouter.com`
- Auth: `Authorization: Bearer sr_live_…` (API key from the dashboard)
- OpenAPI: https://api.studiorouter.com/openapi.json
- MCP server (Streamable HTTP): `https://api.studiorouter.com/mcp` with the same Bearer key. Tools: `create_upload_url`, `get_upload`, `list_projects`, `create_project`, `update_project`, `list_media`, `update_media`, `list_models`, `get_model`, `estimate_cost`, `generate`, `get_job`, `get_balance`, `create_top_up_link`, `report_problem`.

## Projects

Every generation is saved to one or more projects (folders by topic). Each account starts with a default project, used when a request sets no `project`. Agents should match a request to a project by its name and description, and read earlier generations of that project (`GET /v1/jobs?project=…&starred=true`) to reuse prompts and settings that worked.

## How a generation works

1. `POST /v1/videos` or `POST /v1/images` with JSON. Optional `Idempotency-Key` header makes retries safe.
2. The response (HTTP 202) is a job: `{ "id": "job_…", "status": "queued", "estimated_cost_usd": … }`. Credits for the estimate are held.
3. Poll `GET /v1/jobs/{id}?wait=50` (long-poll, max 50 s per call) until `status` is `succeeded`, `failed` or `blocked`. Or pass `webhook_url` and receive `{ "type": "job.succeeded", "job": … }`.
4. On success `output[0].url` is the file (hosted by us, does not expire) and `cost_usd` is what was charged. Failed and blocked jobs are not charged.

## Video request (POST /v1/videos)

| Field | Meaning |
|---|---|
| `model` (required) | Model id, see below |
| `prompt` (required) | What to generate |
| `image` | First-frame image URL → mode `first_frame` |
| `last_image` | Last-frame image URL (with `image`) → mode `first_last_frame` |
| `reference_images`, `reference_videos`, `reference_audios` | Reference media URLs → mode `reference` |
| `video` | Source video URL → mode `edit`; set `"mode": "extend"` to continue it instead |
| `mode` | Only needed to choose `extend`; otherwise inferred from the inputs |
| `duration` | Seconds (default 5). Not used by `edit`, which keeps the source length |
| `resolution` | `480p`, `720p`, `1080p`, … (default depends on the model) |
| `aspect_ratio` | `16:9` (default for text), `9:16`, `1:1`, … With an input image the output follows the image |
| `audio` | `false` to turn generated audio off where the model allows it |
| `seed` | Integer, passed to providers that take one (a hint: providers do not promise identical output) |
| `prompt_expansion` | Wan 3.0 / Prime, H3 Max, HeyGen Video 1. `off` (default) keeps your prompt verbatim, `on` lets the model rewrite it first, `quality` is a slower, richer rewrite. Left unset, `off` is sent to every provider that has a switch (a few providers have none and use their own behaviour). Set explicitly, only providers that can honour the value are used; `GET /v1/models` lists them per mode and provider |
| `negative_prompt` | What should not appear. Only providers that take one are used (currently Wan 3.0 / Prime text and first-frame, on Replicate) |
| `provider` | One provider id or an ordered list, to pin the provider |
| `fallback` | `false` (default): run only on the cheapest provider; a failure fails the job at no cost. `true`: on failure move to the next cheapest, up to 3 providers (credits for the dearest are held). An ordered `provider` list implies `true` |
| `project` | Project id or exact name (or a list) to save the result to. Default: your default project |
| `webhook_url`, `metadata` | Callback URL; free-form string map echoed on the job |

## Image request (POST /v1/images)

`model`, `prompt` (required); `images` (input image URLs → image edit); `resolution` (`1k`, `2k`, `4k`); `aspect_ratio`; `quality` (`low` / `medium` / `high`, GPT Image only); `output_format` (`png` / `jpeg` / `webp`); `seed` (Nano Banana, where the provider takes one); `provider`; `fallback`; `project`; `webhook_url`; `metadata`.

Media inputs are http(s) URLs. Public links go to the provider as they are, and we save a copy for your records (shown under `input_copies` on the job). To use a local file, upload it first (funded accounts only): `POST /v1/files` with the raw bytes and the file's `Content-Type` returns `{ "url": … }`, or `POST /v1/uploads` returns a one-time `upload_url` to PUT the file to, without the API key. An upload no generation uses within 24 hours is deleted.

## Other endpoints

- `GET /v1/models` — full catalog with parameters and prices per provider (no auth)
- `POST /v1/estimate` — price a request without running it (same body as a generation)
- `GET /v1/jobs` — your generations, newest first, with prompt, inputs, cost and output. Filters: `project`, `model` (comma list), `type`, `status`, `starred`, `q` (words in the prompt or note), `sort` (`latest` / `oldest`), `limit`, `cursor` (= `next_cursor`)
- `PATCH /v1/jobs/{id}` — `{ "starred": true, "note": "…", "add_projects": ["…"], "remove_projects": ["…"] }`
- `GET / POST /v1/projects`, `GET / PATCH / DELETE /v1/projects/{id}` — projects (`name`, `description`; PATCH `"is_default": true` makes one the default). Deleting keeps the generations: those only in that project move to the default project
- `GET /v1/balance` — `balance_usd`, `held_usd`, `spent_usd`
- `POST /v1/checkout` — `{ "credit_usd": 50 }` (a pack: 25, 50, 100, 200, 500; or a whole amount from 501 to 10000) returns a Stripe payment `url` for the user to open and pay. Credit lands seconds after payment
- `POST /v1/feedback` — `{ "kind": "problem" | "request", "message": "…", "job_id"? }` sends a problem report or a model/feature request to the team (3 an hour, 10 a day). Only when the user asks or agrees

## Errors

`{ "error": { "code", "message" } }`. Show the message to the user. HTTP 402: the balance is too low; offer to add credit.

## Example

```bash
curl https://api.studiorouter.com/v1/videos \
  -H "Authorization: Bearer $STUDIOROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"wan-3.0","prompt":"A red kite over a quiet beach at sunset","duration":5,"resolution":"480p"}'

curl "https://api.studiorouter.com/v1/jobs/job_…?wait=50" -H "Authorization: Bearer $STUDIOROUTER_API_KEY"
```

## Models

- **wan-3.0** — Wan 3.0 (Alibaba, video). General-purpose video with native audio, 2–30 s, text / image / reference inputs.
  - `text` (Text to video): 480p / 720p / 1080p, 2–30 s; from $0.0325 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `first_frame` (First frame (image to video)): 480p / 720p / 1080p, 2–30 s; from $0.0325 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `first_last_frame` (First + last frame): 480p / 720p / 1080p, 2–30 s; from $0.0325 per second; providers: machgen, atlas, sandbase, fal, wavespeed
  - `reference` (Reference images / video / audio): 480p / 720p / 1080p, 2–30 s; from $0.0325 per second; providers: machgen, atlas, sandbase, fal, wavespeed
  - `edit` (Video edit): 480p / 720p / 1080p; from $0.0643 per second; providers: sandbase, wavespeed
  - `extend` (Video extend): 480p / 720p / 1080p, 2–30 s; from $0.0325 per second; providers: sandbase, wavespeed
- **wan-3.0-prime** — Wan 3.0 Prime (Alibaba, video). Higher-quality Wan 3.0 tier, same inputs.
  - `text` (Text to video): 480p / 720p / 1080p, 2–30 s; from $0.0442 per second; providers: replicate, atlas, sandbase, fal, wavespeed
  - `first_frame` (First frame (image to video)): 480p / 720p / 1080p, 2–30 s; from $0.0442 per second; providers: replicate, atlas, sandbase, fal, wavespeed
  - `first_last_frame` (First + last frame): 480p / 720p / 1080p, 2–30 s; from $0.0442 per second; providers: atlas, sandbase, fal, wavespeed
  - `reference` (Reference images / video / audio): 480p / 720p / 1080p, 2–30 s; from $0.0442 per second; providers: atlas, sandbase, fal, wavespeed
  - `edit` (Video edit): 480p / 720p / 1080p; from $0.0874 per second; providers: sandbase, wavespeed
  - `extend` (Video extend): 480p / 720p / 1080p, 2–30 s; from $0.0442 per second; providers: sandbase, wavespeed
- **seedance-2.5** — Seedance 2.5 (ByteDance, video). Cinematic multimodal video, 4–30 s, up to 30 reference images, video edit and extend.
  - `text` (Text to video): 480p / 720p / 1080p / 4k, 4–30 s; from $0.0874 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `first_frame` (First frame (image to video)): 480p / 720p / 1080p / 4k, 4–30 s; from $0.0874 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `first_last_frame` (First + last frame): 480p / 720p / 1080p / 4k, 4–30 s; from $0.0874 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `reference` (Reference images / video / audio): 480p / 720p / 1080p / 4k, 4–30 s; from $0.0874 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `edit` (Video edit): 480p / 720p / 1080p / 4k; from $0.1143 per second; providers: machgen, sandbase, fal, wavespeed
  - `extend` (Video extend): 480p / 720p / 1080p / 4k, 4–30 s; from $0.0732 per second; providers: machgen, atlas, sandbase, fal, wavespeed
- **kling-v4.0** — Kling v4.0 (Kuaishou, video). Kling Video 4.0, 3–30 s at 720p or 1080p, references, edit and extend.
  - `text` (Text to video): 720p / 1080p, 3–30 s; from $0.1335 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `first_frame` (First frame (image to video)): 720p / 1080p, 3–30 s; from $0.1335 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `first_last_frame` (First + last frame): 720p / 1080p, 3–30 s; from $0.1335 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `reference` (Reference images / video / audio): 720p / 1080p, 3–30 s; from $0.1335 per second; providers: machgen, replicate, atlas, sandbase, fal, wavespeed
  - `edit` (Video edit): 720p / 1080p; from $0.1711 per second; providers: atlas, sandbase, fal, wavespeed
  - `extend` (Video extend): 720p / 1080p, 3–30 s; from $0.1335 per second; providers: wavespeed
- **flux-3** — FLUX 3 Video (Black Forest Labs, video). FLUX 3 video, 5–20 s at 720p or 1080p, first/last frame, edit and extend.
  - `text` (Text to video): 720p / 1080p, 5–20 s; from $0.17 per second; providers: replicate, atlas, sandbase, wavespeed
  - `first_frame` (First frame (image to video)): 720p / 1080p, 5–20 s; from $0.17 per second; providers: replicate, atlas, sandbase, wavespeed
  - `first_last_frame` (First + last frame): 720p / 1080p, 5–20 s; from $0.17 per second; providers: atlas, wavespeed
  - `edit` (Video edit): 720p / 1080p; from $0.03 per second; providers: atlas, fal, wavespeed
  - `extend` (Video extend): 720p / 1080p, 5–20 s; from $0.41 per second; providers: atlas, fal, wavespeed
- **gemini-omni-1.2-flash** — Gemini Omni 1.2 Flash (Google, video). Fast low-cost video, 3–15 s, 360p to 4K.
  - `text` (Text to video): 360p / 720p / 1080p / 4k, 3–15 s; from $0.0226 per second; providers: atlas, sandbase, fal, wavespeed
  - `first_frame` (First frame (image to video)): 360p / 720p / 1080p / 4k, 3–15 s; from $0.0228 per second; providers: atlas, sandbase, fal, wavespeed
  - `first_last_frame` (First + last frame): 360p / 720p / 1080p / 4k, 3–15 s; from $0.023 per second; providers: atlas, sandbase, fal, wavespeed
  - `reference` (Reference images / video / audio): 360p / 720p / 1080p / 4k, 3–15 s; from $0.0228 per second; providers: atlas, sandbase, wavespeed
  - `edit` (Video edit): 360p / 720p / 1080p / 4k; from $0.057 per second; providers: atlas, sandbase, wavespeed
  - `extend` (Video extend): 360p / 720p / 1080p / 4k, 3–10 s; from $0.0226 per second; providers: atlas
- **h3-max** — H3 Max (MiniMax, video). MiniMax H3 Max, 5–15 s at 480p or 768p.
  - `text` (Text to video): 480p / 768p, 5–15 s; from $0.035 per second; providers: atlas, sandbase, fal
  - `first_frame` (First frame (image to video)): 480p / 768p, 5–15 s; from $0.035 per second; providers: atlas, sandbase, fal
  - `first_last_frame` (First + last frame): 480p / 768p, 5–15 s; from $0.035 per second; providers: atlas, sandbase, fal
  - `reference` (Reference images / video / audio): 480p / 768p, 5–15 s; from $0.0475 per second; providers: atlas, sandbase, fal
- **heygen-video-1** — HeyGen Video 1 (HeyGen, video). HeyGen Video 1.0, 5–15 s at 480p or 768p.
  - `text` (Text to video): 480p / 768p / 1080p, 5–15 s; from $0.02 per second; providers: sandbase, fal, wavespeed
  - `first_frame` (First frame (image to video)): 480p / 768p / 1080p, 5–15 s; from $0.02 per second; providers: sandbase, fal, wavespeed
  - `reference` (Reference images / video / audio): 480p / 768p / 1080p, 5–15 s; from $0.02 per second; providers: sandbase, fal, wavespeed
- **grok-imagine-video-1.5** — Grok Imagine Video 1.5 (xAI, video). Grok Imagine Video 1.5, 1–15 s with generated audio.
  - `text` (Text to video): 480p / 720p / 1080p, 1–15 s; from $0.08 per second; providers: atlas, sandbase, wavespeed
  - `first_frame` (First frame (image to video)): 480p / 720p / 1080p, 1–15 s; from $0.08 per second; providers: machgen, replicate, atlas, sandbase, wavespeed
  - `reference` (Reference images / video / audio): 480p / 720p, 1–15 s; from $0.082 per second; providers: atlas, sandbase, wavespeed
- **gpt-image-2.6-flare** — GPT Image 2.6 Flare (OpenAI, image). Fast GPT Image 2.6 tier: generation and editing.
  - `text_to_image` (Text to image): 1k / 2k / 4k; from $0.007 per image; providers: machgen, atlas, sandbase, wavespeed
  - `image_edit` (Image edit): 1k / 2k / 4k; from $0.007 per image; providers: machgen, atlas, sandbase, wavespeed
- **gpt-image-2.6-sunburst** — GPT Image 2.6 Sunburst (OpenAI, image). Detailed GPT Image 2.6 tier: generation and precise edits.
  - `text_to_image` (Text to image): 1k / 2k / 4k; from $0.007 per image; providers: machgen, atlas, sandbase, wavespeed
  - `image_edit` (Image edit): 1k / 2k / 4k; from $0.007 per image; providers: machgen, atlas, sandbase, wavespeed
- **nano-banana-2** — Nano Banana 2 (Google, image). Fast Gemini image generation and natural-language edits.
  - `text_to_image` (Text to image): 0.5k / 1k / 2k / 4k; from $0.028 per image; providers: machgen, atlas, sandbase, fal, wavespeed
  - `image_edit` (Image edit): 0.5k / 1k / 2k / 4k; from $0.028 per image; providers: machgen, atlas, sandbase, fal, wavespeed
- **nano-banana-pro** — Nano Banana Pro (Google, image). High-quality Gemini image generation, typography and controlled edits.
  - `text_to_image` (Text to image): 1k / 2k / 4k; from $0.049 per image; providers: machgen, atlas, sandbase, fal, wavespeed
  - `image_edit` (Image edit): 1k / 2k / 4k; from $0.049 per image; providers: machgen, atlas, sandbase, fal, wavespeed
- **nano-banana-2.1** — Nano Banana 2.1 (Google, image). Newest Nano Banana: better layouts, text and character consistency, 1K to 4K, edits from up to 14 images.
  - `text_to_image` (Text to image): 1k / 2k / 4k; from $0.0175 per image; providers: machgen, atlas, sandbase, wavespeed
  - `image_edit` (Image edit): 1k / 2k / 4k; from $0.0175 per image; providers: machgen, atlas, sandbase, wavespeed
- **seedream-5.5** — Seedream 5.5 (ByteDance, image). Photoreal images with sharp small and multilingual text at 1K, 1.5K or 2K; edits from up to 10 images.
  - `text_to_image` (Text to image): 1k / 1.5k / 2k; from $0.016 per image; providers: atlas, wavespeed
  - `image_edit` (Image edit): 1k / 1.5k / 2k; from $0.016 per image; providers: atlas, wavespeed
- **h3-image** — H3 Image (MiniMax, image). MiniMax H3 Image: detailed photoreal scenes, illustrations and designs at 1K to 4K; edits combine up to 16 images.
  - `text_to_image` (Text to image): 1k / 2k / 4k; from $0.015 per image; providers: machgen, sandbase, wavespeed
  - `image_edit` (Image edit): 1k / 2k / 4k; from $0.015 per image; providers: machgen, sandbase, wavespeed