API 参考

音乐视频端点

所有 /v1/videos/music 端点——用一首歌创建音乐视频、轮询、审阅并修改场景、渲染、下载整支视频、单个场景或某个造型的参考图、删除——包括参数、响应和错误。

音乐视频 API 位于 https://lovelyrouter.com/v1/videos/music 下。每个请求都需要用你的 API 密钥进行身份验证，格式为 Authorization: Bearer $LOVELY_API_KEY（身份验证）。请求为 JSON 或 multipart；除视频文件外，响应均为 JSON。视频从你的预付费余额中扣费。

如需完整的入门介绍——一首歌如何变成视频、如何写创意说明、耗时与价格——请从音乐视频指南开始。

音乐视频对象#

每个端点都返回这个对象，或由它组成的列表。

属性

idstring

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

objectstring

固定为 music_video。

modelstring

用于渲染的模型：ltx-music-video 或 minimax-h3-music-video。

statusstring

analyzing、planning、ready（使用 auto_render: false 时等待渲染）、in_progress、completed、failed 或 cancelled。

stepstring

更细的步骤：analyzing、planning、ready、rendering、stitching（拼接场景）、succeeded、failed 或 cancelled。

planning_stepstring | null

处于 planning 时：casting（导演定下歌手和造型）、profile（画出各造型的参考图）、directing（写镜头）或 frames（画出每个场景的首帧）。其他状态下为 null。

progressinteger

0–100：分析到 5，写场景到 15，渲染到 95，拼接到 100。

created_atinteger

Unix 秒。

completed_atinteger | null

completed 后的完成时间。

expires_atinteger | null

文件被删除的时间，即 completed_at 之后 7 天。

secondsnumber | null

分析后为歌曲（或片段）时长；完成后为视频时长。

startnumber | null

片段在歌曲中的起点，单位为秒。使用整首歌时为 null。

endnumber | null

片段的终点，单位为秒——分析后按实际应用的值给出（超过歌曲结尾的 end 会变为歌曲结尾）。使用整首歌时为 null。

sizestring

先是你请求的画面比例（16:9、9:16、1:1），完成后为视频的像素尺寸，例如 1472x832。

modestring

image（带角色档案）或 text。

briefobject

你发送的 story、style、character 和 locations（未发送时为 null）。使用 character_id 且未发送 character 时，character 为已保存角色的描述。

character_idstring | null

制作视频所用的已保存角色，或 null。

director_modelstring

写场景的聊天模型。

image_modelstring | null

mode: "image" 下画参考图和首帧的图像模型。

first_framesboolean

minimax-h3-music-video 是否也画首帧（见创建请求中的 first_frames）。

temponumber | null

分析后得到的歌曲速度，单位为每分钟节拍数。

languagestring | null

分析后转写歌词所用的语言。

characterstring | null

导演定下的歌手：脸、发型、身材，不含服装。mode: "text" 下以及选角完成前为 null。

looksarray

歌手的造型（服装），最多四个；mode: "text" 下以及选角完成前为空。

scenesarray

每个场景一项，按顺序排列；歌曲分析完成前为空。

errorobject | null

failed 和 cancelled 的视频才有：code 和 message（会说明是否收了费）。

urlstring | null

completed 后完成的 mp4。参见下载视频。

hold_usdnumber

从余额中冻结的金额：整首歌的价格，从分析结束起冻结，直到视频结算。之前为 0。

charge_usdnumber | null

结算后视频的费用。之前为 null。

other_usdnumber

导演的聊天调用以及参考图和首帧的图像调用到目前为止的费用。它们作为各自的调用计费，不计入 charge_usd。

powered_bystring

LTX 或 MiniMax H3。

The music video object

