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
Black Friday deposit bonus
Every qualifying top-up earns free credit, on top of any other offer.
Ends November 30
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>
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 write | It means |
|---|---|
@Mia_Wong | The 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.
From cast to finished video
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.cURLcurl 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.pngRender 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:16or1:1.Pythonimport 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"])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.jsconst 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.
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.
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.
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 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": []}}'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 shot | Per 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.
| Model | Input → output | Price |
|---|---|---|
| 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.
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.