API 参考

角色端点

所有 /v1/characters 和 /v1/scenes 端点——保存角色（名字、描述和一张多视角参考图）或场景（一个地点和它的图片），列出、获取、更新和删除它们，下载图片，并在音乐视频、角色替换和视频镜头中使用它们。

已保存角色是你想反复使用的一个人：名字、描述（脸、发型、体型、平常穿的衣服）和一张多视角参考图——同一个人的正面、四分之三侧、侧面和背面，下面是六种表情的面部特写，都在一张图里——还可以附上生成它的原始照片和一个声音。把它的 ID 作为 character_id 传给音乐视频和角色替换，就不必每次都发送图片。

已保存角色是可选的。每个视频端点仍然接受内联的图片和文字，所以一次性调用完全不需要已保存角色。

这些端点位于 https://lovelyrouter.com/v1/characters 下。用你的 API 密钥进行身份验证，格式为 Authorization: Bearer $LOVELY_API_KEY（身份验证）。保存角色免费，仅你的账户可见，在你删除之前一直保留；每个账户最多可保存 100 个。

角色对象#

属性

idstring

唯一 ID，chr_ 后接 24 个字符。

objectstring

固定为 character。

namestring

你给角色起的名字，最多 80 个字符。

descriptionstring

这个人是谁，按你写的原样保存：脸、发型、身材和默认服装。最多 4,000 个字符；可以为空。

sheet_urlstring

多视角参考图。参见下载图片。替换参考图后，查询参数 v 的值会变化。

photo_urlstring | null

原始照片，保存了照片时才有。

voiceobject | null

角色在视频镜头中的声音：id（一个已保存声音）、description（它是如何设计的，或 null）和 audio_url（样本）。角色没有声音时为 null。参见给角色配上声音。

created_atinteger

Unix 秒。

updated_atinteger

最后一次修改的 Unix 秒。

The character object

{
  "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "object": "character",
  "name": "Mara",
  "description": "A woman in her thirties with a long black braid, brown eyes, freckles and an athletic build; a green bomber jacket over a grey hoodie, black cargo trousers and white sneakers.",
  "sheet_url": "https://lovelyrouter.com/v1/characters/chr_3b9e1f0c7a2d4e58b6c1a9f2/sheet?v=mh2x7k1c",
  "photo_url": null,
  "voice": {
    "id": "voice_7d2a9c4e1b6f3a8d0c5e2b1f",
    "description": "A low, calm alto, unhurried",
    "audio_url": "https://lovelyrouter.com/v1/audio/voices/voice_7d2a9c4e1b6f3a8d0c5e2b1f/audio"
  },
  "created_at": 1792915200,
  "updated_at": 1792915200
}

创建角色#

POST/v1/characters

保存一个角色，并以 201 返回角色对象。可以发送 multipart（sheet 和 photo 作为文件）或 JSON（同样的字段，以 http(s) 或 data: URL 提供）。要保存你用图像 API 生成的参考图，把图像任务的 ID 作为 sheet_image_job 传入，代替文件。

请求体参数

namestring必填

最多 80 个字符。

descriptionstring

脸、发型、身材和默认服装，最多 4,000 个字符。你没有发送 character 时，音乐视频会把它用作 character 创意说明。

sheetfile or string必填

多视角参考图：PNG、JPEG 或 WebP，最大 10 MB，文件或 http(s) / data: URL（也可用 sheet_url）。也可以改用 sheet_image_job，从图像任务中取图。

sheet_image_jobstring

你账户中一个已 succeeded 的图像任务 ID（img_…）：它的第一张图片会成为参考图。在它和 sheet 之间二选一。

photofile or string

生成参考图所用的照片，PNG、JPEG 或 WebP，最大 10 MB（也可用 photo_url 或 photo_image_job）。仅供你留档；视频使用的是参考图。

voice_idstring

给角色使用的一个你的已保存声音（voice_…）。

voicefile or string

或者一个新的声音样本：WAV、MP3、OGG/Opus、FLAC、M4A 或 WebM，最大 10 MB，文件或 http(s) / data: URL。它会以角色的名字保存为你的一个声音并关联到角色。需要 consent。

voice_transcriptstring

样本里说的话（最多 1,000 个字符）——有了它声音克隆得更好。

consentboolean

true 表示你确认样本是你自己的声音，或你已获得说话人的许可。使用 voice 时必填。

voice_descriptionstring

这个声音是如何设计的，例如你给 qwen3-tts 的描述（最多 1,000 个字符）。与声音一起保存，供你留档。

Shell

curl https://lovelyrouter.com/v1/characters \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name=Mara \
  -F description="A woman in her thirties with a long black braid, brown eyes and freckles; a green bomber jacket" \
  -F sheet=@mara-sheet.png

列出角色#

GET/v1/characters

你的角色，按时间倒序。

查询参数

limitinteger默认 20

1–100。

afterstring

一个角色 ID：列出在它之前保存的角色（下一页）。

cURL

curl "https://lovelyrouter.com/v1/characters?limit=50" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [{ "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2", "object": "character", "name": "Mara" }],
  "first_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "last_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "has_more": false
}

获取角色#

GET/v1/characters/{id}

返回角色对象；ID 不属于你时返回 404。

cURL

curl https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

更新角色#

PATCH/v1/characters/{id}

