Lovely Router文档
获取密钥
模型 API

音乐视频

发送一首歌,拿回一支音乐视频 —— POST /v1/videos/music 按节拍把歌切成若干场景,根据你的创意说明为每个场景写一个镜头,让每个场景随它对应的那段音乐渲染,再把它们拼接到原曲上。创意说明、角色档案、审阅、价格与耗时。

POST /v1/videos/music 把一首歌做成音乐视频。你发送音频和一段简短的创意说明——故事、画面风格、人物——拿回一个与歌曲等长的 mp4,配乐就是这首歌。不写代码也可以在 Playground 里试用。所有字段和响应见 API 参考。

工作原理#

  1. 分析。 我们找出歌曲的节拍,把它切成在节拍上结束的场景,每个约 scene_seconds 长(默认 5 秒);场景长度会在整首歌里自动平均,最后一个场景不会过短,视频也会恰好在歌曲结束时结束;并逐个场景转写歌词。
  2. 选角。 由你选择的聊天模型——导演——读你的创意说明和歌词,一次性定下歌手:一段角色描述(脸、发型、身材,不含服装),以及故事需要的造型(服装),最多四个。
  3. 角色档案。 图像模型为每个造型画一张多视角参考图:歌手的正面、四分之三侧、侧面和背面。
  4. 导演。 导演根据你的创意说明、该场景的歌词和前后场景,为每个场景写一个镜头——画面里有什么、发生了什么、镜头怎么运动、光线如何——并选定歌手在其中穿的造型。歌手出镜时,镜头描述会写明他们唱的词。
  5. 首帧。 每个场景的首帧都依它的造型参考图画出,所以每个场景都从同一个人开始。minimax-h3-music-video 默认跳过这一步,除非你要求(first_frames):它直接依参考图拍摄歌手。
  6. 渲染。 每个场景从它的首帧(或它的造型参考图)和提示词开始渲染,由它对应的那段音乐驱动画面:歌手的口型跟着歌词走,动作和剪辑跟着音乐走。
  7. 拼接。 各场景按顺序拼接到原曲上,所以声音就是你发送的那首歌,原封不动。

第 2、3、5 步就是角色档案,默认开启;mode: "text" 会跳过它们,每个场景只根据提示词渲染。你通过轮询音乐视频对象来跟进进度:它的 status、百分比 progress、各造型及其参考图,以及每个场景的歌词、提示词,渲染完成后还有它自己的片段。

模型#

模型价格生成内容
ltx-music-video每秒歌曲 $0.06,最少按 15 秒计费LTX-2.3,24 fps:1472×832(16:9)、832×1472(9:16)或 1152×1152(1:1)。每个场景约 20–25 秒。
minimax-h3-music-video每秒歌曲 $0.13,最少按 15 秒计费MiniMax H3(FastH3 Omni),24 fps:1344×768(16:9)、768×1344(9:16)或 1024×1024(1:1)。歌手依角色参考图拍摄,所以需要角色档案(mode: "image")。较慢:每个场景约 45 秒,使用 first_frames 时约 70 秒。

两者都接受 5 秒到 6 分钟的歌曲,运行在我们自己的 GPU 上,属于 creative-hosted 渠道组。每个请求都要设置 consent: true,表示接受该模型的条款并对遵守它们负责:ltx-music-video 是 LTX 条款,minimax-h3-music-video 是 MiniMax H3 条款——包括不在欧盟、英国、韩国或美国使用它或它的输出(地域条款)。

制作一支音乐视频#

把歌曲作为文件 song 发送(multipart),或在 song 或 song_url 中提供 http(s) 或 data: URL(JSON)。支持 MP3、WAV、FLAC、OGG 或 M4A,最大 60 MB。

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; she leaves the old town behind and reaches the sea at dawn" \
  -F style="Cinematic 35 mm film, teal and orange, light rain, shallow depth of field" \
  -F character="A woman in her twenties with short black hair, a red leather jacket and silver hoop earrings" \
  -F size=16:9 \
  -F consent=true

请求会立即以 202 返回音乐视频对象;即使你断开连接,任务也会继续运行。完成的 mp4 保留 7 天。

写创意说明#

所有字段都是可选的,每个最多 4,000 个字符。完全不写创意说明时,导演会根据歌词自己构思故事、歌手和画面风格。

字段写什么
story整首歌里从头到尾发生的事。导演会把它分配到各个场景,并按顺序推进;故事里换衣服,就会多一个造型。
style画面风格:胶片还是动画、色彩、光线、年代、镜头。会加到每个场景的提示词里,让整支视频保持同一种风格。
character歌手:脸、发型、体型,以及主造型的服装。选角会逐字保留你给出的每个细节,并补全其余部分。写得越具体越好——"短黑发、红色皮夹克"比"一个很酷的女孩"稳定得多。在 mode: "text" 下,这段文字会原样加到每个场景的提示词里。
locations故事经过的地点。
lyrics歌曲原本的歌词。转写是听出来的,这里提供正确的写法给导演。

