Video

Lovely Router makes videos through a Videos API shaped like OpenAI's: POST /v1/videos starts a job and returns a video object, you poll it until it is completed, then download the mp4 from /v1/videos/{id}/content. Try it without code in the playground: upload a clip or find one on X, upload a picture or have any image model draw one, and let a chat model of your choice improve the character and scene prompts — each step billed to your balance like its API call.

For a video that keeps going while you watch, see Live video; to turn a song into a music video, see Music videos.

Models#

All are powered by MiniMax H3 and run on our own GPUs in the creative-hosted channel group. They are under the MiniMax H3 terms: every request sets consent: true, accepting them — including not using it in the EU, the UK, South Korea or the US — and the responsibility for following them.

Swap a character#

Send the source clip as video and a picture of the new character as input_reference, as files (multipart) or as URLs (http(s) or data:, in JSON or as multipart text fields).

curl https://lovelyrouter.com/v1/videos \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=minimax-h3-character-swap \
  -F video=@clip.mp4 \
  -F input_reference=@character.png \
  -F prompt="In front of a weathered concrete wall, soft window light" \
  -F consent=true

A render takes about one minute for a 5-second clip and two to three minutes for a 10-second one (larger frames take longer). When the model hasn't been used for a while, add about a minute while a GPU wakes up. Jobs keep running if you disconnect.

Request fields#

?wait=0–300 on the POST holds the request until the video finishes (then 200), else answers 202 with the queued object.

Use a saved character#

The new character can come with each call or from your saved characters:

• One-off: input_reference — the picture, as a file or a URL (above).
• Saved: character_id — a character you saved with POST /v1/characters; its turnaround sheet is the picture. The video object's character_id shows it.

curl https://lovelyrouter.com/v1/videos \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=minimax-h3-character-swap \
  -F video=@clip.mp4 \
  -F character_id=chr_3b9e1f0c7a2d4e58b6c1a9f2 \
  -F consent=true

Sending both, or a character_id that isn't one of yours, is refused (400 / 404).

Whole videos#

POST /v1/videos/replacements takes a whole video — up to 3 minutes, with cuts and several people. Its shots and everyone in it are found first ($0.01 per second); then you map each person to a character (or keep them) and choose the whole person or only the head (face, hair and anything worn on it). Every shot with a swapped person is re-rendered and the shots are joined back over the original sound; you pay per second swapped ($0.20 per second for the SFW model, rendered on FastH3 Omni; AfterMidnight $0.12). The video replacement endpoints page has the whole flow. The playground uses it for every clip, short or long.

Video shots#

minimax-h3-video makes video from scratch: POST /v1/videos/shots takes a prompt in which your saved characters and scenes are tagged (@Mia_Wong, @[Night Café]), and every tagged one becomes a reference picture — up to 9 per shot. Quoted words are spoken by the character tagged last before them. Render the shots of a story one by one, then join them with POST /v1/videos/joins (free). The video shot endpoints page has every field, the pricing and the projects API the playground uses for storyboards. A character with a voice speaks in it (up to 3 voices a shot). Pronouns outside the dialogue are replaced by the right tag before rendering (the prompt sweep).

curl https://lovelyrouter.com/v1/videos/shots \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "minimax-h3-video", "consent": true, "seconds": 5,
       "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
       "characters": ["chr_3b9e1f0c7a2d4e58b6c1a9f2", "chr_1e4b7d0a9c3f2e5b8a6d0c1f"],
       "scenes": ["scn_5b2d9e0c1a7f4b3e8d6c2a1f"]}'

The video object#

{
  "id": "video_4f9d0c2b8e1a47d6a3c5b7e2",
  "object": "video",
  "model": "minimax-h3-character-swap",
  "status": "completed",
  "progress": 100,
  "created_at": 1792915200,
  "completed_at": 1792915288,
  "expires_at": 1793520088,
  "seconds": "5.17",
  "size": "768x1376",
  "prompt": "In front of a weathered concrete wall, soft window light",
  "character_id": null,
  "error": null,
  "url": "https://lovelyrouter.com/v1/videos/video_4f9d0c2b8e1a47d6a3c5b7e2/content",
  "charge_usd": 0.3875,
  "powered_by": "MiniMax H3"
}

status is queued, in_progress, completed, failed or cancelled. A failed video has error: {code, message} and costs nothing. size follows the clip's orientation on a 768-pixel short edge; the frame rate is 24 fps.

Endpoints#

Pricing#

You pay per second of video you get back, 3 to 10 seconds per clip (a shorter result is billed as 3 seconds): a 5.2-second clip costs $0.52. When you start a video, the most it can cost ($1.00, or seconds × the price) is reserved from your balance; the difference comes back when it finishes. Failed and cancelled videos cost nothing.

Getting good results#

• The clip: one person, clearly visible, moving at a natural pace. Fast action and heavy occlusion are harder. Speech stays in sync because the soundtrack is kept and guides the mouth.
• The picture: the person alone, face visible, evenly lit, on a plain background. Its lighting and backdrop aren't copied, but strong colored light can bleed in. A character sheet — the same person from the front, three-quarter, side and back in one picture — works best when the camera moves around them; it still renders one person.
• The scene: describe the place in prompt to keep it close to the original, e.g. "a weathered concrete wall, soft window light".
• Hair shape follows the clip (a braid in the clip stays a braid); hair color, face and clothes follow the picture.

Errors#

Misuse can be reported at /report.