Black Friday deposit bonus·Top up $50+ and get $10 · Top up $100+ and get $25·Ends November 30Top up →
Video

Video shots API for scenes with several characters

Write a shot like a script line, tag your characters and places with @, and get video with sound and dialogue back. Join shots into one film for free.

Last updated 2026-11-05

Prepaid, no subscriptionREST or MCPOne key for models, data and agents
shots$ curl https://lovelyrouter.com/v1/videos/shots -H "Authorization: …> @mia hands @leo the letter in @kitchen. "You kept it?" shot rendering · 5 s · 2 characters ⏺ POST /v1/videos/joins [shot_1, shot_2, shot_3] ✓ episode.mp4 ready
Black Friday

Black Friday deposit bonus

Every qualifying top-up earns free credit, on top of any other offer.

Ends November 30

Deposit $50
+$10
20% bonus
Deposit $100
+$25
25% bonus
Sign up and claim

A story needs the same people in every shot. With POST /v1/videos/shots you write what happens, tag the cast and the place, @Leo looks up as @Mia_Wong sits down in @[Night Café]: "You came.", and every tagged character and scene becomes a reference picture. The people keep their faces, hair and clothes from their pictures, the place keeps its look, and the shot comes with its own sound and spoken dialogue. Render a story shot by shot, then join the shots into one video at no charge. The model is minimax-h3-video, powered by MiniMax H3, at $0.13 per rendered second with one picture and $0.06 per second for each extra picture.

Hand it to your AI agent

Copy this prompt into Claude Code, Cursor, Codex or any coding agent. It tells the agent where the docs are and how to use your API key.

Make multi-character video shots with the Lovely Router video shots API and join them into one film.