修改你发送的字段，并返回角色对象。与创建一样接受 JSON 或 multipart。已经制作好的视频保留制作时所用的参考图。

请求体参数

namestring

新名字。

descriptionstring

新描述（空字符串会清空它）。

sheetfile or string

新的参考图，或 sheet_image_job。

photofile

新照片（或 photo_image_job）；null 会删除它。

voice_idstring or null

关联你的一个已保存声音；null 取消关联（已保存的声音本身保留）。

voicefile

一个新样本（与 voice_transcript 和 consent 一起，同创建）；null 取消关联。

voice_descriptionstring or null

声音是如何设计的。新关联的声音使用随它一起发送的描述，没有则为空。

cURL

curl -X PATCH https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"description": "A woman in her thirties with a long black braid, now in a red raincoat"}'

下载图片#

GET/v1/characters/{id}/sheet

参考图，带有它自己的内容类型；GET /v1/characters/{id}/photo 是原始照片（没有照片时返回 404）。只有你的密钥能读取它们。

cURL

curl https://lovelyrouter.com/v1/characters/CHARACTER_ID/sheet \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o sheet.png

删除角色#

DELETE/v1/characters/{id}

删除角色及其图片。已经用它制作的视频不受影响。

cURL

curl -X DELETE https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{ "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2", "object": "character.deleted", "deleted": true }

给角色配上声音#

角色可以有一个声音：你的一个已保存声音。在视频镜头中，有声音的角色用这个声音说台词——借用它的音色、音高和语气，而不是它说的内容。

上传：创建或更新角色时，把样本作为 voice 发送（附上 voice_transcript 和 consent: true）。它会以角色的名字保存为一个声音。
设计：用 qwen3-tts 根据一段描述和角色可能说的一句台词生成样本（instructions = 描述，input = 台词，不传 voice），用 POST /v1/audio/voices 保存，再作为 voice_id 关联——把描述作为 voice_description。

voice_id: null（或 voice: null）取消关联。删除角色会保留它的声音；删除声音会把它从所有角色上取消关联。

cURL

# 给角色关联一个已保存声音。
curl -X PATCH https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"voice_id": "voice_7d2a9c4e1b6f3a8d0c5e2b1f", "voice_description": "A low, calm alto, unhurried"}'

已保存场景#

POST/v1/scenes

已保存场景是你想在视频镜头中反复使用的地点：名字、地点描述和它的图片。场景的用法与角色相同，位于 https://lovelyrouter.com/v1/scenes 下，图片字段叫 image（文件、http(s) / data: URL，或 image_image_job），没有照片。每个账户最多 100 个，不占用角色的名额；免费。

场景对象：{id: "scn_…", object: "scene", name, description, image_url, created_at, updated_at}。

请求	作用
`POST /v1/scenes`	`name`（必填，最多 80 个字符）、`description`、`image`（必填）。返回 `201`。
`GET /v1/scenes`	你的场景，从新到旧（`?limit`、`?after`）。
`GET /v1/scenes/{id}`	一个场景。
`PATCH /v1/scenes/{id}`	`name`、`description`、`image`。
`GET /v1/scenes/{id}/image`	图片（仅你的密钥可读）。
`DELETE /v1/scenes/{id}`	删除场景及其图片。

cURL

curl https://lovelyrouter.com/v1/scenes \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name="Night Café" \
  -F description="A small café at night, rain on the windows, warm lamps" \
  -F image=@cafe.jpg

使用角色#

在原本发送图片的地方传入 character_id。内联字段仍然可用，所以每次调用都可以自行选择：

端点	一次性调用（内联）	使用已保存角色
`POST /v1/videos/music`	`character`（文字）和/或 `character_image`（文件或 URL）	`character_id`：它的参考图作为参考图片，未发送 `character` 时它的描述作为 `character` 文字。不能与 `character_image` 同时使用，且仅限 `mode: "image"`。
`POST /v1/videos`	`input_reference`（文件或 URL）	`character_id`：它的参考图作为参考图片。两者必须且只能发送其一。
`POST /v1/videos/shots`	`characters` / `scenes`：`{name, image}` 对象	`characters` / `scenes`：ID；提示词标记它们（`@Mara`），每个被标记的都是一张参考图片。

音乐视频对象和视频对象会显示制作时所用的 character_id（内联调用为 null）。

cURL

# 一次性的音乐视频：图片随调用发送。
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 -F consent=true \
  -F character="A woman with a long black braid" -F character_image=@mara.png

# 同样的视频，使用已保存角色。
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 -F consent=true \
  -F character_id=chr_3b9e1f0c7a2d4e58b6c1a9f2

错误#

错误使用标准错误响应体。

状态	`type`	原因
`400`	`invalid_request_error`	缺少 `name` 或 `sheet`、字段过长、图片不是 PNG、JPEG 或 WebP 或大于 10 MB、图像任务不属于你或尚未成功，或已保存了 100 个角色。`voice_id` 不是你的声音、`voice` 不是音频或大于 10 MB、发送 `voice` 时没有 `consent`，或已保存了 100 个声音。
`401`	`authentication_error`	API 密钥缺失或无效。
`404`	`not_found_error`	未知或已删除的角色，或属于其他账户的角色——在视频请求中作为 `character_id` 时也是如此。