API 参考

视频镜头端点

所有 /v1/videos/shots、/v1/videos/joins 和 /v1/videos/projects 端点——用标记了角色和场景的提示词渲染镜头，免费把已完成的镜头拼接成一个视频，并把分镜保存为项目。

镜头是由提示词和图片生成的几秒视频：在提示词中标记你的已保存角色和场景——@Mia_Wong、@[Night Café] 或 @chr_…——每个被标记的都会成为一张参考图片。人物的脸、发型和服装来自他们的图片，地点的样貌来自它的图片，镜头自带声音和台词。每个镜头单独渲染，然后免费把已完成的镜头拼接成一个视频。

这些端点位于 https://lovelyrouter.com/v1/videos 下。用你的 API 密钥进行身份验证，格式为 Authorization: Bearer $LOVELY_API_KEY（身份验证）。模型是 minimax-h3-video，由 MiniMax H3 驱动，受 MiniMax H3 条款约束：每个镜头都要设置 consent: true。不想写代码，可以在 Playground 中试用。

标记与图片#

提示词决定用哪些图片。在 characters 和 scenes 中列出这个镜头可以使用的角色和场景（直接发送整个项目的素材库也可以）；提示词标记到的每一个都会成为一张图片，按第一次提到的顺序排列。

@handle——名字中的空格换成 _：Mia Wong → @Mia_Wong。不区分大小写。
@[Full Name]——按原样写出的任意名字：@[Night Café]。
@chr_… / @scn_…——ID，用于两个同名的情况。

双引号中的文字是台词，由它前面最后一个被标记的角色说出：@Leo looks up: "You came."。不要描述服装或长相——图片已经包含这些。一个镜头使用 1 到 9 张图片；没有标记的提示词，如果只列出了一个角色（以及只列出了一个场景），就使用它。

声音#

被标记的角色如果有声音，就会带上它：台词用这个声音说出（借用音色、音高和语气，不借用内容和背景声）。每个镜头按图片顺序，前 3 个有声音的角色带上自己的声音——模型最多接受 3 个音频参考；其余角色由模型配音。内联角色也可以带 voice：一个已保存声音的 ID（voice_…），或样本的 http(s) / data: URL。声音不影响价格。

谁是谁：提示词清理#

视频模型需要知道每个词说的是谁，所以对白之外的代词——he、she、his、her、they（以及他、她、彼、彼女）——绝不会送到模型。镜头渲染之前：

一个角色：每个代词都替换为该角色的标签（her coat → @Mia's coat），立即完成，免费。
两个或更多角色：由一个聊天模型（sweep_model，默认 gemini-3.8-flash）改写提示词，让每个人每次都用标签指明。答案会被检查——标签相同、对白一字不改、不留代词——不通过就再试一次；仍不通过则按你发送的提示词渲染。镜头绝不会因为清理而失败。

实际渲染的提示词是镜头的 prompt_rendered（没有改动时为 null）；prompt 保持你发送的原样。聊天调用作为普通聊天请求在同一个密钥上计费，显示为 other_usd，不计入镜头价格。发送 sweep: false 可完全按原文渲染。双引号内的文字永远不会被修改。

定价#

镜头按实际渲染的秒数计费：模型以 24 fps、17k+5 帧为单位渲染（至少 124 帧），所以 5 秒的镜头渲染 5.17 秒，10 秒的镜头渲染 10.13 秒——即镜头对象中的 rendered_seconds。使用一张图片时每渲染一秒 $0.13，之后每多一张图片每秒加 $0.06：一个有两个角色和一个场景的 5 秒镜头费用为（$0.13 + 2 × $0.06）× 5.17 秒。提交时预留费用，镜头完成时扣费；失败和取消的镜头不收费。拼接和项目免费。

镜头对象#

属性

idstring

shot_ 后接 24 个字符。

objectstring

固定为 video.shot。

statusstring

queued、in_progress、completed、failed 或 cancelled。

progressinteger

0–100，渲染时为估计值。

promptstring

你发送的提示词原文。

prompt_renderedstring | null

经过清理后的提示词（有改动时）。

secondsnumber

你要求的时长，5–15。

rendered_secondsnumber

实际渲染并计费的时长。

sizestring

16:9、9:16 或 1:1；完成后 width 和 height 为像素尺寸。

referencesarray

按图片顺序列出被标记的角色和场景：{picture, kind, name, id}（内联的 id 为 null）。然后按顺序列出随之而来的声音：{audio, kind, name, id}（audio = 1–3）。

project_idstring | null

所属项目。

urlstring | null

completed 后的 mp4，保留 7 天。

hold_usd、`charge_usd` number

预留的金额，以及结算后的费用。

other_usdnumber

清理的聊天调用，作为聊天在同一个密钥上计费（不计入 hold_usd / charge_usd）。

errorobject | null

失败时为 {code, message}。

镜头对象

{
  "id": "shot_8c1f0a7d3b9e4c2a6f5d1e0b",
  "object": "video.shot",
  "model": "minimax-h3-video",
  "status": "completed",
  "progress": 100,
  "project_id": "prj_2a9e7c1b5d3f4e6a8c0b1d2e",
  "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
  "prompt_rendered": null,
  "seconds": 5,
  "rendered_seconds": 5.167,
  "size": "16:9",
  "width": 1344,
  "height": 768,
  "seed": null,
  "language": "en",
  "style": null,
  "references": [
    { "picture": 1, "kind": "scene", "name": "Night Café", "id": "scn_5b2d9e0c1a7f4b3e8d6c2a1f" },
    { "picture": 2, "kind": "character", "name": "Leo", "id": "chr_1e4b7d0a9c3f2e5b8a6d0c1f" },
    { "picture": 3, "kind": "character", "name": "Mia Wong", "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2" },
    { "audio": 1, "kind": "character", "name": "Mia Wong", "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2" }
  ],
  "url": "https://lovelyrouter.com/v1/videos/shots/shot_8c1f0a7d3b9e4c2a6f5d1e0b/content",
  "hold_usd": 1.291667,
  "charge_usd": 1.291667,
  "other_usd": 0,
  "error": null,
  "powered_by": "MiniMax H3"
}