{
  "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
  "object": "music_video",
  "model": "ltx-music-video",
  "status": "completed",
  "step": "succeeded",
  "planning_step": null,
  "progress": 100,
  "created_at": 1792915200,
  "completed_at": 1792915330,
  "expires_at": 1793520130,
  "seconds": 16.13,
  "start": null,
  "end": null,
  "size": "1472x832",
  "mode": "image",
  "brief": {
    "story": "A night drive through a neon city that ends at the sea at dawn",
    "style": "Cinematic 35 mm film, teal and orange, light rain",
    "character": "A woman in her twenties with short black hair and a red leather jacket",
    "locations": null
  },
  "character_id": null,
  "director_model": "gemini-3.8-flash",
  "image_model": "gpt-image-2",
  "first_frames": false,
  "tempo": 118,
  "language": "en",
  "character": "A woman in her twenties with short black hair in a blunt bob, dark brown eyes, light olive skin, a slim build and a small scar above her left eyebrow",
  "looks": [
    {
      "id": 1,
      "outfit": "A red leather jacket over a black T-shirt, dark jeans, black boots, silver hoop earrings",
      "url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/looks/1/content"
    }
  ],
  "scenes": [
    {
      "index": 0,
      "look": 1,
      "start": 0,
      "seconds": 5.375,
      "lyrics": null,
      "prompt": "A woman in her twenties with short black hair in a blunt bob, dark brown eyes, light olive skin, a slim build and a small scar above her left eyebrow, wearing a red leather jacket over a black T-shirt, dark jeans, black boots, silver hoop earrings. Style: Cinematic 35 mm film, teal and orange, light rain. She drives through the neon city, signs smearing across the wet windshield; the camera pushes in from the passenger seat.",
      "status": "done",
      "url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/scenes/0/content"
    },
    {
      "index": 1,
      "look": 1,
      "start": 5.375,
      "seconds": 5.042,
      "lyrics": "we never looked back",
      "prompt": "A woman in her twenties with short black hair in a blunt bob, … wearing a red leather jacket over a black T-shirt, … Style: Cinematic 35 mm film, teal and orange, light rain. Medium close-up: she sings \"we never looked back\" to the camera, hair whipping in the wind of the open window, handheld.",
      "status": "done",
      "url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/scenes/1/content"
    },
    {
      "index": 2,
      "look": 1,
      "start": 10.417,
      "seconds": 5.708,
      "lyrics": null,
      "prompt": "A woman in her twenties with short black hair in a blunt bob, … wearing a red leather jacket over a black T-shirt, … Style: Cinematic 35 mm film, teal and orange, light rain. She steps out of the car on an empty beach road as the sky turns pink; the camera tracks alongside her toward the sea.",
      "status": "done",
      "url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/scenes/2/content"
    }
  ],
  "error": null,
  "url": "https://lovelyrouter.com/v1/videos/music/mv_8c1f3a9e2b7d4c60a5e9f1b3/content",
  "hold_usd": 0,
  "charge_usd": 1.1288,
  "other_usd": 0.1621,
  "powered_by": "LTX"
}

创建音乐视频#

POST/v1/videos/music

用一首歌开始制作音乐视频，并立即以 202 返回音乐视频对象。工作在后台进行；用获取音乐视频跟进。可以发送 multipart（song 和 character_image 作为文件）或 JSON（同样的字段，以 http(s) 或 data: URL 提供）。歌手可以随调用内联提供（character、character_image），也可以来自已保存角色（character_id）；两种方式都可以，也都不是必需的。默认会先为歌手选角并画出参考图（角色档案）。开始时余额需要足够支付最短的视频（15 秒）；歌曲时长确定后会冻结整首歌的价格。

请求体参数

modelstring必填

ltx-music-video 或 minimax-h3-music-video（参见模型）。

songfile or string必填

歌曲：MP3、WAV、FLAC、OGG 或 M4A，5 秒到 6 分钟，最大 60 MB。文件，或 http(s) / data: URL（也可用 song_url）。

startnumber

只使用歌曲的一部分：片段的起点，单位为秒（默认 0）。分析、场景、歌词和配乐都以片段为准，按片段时长付费。参见使用歌曲的一部分。

endnumber

片段的终点，单位为秒（默认：歌曲结尾）。end − start 必须至少 5 秒、至多 6 分钟。

consentboolean必填

true：你接受该模型的条款——LTX 条款或 MiniMax H3 条款（包括其地域条款）——并对遵守它们负责，并确认创意说明或图片中可辨认的任何人都已年满 18 岁且同意以此方式使用其肖像。

storystring

整首歌里发生的事。与其他创意说明字段一样，最多 4,000 个字符。

stylestring

画面风格：胶片还是动画、色彩、光线、镜头。会加到每个场景的提示词里。

characterstring

歌手（脸、发型、体型、主造型的服装）。选角会保留每个细节并补全其余部分；mode: "text" 下会原样加到每个场景的提示词里。

locationsstring

故事经过的地点。

lyricsstring

歌曲原本的歌词，用于正确的写法。可选：歌词无论如何都会被转写。

languagestring