language 告诉转写这首歌是什么语言(如 en、zh 或 ja);不填则自动识别。

使用歌曲的一部分#

发送 start 和 end(歌曲中的秒数),只为歌曲的一部分制作视频——副歌、第一分钟。歌曲会在一切开始之前先被截取,所以成片的节拍、场景、歌词和配乐都来自这个片段,而你按片段的时长付费,而不是整首歌。

  • 只发 start 会一直用到歌曲结尾;只发 end 则从 0 开始。
  • 片段长度为 5 秒到 6 分钟(end − start);歌曲本身可以更长。
  • 超过歌曲结尾的 end 会变为歌曲结尾;超过结尾的 start 会在分析后失败,不收费。
  • 对象的 start 和 end 显示实际应用的片段(整首歌时为 null)。场景时间(scenes[n].start)从片段的起点开始计算。
cURL
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 \
  -F start=42.5 -F end=102.5 \
  -F consent=true

Playground 提供带预览的片段截取工具。

角色档案#

默认是 mode: "image":在写任何场景之前,先为歌手选角并画出来,让同一个人唱完每个场景。

  • 选角。 导演给出角色(对象中的 character)和造型(looks):造型 1 是主服装,只有故事需要换衣服时才会多加一个造型——最多四个,通常一两个。
  • 参考图。 image_model(默认 gpt-image-2;你的密钥可用的任意图像模型)为每个造型画一张多视角参考图:正面、四分之三侧、侧面和背面,纯色背景。如果你发送了 character_image——一张歌手的图片,PNG、JPEG 或 WebP,最大 20 MB——造型 1 就由它生成;也可以由已保存角色的参考图生成(character_id,见下文)。其他造型都是在造型 1 参考图的基础上编辑出来的,所以脸会延续下去。每张参考图画好后就可以在 looks[n].url 拿到。
  • 镜头配造型。 导演把每个镜头都安排在某个造型里(scenes[n].look),一个造型会持续一段故事。场景的提示词以角色和该造型的服装开头。
  • 首帧。 每个场景的首帧都依它的造型参考图画出;场景从这一帧开始渲染,由歌曲驱动口型。
  • 使用 minimax-h3-music-video 时,每个场景直接依它的造型参考图拍摄,不需要首帧,提示词也不描述服装:服装由参考图带出。发送 first_frames: true 还会为每个场景画开场的一帧,与参考图一起交给模型,以便更好地控制场景和构图(每个场景多一张图,渲染更慢)。

角色档案需要支持参考图(编辑)的图像模型,例如 gpt-image-2:每个造型和每张首帧都从参考图画出,脸因此能带到每一个镜头。在 mode: "image" 下,只能生成的模型会被拒绝并返回 400;请改用支持参考图的模型,或使用 mode: "text"。

参考图和首帧是你的密钥上的普通图像任务,按该图像模型的价格计费,并列在你的日志中:通常每个造型一张,加上每个场景一张(对象中的 other_usd 汇总了它们)。

内联或已保存#

你可以每次调用都发送歌手,也可以保存一次后传入 ID——两种方式同样完整支持:

  • 一次性: character(文字)和/或 character_image(图片),如上所述。
  • 已保存: character_id = 你账户中的一个已保存角色(POST /v1/characters:名字、描述和一张多视角参考图)。它的参考图用作 character_image,它的描述用作 character,除非你发送了自己的文字。对象中的 character_id 表明用的是哪一个。

character_id 需要 mode: "image",且不能与 character_image 同时使用。

cURL
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 story="She drives through the night to the sea" \
  -F consent=true

mode: "text" 跳过角色档案:不选角、不画图,每个场景只根据提示词渲染,提示词里带着你的 character 文字。更快也更便宜,但歌手可能在场景之间变样。

导演#

director_model 选择为歌手选角并写镜头的聊天模型:你的密钥可用的任意聊天模型,默认 gemini-3.8-flash。它每次调用写八个镜头;这些调用像任何聊天调用一样通过你的密钥,按该模型的价格计费。一个快速、便宜的模型就足够了。如果它没能完成选角或写出镜头,视频会在渲染任何内容之前停止,视频本身不收费。

以下是它收到的全部指令(原文为英文)。选角:

Casting instructions
You cast a music video before it is shot. From the brief and the song, define the singer once, so that a reference photo of them can be made and every scene shows the same person.
- The character: face, age, skin, hair, eyes, build and distinctive features — no clothes, no setting, no action. Keep every detail the brief gives, word for word, and add what is missing.
- The looks: the outfits the singer wears. Look 1 is the main one (from the brief, if it names clothes). Add another look only where the story clearly calls for a change of clothes; at most 4 looks, usually one or two. Write each outfit as "Upper: …" then "Lower: …". Upper is only what a chest-up close-up shows — top, neckline, jacket, jewellery, anything in the hair — and never a length, hem or anything below the waist (a gown is "a crimson satin bodice with thin straps", not "a floor-length gown"). Lower is the rest: trousers, skirt or the gown's length and slit, shoes. Garments, colours, materials; no setting.
- English, concrete words. Never write about yourself or the task.