创建镜头#

POST/v1/videos/shots

开始一个镜头，返回 202 和镜头对象（在 wait 内完成则返回 200）。发送 JSON，或者 multipart（characters / scenes 作为 JSON 文本字段）。

请求体参数

modelstring必填

minimax-h3-video。

promptstring必填

发生什么，并标记角色和场景。最多 4,000 个字符。

consentboolean必填

true 表示接受 MiniMax H3 条款。

charactersarray

已保存角色的 ID（chr_…），或内联角色：{name, image, description?}，image 为 http(s) 或 data: URL——在 multipart 中也可以是某个文件字段的名字。内联角色还可以加上 voice：已保存声音的 ID，或样本的 http(s) / data: URL（参见声音）。

scenesarray

已保存场景的 ID（scn_…），或内联的 {name, image, description?}。

secondsnumber默认 5

5–15。

sizestring默认 16:9

16:9、9:16 或 1:1。

languagestring

台词使用的语言，例如 en、zh、ja。默认英语。

stylestring

画面风格，例如 warm 35mm film。默认真人实拍。

seedinteger

0–2147483647，用于得到可复现的结果。

sweepboolean默认 true

false 按原文渲染提示词，不做清理。

sweep_modelstring默认 gemini-3.8-flash

镜头中有两个或更多角色时，负责指明每个人的聊天模型。可以是你的密钥能用的任何聊天模型。

project_idstring

归入你的某个项目。

waitinteger

0–300 秒，请求保持到完成为止（也可用 ?wait=）。

Shell

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,
    "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
    "characters": ["chr_3b9e1f0c7a2d4e58b6c1a9f2", "chr_1e4b7d0a9c3f2e5b8a6d0c1f"],
    "scenes": ["scn_5b2d9e0c1a7f4b3e8d6c2a1f"],
    "seconds": 5
  }'

获取、列出和删除镜头#

GET/v1/videos/shots/{id}

返回镜头对象。?wait=1–300 会等到完成或超时。GET /v1/videos/shots/{id}/content 是 mp4（支持 Range 请求）。GET /v1/videos/shots 按从新到旧列出你的镜头：?limit=1–100，?before=<镜头 ID> 获取下一页，?project_id= 只列某个项目的。

DELETE /v1/videos/shots/{id} 把镜头从列表中移除并删除其文件。排队中的镜头会被免费取消；已经在渲染的镜头仍会完成并计费。

cURL

curl "https://lovelyrouter.com/v1/videos/shots/SHOT_ID?wait=60" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

curl https://lovelyrouter.com/v1/videos/shots/SHOT_ID/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o shot.mp4

拼接镜头#

POST/v1/videos/joins

按给定顺序把你已完成的镜头拼接成一个视频，每个镜头保留自己的声音。免费。这些镜头必须尺寸相同且不超过 7 天。返回 202 和拼接对象：{id: "join_…", object: "video.join", status, shots, size, seconds, width, height, url, charge_usd: 0}。GET /v1/videos/joins/{id}（可带 ?wait=）、/content、GET /v1/videos/joins 和 DELETE 的用法与镜头相同。

请求体参数

shotsarray必填

2–50 个镜头 ID，按播放顺序排列。

project_idstring

归入你的某个项目。

cURL

curl https://lovelyrouter.com/v1/videos/joins \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"shots": ["shot_8c1f0a7d3b9e4c2a6f5d1e0b", "shot_0d2e4f6a8b1c3e5d7f9a0b2c"]}'

项目#

POST/v1/videos/projects

项目用来保存分镜：一个名字和一份你自己的 JSON 文档（doc）——Playground 在里面保存尺寸、风格、语言、镜头、角色和场景。免费；每个账户最多 100 个。POST 接受 {name?, doc?}，返回 201 和 {id: "prj_…", object: "video.project", name, doc, created_at, updated_at}。

请求	作用
`GET /v1/videos/projects`	你的项目，最近修改的在前，不含 `doc`（`?limit`、`?after`）。
`GET /v1/videos/projects/{id}`	一个项目，含 `doc`。
`PATCH /v1/videos/projects/{id}`	`{name?, doc?}`；`doc` 整体替换，最大 200 KB。
`DELETE /v1/videos/projects/{id}`	删除项目；其中的镜头保留。

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": []}}'

错误#

错误使用标准错误响应体。提示词错误带有 code 和相关的 tags。

状态	`code` / `type`	原因
`400`	`unknown_tags`	提示词标记的名字不在 `characters` 或 `scenes` 中；`error.tags` 列出这些名字。
`400`	`ambiguous_tag`	列出的两个角色或场景与被标记的名字相同：请用 ID 标记其中一个。
`400`	`no_pictures` / `too_many_pictures`	没有图片，或超过 9 张。
`400`	`consent_required`	`consent` 不是 `true`。
`400`	`mixed_sizes`	拼接的镜头尺寸不同。
`400`	`invalid_request_error`	字段超出范围、图片无法读取、图片合计超过 24 MB、拼接的镜头尚未完成或已过期。
`402`	`insufficient_quota`	余额不足以支付预留金额。
`404`	`not_found_error`	未知的模型、镜头、拼接、项目、角色或场景，或属于其他账户。
`429`	`rate_limit_exceeded`	你的账户已有 5 个镜头或拼接在排队或渲染。