使用场景

AI 角色替换 API：
把任意视频里的人换成你的角色

上传一段视频，指定谁换成谁，就能拿回替换后的视频：画面中的人物换成你的角色，而动作、运镜、剪辑和声音都保持原样。

预付费，无订阅REST 或 MCP一个密钥搞定模型、数据和智能体

角色替换（也叫 recast，重新选角）会把视频重新"拍"一遍，只是里面的人换了。你上传视频，API 会找出所有镜头以及每个镜头里的人，然后由你指定谁换成谁：一个已保存的角色、一张图片，或者保持不变。凡是有被替换人物的镜头，都会以你的角色重新渲染，动作与原来的人完全一致；其他镜头一帧不动。动作、构图、运镜、剪辑和配乐全部保留。可以用来重拍一场戏、让吉祥物跳热门舞蹈、在真实的产品演示里换上虚拟主持人，或者用自己的阵容做预演。只需一次 API 调用，也可以不写代码，直接在 Playground 里完成。

交给你的 AI 智能体

把这段提示词复制到 Claude Code、Cursor、Codex 或任何编程智能体中。它会告诉智能体文档在哪里，以及如何使用你的 API 密钥。

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>

工作原理

上传视频
把 MP4、MOV 或 WebM 文件（最大 95 MB）发送到 POST /v1/videos/replacements，也可以只发送你需要的片段，最长 3 分钟。视频会被切分成镜头，出现的每个人会被归为一个演员表（p1、p2……），附带脸部图、半身图以及他们出现的镜头。这一步分析免费。
指定谁换成谁
为每个演员指定角色：已保存角色的 character_id、一张图片，或 keep。选 person 会替换整个人（脸、头发、身体和服装），选 face 只替换头部并保留原来的服装。可以保留原背景，也可以设 background: "new" 并为每个镜头描述一个新的 scene。
逐镜头渲染，其余不动
每个有被替换人物的镜头，都会根据角色图片、沿着原来的动作和运镜重新渲染。视觉模型会先记下每个角色的外观，让每个镜头里的发型、眼镜和服装都一致；还会判断每个镜头里是谁在说话，不说话的被替换者不会去对别人的口型。没有被替换人物的镜头保持原样。
一个视频，原声不变
所有镜头按原顺序拼接，配上原来的声音。每个替换片段一完成就能观看，漏掉人的片段可以单独重试，成片可在 7 天内下载。

两次请求完成替换

cURL

# 1. 上传：免费找出镜头和演员表
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. 渲染：p1 换成你保存的角色，p2 保持不变
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"}'

上传会立即返回 202；轮询 GET /v1/videos/replacements/{id}?wait=60 直到状态为 ready，然后查看其中的 shots 和 cast。调用渲染后再次轮询，直到 succeeded，然后下载 GET /v1/videos/replacements/{id}/content。视频替换 API 参考里有同样流程的 Python 示例。

用到的工具

整段视频替换。

POST /v1/videos/replacements 可处理带剪辑、多个镜头、最多 8 个人的视频，只替换需要替换的镜头。参考：视频替换接口。

单段片段替换。

对一段最长 10 秒的连续片段，POST /v1/videos 加上 video 和 input_reference，一次调用就返回换上新角色的同一片段。参见角色替换。

已保存的角色。

用 POST /v1/characters 保存一次角色（名称、描述和三视图设定图），之后每个视频都用它的 character_id，让你的吉祥物或主持人处处一致。保存免费。参见角色。

把原服装穿到你的角色身上。

POST …/{id}/outfit 会从视频的一帧里抠出某个人的服装，方便在渲染前把你的角色画成穿着这身衣服。免费。

单独重试一个镜头。

如果某个片段漏掉了人，POST …/{id}/pieces/{n}/retry 只重新渲染这一段，可以用一句简短描述（"man in a black suit"）或在画面上点一下来找到这个人。只有真的替换了人才收费。

分析漏掉的人。

只露背影或很小的人，可以用 added 按位置补上，然后像其他人一样映射。在低分辨率的 preview 视频里就能找到他们。

价格

项目	价格	说明
整段视频替换	每替换一秒 $0.2	只按真正替换了人的秒数计费；每个被替换的片段至少按 5 秒计。找镜头和演员表免费，保持不变的镜头也免费。
单段片段替换	返回视频每秒 $0.1	一段片段，最长 10 秒。

一段 60 秒的视频，你的角色出现 25 秒，费用约 $5。渲染开始时会从预付费余额里预留最高可能费用，完成后退回多余部分；没有找到被映射人物的镜头不收费。每个角色的外观记录和每个镜头的说话人判断，按小额对话调用从你的密钥计费。所有价格见价格页。

实用配方

重拍一场戏。

上传剪好的片段，把主角映射到演员已保存的角色，用 mode: "person"，其他人保持不变。主角出现的每个镜头都会重拍，其余部分一帧不动。

让吉祥物跳热门舞。

拿一段舞蹈或热梗视频，把舞者映射到吉祥物角色，设置 background: "new"，再用 scene 描述品牌配色的场景。

虚拟主持人。

真实的产品演示只拍一次，然后用 mode: "face" 为每个市场换上当地的主持人，手、服装和产品都保持原样。

先确认再花钱。

免费分析后把 cast 图片给用户看，让他们选好谁换成谁，再调用渲染。放弃一个已分析的视频不花钱。

会剪视频的智能体。

把本页的提示词交给 Claude Code 或 Cursor：它会阅读 Markdown 文档，并用你的密钥调用 API。

常见问题

什么是 recast（重新选角）？+

Recast 指把一个已经拍好的角色换成另一个人：同样的场景、同样的动作、同样的节奏，换上新的脸和身体。在这里只需一次 API 调用：指定视频里谁换成哪个角色，只有他们出现的镜头会被重新渲染。

这和换脸应用有什么不同？+

换脸是逐帧把一张脸贴到另一张脸上。角色替换会用你的角色把镜头重新渲染一遍，可以换整个人，也可以只换头部，所以发型、身体、服装和光线都能对上。它能处理带剪辑、有多个人的整段视频，并让不涉及替换的镜头保持原样。

视频的声音和节奏会保留吗？+

会。镜头按原时长重新渲染，再按顺序拼接到原声上，所以剪辑点、音乐和对白都保持同步。

能同时替换多个人吗？+

可以。一次渲染最多映射 8 个演员，每人换成不同的角色，也可以让任何人保持不变。

需要多长时间？+

免费分析通常需要一两分钟。之后每个被替换的镜头大约每 5 秒需要一分钟，镜头依次渲染；一段 30 秒、被替换的人出现在大多数镜头里的视频，大约 6 到 10 分钟完成。如果没有已启动的 GPU，再加约一分钟。

什么样的角色图片效果最好？+

画面里只有一个人，脸清晰可见，光线均匀，背景简单。用已保存角色的三视图设定图（正面、侧面、背面），各个角度的相似度最稳定。

如果某个镜头没有变化怎么办？+

人物是按脸来匹配的，所以全程只露背影的人可能在某个镜头里找不到。这个片段会原样返回，并且不收费。可以用一句描述或在画面上点一下这个人来重试。

完整的 API 请见视频替换参考；想用同样的角色做 MV，请见音乐视频。

一个预付费密钥，搞定模型、数据和智能体

无需订阅。充值后按需使用，每笔费用都能在日志中查看。

获取密钥价格

AI 角色替换 API：把任意视频里的人换成你的角色

交给你的 AI 智能体

工作原理

上传视频

指定谁换成谁

逐镜头渲染，其余不动

一个视频，原声不变