供转写使用的歌曲语言，例如 en、zh 或 ja。默认：自动识别。

sizestring默认 16:9

16:9、9:16 或 1:1：ltx-music-video 为 1472×832、832×1472 或 1152×1152；minimax-h3-music-video 为 1344×768、768×1344 或 1024×1024。

modestring默认 image

image：角色档案——导演为歌手选角并定下最多四个造型，image_model 为每个造型画一张参考图，每个场景都从依其造型参考图画出的首帧开始（minimax-h3-music-video：每个场景直接依参考图拍摄；见 first_frames）。text：不画图，每个场景只根据提示词生成；不能用于 minimax-h3-music-video，它需要角色档案。

image_modelstring默认 gpt-image-2

仅用于 mode: "image"。你的密钥可用、支持参考图（编辑） 的图像模型，例如 gpt-image-2；只能生成的模型会被拒绝并返回 400。按普通图像任务计费，通常每个造型一张、每个场景一张。

first_framesboolean默认 false

仅 minimax-h3-music-video（其他模型在 mode: "image" 下总会画首帧）。这个模型直接依造型参考图拍摄歌手，不需要首帧；设为 true 时还会为每个场景画开场的一帧，与参考图一起交给模型：能更好地控制每个场景在哪里、以什么方式开场，代价是每个场景多一张图，渲染也更慢。此时视频按每秒 $0.2 计费（而不是 $0.13）。

character_imagefile or string

仅 mode: "image"。你的歌手图片，用来生成造型 1 的参考图：PNG、JPEG 或 WebP，最大 20 MB，文件或 URL（也可用 character_image_url）。

character_idstring

仅 mode: "image"。你账户中的一个已保存角色：它的参考图会像 character_image 一样使用；未发送 character 时，它的描述用作 character。不能与 character_image 同时使用。

director_modelstring默认 gemini-3.8-flash

写场景的聊天模型。你的密钥可用的任意聊天模型；按普通聊天调用计费。

scene_secondsnumber默认 5

目标场景时长，2–10 秒。剪辑点落在节拍上，所以场景长度会在它附近浮动。

auto_renderboolean默认 true

false：场景写好、首帧画好后停在 ready 状态，以便你在渲染之前修改它们。

seedinteger

可复现的场景（0–2147483647）。默认：随机。

查询参数

waitinteger

0–300。挂起请求，直到视频有变化（步骤切换、某个场景完成）或时间用完；如果届时已结束则返回 200。

Shell

curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video \
  -F song=@song.mp3 \
  -F story="A night drive through a neon city that ends at the sea at dawn" \
  -F style="Cinematic 35 mm film, teal and orange, light rain" \
  -F character="A woman in her twenties with short black hair and a red leather jacket" \
  -F start=42.5 -F end=102.5 \
  -F consent=true

# 用已保存角色代替内联的角色文字和图片：
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 \
  -F character_id=chr_3b9e1f0c7a2d4e58b6c1a9f2 \
  -F consent=true

Response

{
  "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
  "object": "music_video",
  "model": "ltx-music-video",
  "status": "analyzing",
  "step": "analyzing",
  "planning_step": null,
  "progress": 2,
  "seconds": null,
  "size": "16:9",
  "mode": "image",
  "character": null,
  "looks": [],
  "scenes": [],
  "error": null,
  "url": null,
  "hold_usd": 0,
  "charge_usd": null,
  "other_usd": 0,
  "powered_by": "LTX"
}

获取音乐视频#

GET/v1/videos/music/{id}

返回音乐视频对象。轮询它，直到 status 为 completed、failed 或 cancelled。

查询参数

waitinteger

0–300。长轮询：步骤切换或又有一个场景完成时立即返回，否则在时间用完时返回。处于 ready 的视频会立即返回。

Shell

curl "https://lovelyrouter.com/v1/videos/music/MUSIC_ID?wait=120" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

列出音乐视频#

GET/v1/videos/music

你的音乐视频，最新的在前。

查询参数

limitinteger默认 20

1–100。

afterstring

一个音乐视频 ID：列出在它之前创建的视频（下一页）。

cURL

curl "https://lovelyrouter.com/v1/videos/music?limit=10" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [{ "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3", "object": "music_video", "status": "completed" }],
  "first_id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
  "last_id": "mv_8c1f3a9e2b7d4c60a5e9f1b3",
  "has_more": false
}

修改场景#

PATCH/v1/videos/music/{id}

