AI character swap API:
replace people in any video
Recast any video: upload it, pick who becomes who, and get it back with those people replaced by your character. Motion, camera, cuts and sound stay.
Character replacement, also called recasting, re-shoots a video with a different person in it. You upload the video, the API finds its shots and everyone in them, and you say who becomes who: a saved character, a picture, or nobody. Every shot with a swapped person is rendered again with your character doing exactly what the original person did, and every other shot is left untouched. The motion, the framing, the camera moves, the cuts and the soundtrack all stay. Use it for a recast scene, a mascot in a dance trend, a virtual presenter in a real product demo, or a pre-visualization with your own cast, from one API call, or with no code in the playground.
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.
Replace people in a video with my own character using the Lovely Router video replacement API: it finds the shots and everyone in them for free, re-renders only the shots with a swapped person, and joins them back over the original sound.
- Docs (read first): https://lovelyrouter.com/docs/api/video-replacements.md and https://lovelyrouter.com/docs/api/characters.md
- Upload: POST https://lovelyrouter.com/v1/videos/replacements (multipart) with `video` (MP4/MOV/WebM up to 95 MB, or a URL), `model=minimax-h3-character-swap`, optional `start`/`end` (seconds, up to 3 minutes) and `consent=true` (confirms everyone shown is 18+ and agreed, and accepts the model's terms; read the licence linked in the docs first and tell me if my use might not be allowed).
- Poll GET https://lovelyrouter.com/v1/videos/replacements/<id>?wait=60 until `ready`, then show me the `cast` (face_url / body_url per person) and ask who becomes who before rendering.
- Render: POST https://lovelyrouter.com/v1/videos/replacements/<id>/render with `cast` (cast id → {"character_id"} or {"image"} or "keep"), `mode` (`person` or `face`) and optionally `background: "new"` with a `scene`. Billed per second swapped; the most it can cost is reserved when it starts.
- Poll until `succeeded`, then download GET https://lovelyrouter.com/v1/videos/replacements/<id>/content (kept 7 days). If a piece missed someone, POST .../pieces/<n>/retry with a short `search` description.
- For a recurring character, save it once with POST https://lovelyrouter.com/v1/characters and use its `character_id`.
- 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 video, who in it should be replaced, and a picture or saved character for each>How it works
Upload the video
Send an MP4, MOV or WebM file (up to 95 MB) to
POST /v1/videos/replacements, or just the part you want, up to 3 minutes. The video is cut into its shots, and everyone in it is grouped into a cast (p1,p2, …) with a face picture, a half-body picture and the shots they appear in. This analysis is free.Say who becomes who
Map each cast member to a character: a saved character's
character_id, a picture, orkeep. Choosepersonto swap the whole person (face, hair, body and clothes) orfaceto swap only the head and keep their clothes. Keep the original backgrounds, or setbackground: "new"and describe a newscenefor every shot.Shot by shot, the rest untouched
Each shot with a mapped person is rendered again from your character's picture, following the original motion and camera. A vision model notes each character's look first, so every shot shows the same hair, glasses and clothes, and each shot is checked for who is speaking, so a swapped person who doesn't speak doesn't mouth someone else's lines. Shots without a mapped person are kept exactly as they were.
One video, same sound
The shots are joined in their original order over the original sound. Watch each swapped piece as soon as it finishes, retry any piece that missed someone, and download the finished mp4 for 7 days.
Swap someone with two requests
# 1. Upload: shots and cast are found for free
curl https://lovelyrouter.com/v1/videos/replacements \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-F model=minimax-h3-character-swap \
-F video=@party.mp4 -F start=12 -F end=72 \
-F consent=true
# 2. Render: p1 becomes your saved character, p2 stays
curl https://lovelyrouter.com/v1/videos/replacements/RPL_ID/render \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"cast": {"p1": {"character_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2"}, "p2": "keep"}, "mode": "person"}'The upload answers 202; poll GET /v1/videos/replacements/{id}?wait=60 until it is ready and read its shots and cast. After the render call, poll again until it is succeeded, then download GET /v1/videos/replacements/{id}/content. The video replacement reference has the same flow in Python.
The tools for the job
POST /v1/videos/replacements handles videos with cuts, several shots and up to 8 people, and swaps only the shots that need it. Reference: video replacement endpoints.
For one continuous clip of up to 10 seconds, POST /v1/videos with video and input_reference returns the same clip with the new character in one call. See character swap.
Save a character once with POST /v1/characters (a name, a description and a turnaround sheet) and use its character_id in every video, so your mascot or presenter looks the same everywhere. Saving is free. See characters.
POST …/{id}/outfit cuts one person's clothes out of a frame of the video, so you can draw your character wearing them before you render. Free.
If a piece missed someone, POST …/{id}/pieces/{n}/retry renders just that piece again, finding the person by a short description ("man in a black suit") or by a tap on the frame. You pay only if someone is swapped.
Someone seen only from behind or very small can be added by position with added, then mapped like anyone else. Find them in the low-resolution preview video.
Pricing
| What | Price | Notes |
|---|---|---|
| Whole-video replacement | $0.2 per second swapped | Only the seconds where someone was replaced; each swapped piece counts at least 5 seconds. Finding the shots and the cast is free, and so are shots that stay unchanged. |
| Single-clip swap | $0.1 per second of video you get back | One clip, up to 10 seconds. |
A 60-second video in which your character appears for 25 seconds costs about $5. The most a render can cost is held from your prepaid balance when it starts, and the rest is returned when it finishes; a shot where nobody mapped is found isn't charged. The vision notes on each character and the speaker check on each shot are billed as small chat calls on your key. Every price is on pricing.
Recipes
Upload the cut, map the lead to your performer's saved character with mode: "person", and keep everyone else. Every shot the lead is in is re-shot; the rest of the cut is untouched.
Take a dance or meme clip, map the dancer to your mascot's character, and set background: "new" with a scene in your brand's colors.
Film a real product demo once, then swap the presenter's head with mode: "face" for each market's presenter, keeping the hands, clothes and product exactly as filmed.
Show your user the cast pictures after the free analysis, let them choose who becomes who, then call render. Discarding an analysed video costs nothing.
Give Claude Code or Cursor the prompt on this page: it reads the Markdown docs and calls the API with your key.
Consent and responsible use
Only replace people when you have the right to: your own footage, performers and creators who agreed, or characters you own. Every upload sets consent: true, confirming that everyone shown is 18 or older and agreed to this use of their likeness, and accepting the MiniMax H3 terms, which don't allow use in the EU, the UK, South Korea or the US. Impersonating real people, deceptive or non-consensual content, and anything involving minors are not allowed under the Acceptable Use Policy. Anyone can report misuse on the report page, and every report is reviewed. Finished videos are kept for 7 days, then deleted.
Frequently asked questions
What is a recast?+
Recasting a video means putting a different person in a role that was already filmed: same scene, same moves, same timing, new face and body. Here it is one API call: map who in the video becomes which character, and only their shots are re-rendered.
How is this different from a face swap app?+
A face swap pastes one face over another frame by frame. Character replacement re-renders the shot with your character as a whole person, or just their head, so hair, body, clothes and lighting match. It handles a whole video with cuts and several people, and leaves the shots without them untouched.
Does the video keep its sound and timing?+
Yes. Shots are re-rendered at their original length and joined in order over the original soundtrack, so the cuts, the music and any dialogue stay in sync.
Can I swap more than one person?+
Yes. Map up to 8 cast members in one render, each to a different character, or keep any of them as they are.
How long does it take?+
The free analysis usually takes a minute or two. Each swapped shot then renders in about a minute per 5 seconds, and shots render one after another; a 30-second video with the swapped person in most shots is ready in about 6 to 10 minutes. Add about a minute when no GPU is warm.
What makes a good character picture?+
One person, face clearly visible, evenly lit, on a plain background. A turnaround sheet (front, side, back) from a saved character gives the steadiest likeness from every angle.
What if a shot comes back unchanged?+
People are matched by face, so someone seen only from behind may not be found in a shot. That piece comes back unchanged and isn't charged. Retry it with a description or a tap on the person.
For the whole API, see the video replacement reference; for music videos with the same characters, see music videos.