镜头:

Director instructions
You direct a music video. The song is cut into scenes that end on its beats; for every scene you write the prompt a text-to-video model renders while that part of the song plays. The model hears the music and moves the picture to it — lips, dancing, cuts — so describe the picture only.
- The brief comes first: its story, style, people and places. The people look the same in every scene; don't describe their faces, hair or clothes — that is added to every prompt for you from the character profile.
- Every scene with lyrics is a performance shot: the singer is on screen, mouth visible, and sings that scene's words — write "sings" and the words in double quotes. Keep the singer between a close-up and a medium shot for the whole shot: a gentle pull back or push within that range is fine, a wide shot or a big pull away is not (a face that gets small comes out distorted). Scenes without lyrics are story or atmosphere shots; nobody sings, and wider framing is fine, with people small or turned away.
- Make the camera work varied, like a real music video: change the angle and the move from scene to scene — eye level, low angle, high angle, profile, three-quarter, over-the-shoulder, a lateral tracking shot, an orbit, a handheld follow, a slow crane at eye level, a gentle pull back, a push in now and then. Never the same move two scenes in a row, and not a push in every time.
- In a performance shot the singer's face stays in frame from the first frame to the last: the camera never tilts down to the ground, and the prompt never mentions the ground, puddles, reflections on the pavement, legs, feet or shoes (the video model turns its eye to whatever is named). Describe the light on her, the background behind her and her expression instead.
- Follow the song: quiet parts slower and closer, the chorus with more movement and energy; follow the story from scene to scene.
- Every prompt: what is on screen, what happens (verbs), what the camera does, the light and colour.
- Present tense, concrete words, English; quoted lyrics in the song's own language. At most 70 words a prompt. Never write about yourself, the task or these rules.

渲染前审阅场景#

设置 "auto_render": false 后,视频会在每个场景都有了提示词和首帧、但尚未渲染任何内容时停在 ready 状态。看看参考图和首帧,改写你想改的场景,然后开始渲染:

cURL
# 改写第 3 个场景(索引从 0 开始)
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 silver hoop earrings, wearing a red leather jacket over a black T-shirt. Style: Cinematic 35 mm film. She sings \"we never looked back\" into the wind on an empty pier, the camera orbiting her at dawn."}]}'

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

场景的 prompt 就是它实际渲染的内容:角色和其造型的服装(mode: "text" 下为你的 character 文字),然后是 style 和镜头。你发送的提示词会原样替换它,所以请保留其中对人物的描述。到 ready 时首帧已经画好;改写提示词会改变场景的动作,而不会改变它的首帧。一天内未渲染的方案会被取消,不收任何费用。

耗时#

  • 分析:不到一分钟。
  • 角色档案和首帧:通常几分钟,取决于图像模型。首帧是同时画的。mode: "text" 跳过这一步。
  • 场景:GPU 预热后逐个渲染——ltx-music-video 每个约 20–25 秒,minimax-h3-music-video 每个约 45 秒。一首 3 分钟的歌按 5 秒一个场景(约 36 个场景),ltx-music-video 大约需要 12–15 分钟,minimax-h3-music-video 大约需要 25–30 分钟。
  • 冷启动:没有 GPU 在运行时,再加约一分半钟。

每个场景渲染完成后,它的片段就可以使用(scenes[n].url),所以你可以展示视频逐步成形的过程。

价格#

按歌曲的秒数付费,每支视频最少按 15 秒计费:

模型每秒最低费用(15 秒)一首 3 分半的歌
ltx-music-video$0.06$0.9$12.6
minimax-h3-music-video$0.13$1.95$27.3
minimax-h3-music-video,开启 first_frames$0.2$3$42

导演的调用和角色档案的图片(通常每个造型一张,加上每个场景一张)另行计费,作为各自的聊天和图像调用,按这些模型的价格计费(对象中的 other_usd 汇总了它们)。

  • 开始一支视频时,余额需要足够支付 15 秒的最低费用。
  • 分析之后,歌曲时长确定,整首歌的价格会从余额中冻结(hold_usd)。如果余额不足,视频会以 insufficient_quota 失败,不收任何费用。
  • 完成时,视频的秒数作为一次调用计入你的日志(charge_usd),冻结金额随即释放。
  • 开始后无法取消:视频一旦提交就会运行到结束。如果想先检查,请用 auto_render: false 先审阅方案;停在 ready 的方案可以用 DELETE 免费放弃(已经产生的导演调用和图片仍会计费)。
  • 如果是我们这边出错导致失败,视频本身不收费。

限制#

  • 每个账户同时最多有两支音乐视频在进行中;第三支会被 429 拒绝,直到有一支完成。
  • 歌曲长度 5 秒到 6 分钟,最大 60 MB。更长的歌会在分析后失败,不收费——或者发送其中的一个片段(5 秒到 6 分钟)。
  • scene_seconds 为 2 到 10。剪辑点落在节拍上,所以场景长度会在你选择的值附近浮动。