黑色星期五充值赠礼·充值 $50 起送 $10 · 充值 $100 起送 $25·11月30日截止充值 →
视频

用于多角色场景的视频镜头 API

像写台词一样写一个镜头,用 @ 标记角色和场景,拿回带声音和对话的视频,再把多个镜头免费拼成一部完整短片。

最后更新于 2026-11-05

预付费,无订阅REST 或 MCP一个密钥搞定模型、数据和智能体
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
黑色星期五

黑色星期五充值赠礼

每笔符合条件的充值都可获赠额度,并可与其他优惠叠加。

11月30日截止

充值 $50
+$10
额外赠送 20%
充值 $100
+$25
额外赠送 25%
注册并领取

一个故事需要每个镜头里都是同一批人。用 POST /v1/videos/shots 写下发生了什么,标记演员和地点,@Leo looks up as @Mia_Wong sits down in @[Night Café]: "You came.",每个被标记的角色和场景都会变成一张参考图。人物会保留照片里的脸、发型和衣服,地点保留它的样子,镜头自带声音和说出的对话。一个故事可以逐个镜头渲染,然后免费把镜头拼成一部视频。模型是 minimax-h3-video,由 MiniMax H3 驱动,每渲染一秒 $0.13,含一张图,每多一张图每秒 $0.06。

交给你的 AI 智能体

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

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

像写剧本一样写提示词

提示词决定用哪些图。它标记的每个角色和场景都会成为一张图,按首次提及的顺序,每个镜头 1 到 9 张。

你写的含义
@Mia_Wong名为 Mia Wong 的角色:空格变成 _,大小写不敏感
@[Night Café]任意名字,按原样书写
@chr_… 或 @scn_…用 id 指定角色或场景,用于两个同名时
"You came."对话,由它前面最后标记的角色说出

不要描述脸或衣服:图片会承载这些。把文字花在动作、镜头和氛围上。没有标记的提示词会使用唯一列出的角色和场景,前提是各只有一个。

MiniMax H3 最擅长读六段式的长提示词,而这不用你来写。每次渲染前,一个视觉模型(rewrite_model,默认 gemini-4-argon)会看你的图片和需求,写出完整的 H3 提示词;prompt_rendered 显示模型收到的内容,rewrite: false 则发送你自己写的。想自己写的话,如何写 MiniMax H3 提示词 讲解了这种格式。

代词是跟丢谁是谁的常见方式,所以在镜头渲染前,对话之外的代词会被替换成标记。只有一个角色时,这一步立即完成且免费;有两个或更多角色时,由聊天模型(sweep_model,默认 gemini-3.8-flash)改写提示词,并检查结果以逐字保留相同的标记和相同的对话。它的调用按普通聊天计费,显示为 other_usd。渲染后的文本在 prompt_rendered 中,sweep: false 会完全按你写的内容保留提示词。

02

从演员到成片

  1. 保存演员和地点

    保存的角色是一个名字、一段描述和一张转面图:同一个人从四个角度,外加六种表情的特写。用图像 API 制作这张图,并用 sheet_image_job 直接从图像任务中保存。场景是一个地点和它的图片。两者都免费,每个账户各最多 100 个。

    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. 渲染一个镜头

    列出镜头可能用到的角色和场景(整个库也可以),并标记其中出现的。镜头时长 5 到 15 秒,比例为 16:9、9:16 或 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. 拼接镜头

    按播放顺序拼接 2 到 50 个已完成、尺寸相同的镜头,每个镜头带自己的声音。拼接免费。

    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 返回 202 和镜头对象,若镜头在 wait 内完成(最多 300 秒)则返回 200。否则轮询 GET /v1/videos/shots/{id}?wait=60,并从 /content 下载 mp4。完成的文件保留 7 天。

03

用自己的声音说话的角色

给角色一个保存的声音(voice_id),或在保存角色时上传样本,他们在镜头里的台词就会用这个声音说出:它的音色、音高和说话方式,而不是它的词。镜头中按画面顺序的前 3 个有声音的角色会带上他们的声音;其余由模型配音。声音也可以设计:把它描述给文本转语音,保存结果并关联。声音不影响价格。

04

用自己的图片开场

{}

要让镜头从某个特定画面开始,把这张图作为场景发送,并在提示词中说明:"The shot opens exactly on @[Opening frame] as its first frame. @Priya turns from the window and walks toward the camera." 开场会紧跟它,但不是逐像素一致。画面中的人不会从图中保留;如果他们应该长得一样,也把他们作为角色发送。该画面在价格中算作一张图。

05

用于分镜的项目

项目保存一份分镜:一个名字和一份你自己的 JSON 文档,最大 200 KB,你可以用 project_id 把镜头和拼接归到它下面。演练场会把尺寸、风格、语言、镜头、角色和场景存在一个项目里。项目免费,每个账户最多 100 个。

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

费用

镜头按渲染秒计费。模型以 24 fps 的固定帧网格渲染,所以 5 秒的镜头会渲染 5.17 秒,10 秒的镜头渲染 10.13 秒;镜头对象的 rendered_seconds 会说明是哪个。

镜头中的图片每渲染秒
1$0.13
每多一张图片+ $0.06
3(两个角色和一个场景)$0.25

所以上面那个咖啡馆镜头,5 秒、两个角色和一个场景,大约花费 $1.29。价格在提交时预留,在镜头完成时扣费。失败和取消的镜头不收费,拼接、项目、保存的角色和场景都免费。当镜头中有两个或更多角色时,提示词扫描的聊天调用会在同一个 key 上按聊天计费。其余见定价。

模型输入 → 输出价格
MiniMax H3 Video (FastH3 Omni)
minimax-h3-video
text+image→video每秒 $0.13

实时美元价格,与 API 实际收费相同。

镜头受 MiniMax H3 条款约束:每个请求都要设置 consent: true。每个账户同时最多可以有 5 个镜头或拼接在排队或渲染。

07

常见问题

?
一个镜头可以有多少个角色?+

每个镜头最多 9 张图片,角色和场景合计。最多 3 个有声音的角色会带上自己的声音;其余由模型配音。

一个镜头可以多长?+

5 到 15 秒。可以把最多 50 个尺寸相同的已完成镜头免费拼成一部更长的视频。

镜头有声音吗?+

有。每个镜头都带自己的声音,以及你放在双引号里的对话,由它前面标记的角色用你设置的 language 说出(默认英语)。

一个视频镜头多少钱?+

一张图每渲染秒 $0.13,每多一张图每秒加 $0.06。拼接免费,失败的镜头不收费。

必须先保存角色吗?+

不用。镜头也接受内联的角色和场景,{name, image},使用 http(s) 或 data: URL。保存过的可以省去每次发送图片。

这和角色替换有什么不同?+

角色替换把新的人放进你已有的片段。镜头则从提示词和图片从零生成视频。要重铸已有视频,见角色替换。

每个字段和错误码都在视频镜头参考中。想要边看边持续推流,见实时视频 API。

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

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