在视频处于 ready 时（以 auto_render: false 创建）改写场景提示词。你发送的每个提示词都会原样替换该场景的 prompt——不会再次加上角色、造型和 style，所以请把它们保留在其中。在 mode: "image" 下首帧已经画好；新的提示词会改变场景的动作，而不会改变它的首帧。返回音乐视频对象；其他状态下返回 409。

请求体参数

scenesarray必填

要修改的场景。

cURL

curl -X PATCH https://lovelyrouter.com/v1/videos/music/MUSIC_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"scenes": [{"index": 2, "prompt": "A woman in her twenties with short black hair and a red leather jacket. She sings \"we never looked back\" on an empty pier at dawn, the camera orbiting her."}]}'

渲染音乐视频#

POST/v1/videos/music/{id}/render

开始渲染处于 ready 的视频。返回音乐视频对象，此时为 in_progress；其他状态下返回 409。一天内未渲染的方案会被取消，不收费。

cURL

curl -X POST https://lovelyrouter.com/v1/videos/music/MUSIC_ID/render \
  -H "Authorization: Bearer $LOVELY_API_KEY"

下载视频#

GET/v1/videos/music/{id}/content

完成的 mp4，配乐就是这首歌。支持 Range 请求，播放器可以拖动进度。保留 7 天；completed 之前返回 409，删除或过期后返回 410。

cURL

curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o music-video.mp4

下载单个场景#

GET/v1/videos/music/{id}/scenes/{n}/content

单个已渲染场景的 mp4，带有它那段歌曲，在该场景 done 后即可下载——无需等整支视频完成。n 是场景的 index。尚未渲染时返回 409。

cURL

curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/scenes/0/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o scene-0.mp4

下载造型参考图#

GET/v1/videos/music/{id}/looks/{n}/content

某个造型的多视角参考图（正面、四分之三侧、侧面、背面），画好后即可下载——在规划阶段、任何场景渲染之前。n 是造型的 id，从 1 开始。尚未画好时以及 mode: "text" 下返回 404。

cURL

curl https://lovelyrouter.com/v1/videos/music/MUSIC_ID/looks/1/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o look-1.png

删除#

DELETE/v1/videos/music/{id}

对已结束的视频（completed、failed 或 cancelled）：删除它的文件，并从你的列表中移除。对停在 ready 等待的方案（auto_render: false）：放弃它，不收任何费用。已经开始分析或渲染的视频无法停止：返回 409。等它完成后再删除。

cURL

curl -X DELETE https://lovelyrouter.com/v1/videos/music/MUSIC_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response (deleted)

{ "id": "mv_8c1f3a9e2b7d4c60a5e9f1b3", "object": "music_video.deleted", "deleted": true }

错误#

错误使用标准错误响应体。视频开始后才失败不是 HTTP 错误：它的 status 为 failed，error 说明原因。

状态	`type` / `code`	原因
`400`	`consent_required`	`consent` 不是 `true`。
`400`	`invalid_request_error`	缺少歌曲或图片、无法读取、文件过大、字段超出范围、片段短于 5 秒或长于 6 分钟、没有 `mode: "image"` 却发送了 `character_image`、`character_id` 或 `first_frames`、对 `minimax-h3-music-video` 使用 `mode: "text"`、同时发送了 `character_image` 和 `character_id`，或你的密钥无法使用该 `director_model` / `image_model`。
`401`	`authentication_error`	API 密钥缺失或无效。
`402`	`insufficient_quota`	余额或密钥的消费上限不足以支付最短的视频。
`404`	`not_found_error`	未知的模型或音乐视频、该模型不制作音乐视频、`character_id` 不是你的已保存角色，或该造型的参考图还没画好。
`409`	`invalid_request_error`	修改或渲染不处于 `ready` 的视频，或下载尚未渲染的文件。
`410`	`not_found_error`	视频已被删除或已过期。
`429`	`rate_limit_exceeded`	你的账户已有两支音乐视频在进行中，或达到了密钥的速率限制。

失败的视频带有以下 error.code 之一：invalid_request_error（歌曲无法使用，例如短于 5 秒或长于 6 分钟，或 start 超过了歌曲结尾）、insufficient_quota（余额不足以支付整首歌）、capacity_exhausted（没有可用的 GPU）、api_error（我们这边出了问题）、expired（ready 的方案等了一天）和 cancelled（在 ready 时放弃的方案）。以上任何情况视频本身都不收费。