- Docs (read first): https://lovelyrouter.com/docs/api/video-shots.md and https://lovelyrouter.com/docs/api/characters.md
- Save characters and scenes once (POST https://lovelyrouter.com/v1/characters, /v1/scenes), then POST https://lovelyrouter.com/v1/videos/shots with a prompt that tags them (`@handle`), `consent: true`; poll the shot until it is completed. Join finished shots with POST https://lovelyrouter.com/v1/videos/joins (free).
- Billed per rendered second plus a fee per extra picture; render one short test shot before a whole episode.
- Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys.
- Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large.
- Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt.

My task: <the cast, the scenes and the shot list>
01

Write the prompt like a script

The prompt chooses the pictures. Every character and scene it tags becomes one, in the order it is first mentioned, from 1 to 9 per shot.

You writeIt means
@Mia_WongThe character named Mia Wong: spaces become _, case doesn't matter
@[Night Café]Any name exactly as written
@chr_… or @scn_…A character or scene by id, when two share a name
"You came."Dialogue, spoken by the character tagged last before it

Don't describe faces or clothes: the pictures carry them. Spend the words on action, camera and mood instead. A prompt without tags uses the only listed character and scene, when there is exactly one of each.

MiniMax H3 reads best from a long prompt in six sections, and you don't have to write it. Before each render, a vision model (rewrite_model, gemini-4-argon by default) reads your pictures and your request and writes the whole H3 prompt; prompt_rendered shows what the model got, and rewrite: false sends your own. How to write MiniMax H3 prompts explains the format if you want to write it yourself.

Pronouns are a common way to lose track of who is who, so before a shot renders, pronouns outside the dialogue are replaced by tags. With one character that happens at once and for free; with two or more, a chat model (sweep_model, gemini-3.8-flash by default) rewrites the prompt and the result is checked to keep the same tags and the same dialogue word for word. Its call is billed as ordinary chat and shown as other_usd. The rendered text is in prompt_rendered, and sweep: false keeps your prompt exactly as written.

02

From cast to finished video

  1. Save the cast and the place

    A saved character is a name, a description and a turnaround sheet: the same person from four sides over close-ups of six expressions. Make the sheet with the image API and save it straight from the image job with sheet_image_job. A scene is a place and its picture. Both are free, up to 100 of each per account.

    cURL
    curl https://lovelyrouter.com/v1/characters \
      -H "Authorization: Bearer $LOVELY_API_KEY" \
      -F name="Mia Wong" \
      -F description="A woman in her twenties with a short black bob and a yellow raincoat" \
      -F sheet=@mia-sheet.png
    
    curl https://lovelyrouter.com/v1/scenes \
      -H "Authorization: Bearer $LOVELY_API_KEY" \
      -F name="Night Café" \
      -F description="A narrow café at night, neon in the rain-streaked window" \
      -F image=@cafe.png
  2. Render a shot

    List the characters and scenes the shot may use (a whole library is fine) and tag the ones in it. Shots last 5 to 15 seconds, in 16:9, 9:16 or 1:1.

    Python
    import os, requests
    
    API = "https://lovelyrouter.com/v1/videos"
    H = {"Authorization": f"Bearer {os.environ['LOVELY_API_KEY']}"}
    
    shot = requests.post(f"{API}/shots", headers=H, params={"wait": 300}, json={
        "model": "minimax-h3-video",
        "consent": True,
        "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
        "characters": ["chr_3b9e1f0c7a2d4e58b6c1a9f2", "chr_1e4b7d0a9c3f2e5b8a6d0c1f"],
        "scenes": ["scn_5b2d9e0c1a7f4b3e8d6c2a1f"],
        "seconds": 5,
        "style": "warm 35mm film",
    }).json()
    print(shot["status"], shot["rendered_seconds"], shot["url"])
  3. Join the shots

    Join 2 to 50 completed shots of the same size, in the order they play, each with its own sound. Joins are free.

    Node.js
    const res = await fetch('https://lovelyrouter.com/v1/videos/joins', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.LOVELY_API_KEY}`, 'content-type': 'application/json' },
      body: JSON.stringify({ shots: ['shot_8c1f0a7d3b9e4c2a6f5d1e0b', 'shot_0d2e4f6a8b1c3e5d7f9a0b2c'] }),
    });
    const join = await res.json();
    console.log(join.id, join.status);

POST /v1/videos/shots answers 202 with the shot object, or 200 when the shot finished within wait (up to 300 seconds). Poll GET /v1/videos/shots/{id}?wait=60 otherwise, and download the mp4 from /content. Finished files are kept for 7 days.

03

Characters who speak in their own voice

Give a character a saved voice (voice_id), or upload a sample when you save them, and their lines in a shot are spoken in it: its timbre, pitch and manner, not its words. The first 3 voiced characters of a shot, in picture order, bring their voices; any others are voiced by the model. A voice can also be designed: describe it to text to speech, save the result and link it. Voices don't change the price.

04

Open on a picture of your own

{}

To start a shot on a specific frame, send the image as a scene and say so in the prompt: "The shot opens exactly on @[Opening frame] as its first frame. @Priya turns from the window and walks toward the camera." The opening follows it closely but not pixel for pixel. People in the frame are not kept from it; send them as characters too if they should look the same. The frame counts as a picture in the price.

05

Projects for storyboards

A project keeps a storyboard: a name and a JSON document of your own, up to 200 KB, and you can file shots and joins under it with project_id. The playground stores its size, style, language, shots, characters and scenes in one. Projects are free, up to 100 per account.

cURL
curl https://lovelyrouter.com/v1/videos/projects \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Night café", "doc": {"size": "16:9", "shots": []}}'
06

What you pay

A shot is billed per rendered second. The model renders on a fixed frame grid at 24 fps, so a 5 s shot renders 5.17 s and a 10 s shot 10.13 s; the shot object's rendered_seconds says which.

Pictures in the shotPer rendered second
1$0.13
Each extra picture+ $0.06
3 (two characters and a scene)$0.25

So the café shot above, 5 s with two characters and a scene, costs about $1.29. The price is reserved when you submit and charged when the shot completes. Failed and cancelled shots cost nothing, and joins, projects, saved characters and scenes are free. The prompt sweep's chat call, when two or more characters are in a shot, is billed as chat on the same key. See pricing for the rest.

ModelInput → outputPrice
MiniMax H3 Video (FastH3 Omni)
minimax-h3-video
text+image→video$0.13 per second

Live prices in USD, the same the API charges.

Shots are under the MiniMax H3 terms: every request sets consent: true. Each account can have 5 shots or joins queued or rendering at once.

07

Frequently asked questions

?
How many characters can one shot have?+

Up to 9 pictures per shot, counting characters and scenes together. Up to 3 voiced characters bring their own voices; the rest are voiced by the model.

How long can a shot be?+

5 to 15 seconds. Join up to 50 finished shots of the same size into one longer video, for free.

Does a shot have sound?+

Yes. Every shot comes with its own sound and the dialogue you put in double quotes, spoken by the character tagged before it, in the language you set (English by default).

How much does a video shot cost?+

$0.13 per rendered second with one picture, plus $0.06 per second for each extra picture. Joins are free, and failed shots cost nothing.

Do I have to save characters first?+

No. A shot also takes inline characters and scenes, {name, image} with an http(s) or data: URL. Saved ones save you sending the pictures every time.

How is this different from character swap?+

Character swap puts a new person into a clip you already have. Shots make the video from scratch, from a prompt and pictures. To recast an existing video, see character replacement.

Every field and error code is in the video shots reference. For a stream that keeps going while you watch, see the live video API.

One prepaid key for models, data and agents

No subscription. Top up, use what you need, see every charge in your logs.