Music videos

POST /v1/videos/music turns a song into a music video. You send the audio and a short brief — the story, the look, the people — and get back one mp4 the length of the song, with the song as its soundtrack. Try it without code in the playground. Every field and response is in the API reference.

How it works#

1. Analysis. We find the song's beats and cut it into scenes that end on a beat, about scene_seconds long each (5 s by default); the lengths are evened out over the song so the last scene is never a stub, and the video ends exactly when the song does. The lyrics are transcribed scene by scene.
2. Casting. A chat model of your choice — the director — reads your brief and the lyrics and defines the singer once: a character description (face, hair, body, no clothes) and the looks (outfits) the story needs, at most four.
3. Character profile. An image model draws a turnaround reference sheet for every look: the singer from the front, three-quarter, side and back.
4. Directing. The director writes one shot per scene from your brief, the scene's lyrics and the scenes around it — what is on screen, what happens, what the camera does, the light — and picks the look the singer wears in it. When the singer is on screen, the shot says what they sing.
5. First frames. Each scene's first frame is drawn from its look's sheet, so every scene starts on the same person. minimax-h3-music-video skips this unless you ask for it (first_frames): it films the singer from the sheet itself.
6. Rendering. Each scene is rendered from its first frame (or its look's sheet) and its prompt, with its part of the song driving the picture: a singer's lips follow the words, and movement and cuts follow the music.
7. Joining. The scenes are joined in order over the original song, so the sound is the track you sent, untouched.

Steps 2, 3 and 5 are the character profile, on by default; mode: "text" skips them and renders every scene from its prompt alone. You follow it all by polling the music video object: its status, a progress percentage, the looks with their sheets, and every scene with its lyrics, its prompt and, once rendered, its own clip.

Models#

Both take songs from 5 seconds to 6 minutes and run on our own GPUs in the creative-hosted channel group. Every request sets consent: true, accepting the model's terms and the responsibility for following them: the LTX terms for ltx-music-video, the MiniMax H3 terms for minimax-h3-music-video — including not using it, or its outputs, in the EU, the UK, South Korea or the US (territory).

Make a music video#

Send the song as the file song (multipart), or as an http(s) or data: URL in song or song_url (JSON). MP3, WAV, FLAC, OGG or M4A, up to 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

The request answers 202 at once with the music video object; the job keeps running if you disconnect. The finished mp4 is kept for 7 days.

Write the brief#

Every field is optional and up to 4,000 characters. With no brief at all, the director invents a story, a singer and a look from the lyrics.

language tells the transcription which language the song is in (such as en, zh or ja); without it the language is detected.

Use part of a song#

Send start and end (seconds into the song) to make the video for one part of it — the chorus, the first minute. The song is cut before anything else, so the beats, the scenes, the lyrics and the soundtrack of the finished video are the slice's, and you pay for the slice's length, not the song's.

• start alone runs to the end of the song; end alone starts at 0.
• The slice is 5 seconds to 6 minutes long (end − start); the song itself may be longer.
• An end past the song's end becomes its end; a start past it fails after analysis, without charge.
• The object shows the slice as applied in start and end (null for the whole song). Scene times (scenes[n].start) count from the slice's start.

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

The playground has a slicer with a preview for this.

The character profile#

mode: "image" is the default: before any scene is written, the singer is cast and drawn, so the same person sings every scene.

• Casting. The director answers with the character (character in the object) and the looks (looks): look 1 is the main outfit, and another look is added only where the story calls for a change of clothes — at most four, usually one or two.
• Sheets. image_model (default gpt-image-2; any image model your key can use) draws a turnaround reference sheet per look: front, three-quarter, side and back on a plain background. Look 1 is made from character_image when you send one — a picture of your singer, PNG, JPEG or WebP up to 20 MB — or from the sheet of a saved character (character_id, below). Every other look is an edit of look 1's sheet, so the face carries over. Each sheet is at looks[n].url as soon as it is drawn.
• Shots in a look. The director writes every shot in one of the looks (scenes[n].look) and keeps a look for a stretch of the story. The scene's prompt starts with the character and that look's outfit.
• First frames. Each scene's first frame is drawn from its look's sheet; the scene is rendered from that frame, with the song driving the lips.
• With minimax-h3-music-video each scene is filmed from its look's sheet itself, with no first frame, and its prompt doesn't describe the clothes: the sheet carries them. Send first_frames: true to also draw each scene's opening frame and give it to the model with the sheet, for more control over the setting and framing (one more picture per scene, slower renders).

The character profile needs an image model that accepts reference images (edits), such as gpt-image-2: every look and every first frame is drawn from the sheet, so the face carries into each one. A model that only generates is refused with 400 in mode: "image"; use one that takes references, or mode: "text".

The sheets and first frames are ordinary image jobs on your key, billed at the image model's price and listed in your logs: typically one picture per look plus one per scene (other_usd in the object adds them up).

Inline or saved#

Send the singer with each call, or save them once and pass the id — both are first-class:

• One-off: character (text) and/or character_image (a picture), as above.
• Saved: character_id = a saved character of your account (POST /v1/characters: a name, a description and a turnaround sheet). Its sheet is used as character_image, its description as character unless you send your own text. The object's character_id says which one was used.

character_id needs mode: "image" and can't be combined with character_image.

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" skips the profile: no casting, no pictures, and every scene is rendered from its prompt alone, with your character text in it. Faster and cheaper, but the singer can change from scene to scene.

The director#

director_model picks the chat model that casts the singer and writes the shots: any chat model your key can use, default gemini-3.8-flash. It writes eight shots per call; its calls go through your key like any chat call, billed at that model's price. A fast, inexpensive model is plenty. If it fails to cast the singer or write the shots, the video stops before anything renders and nothing is charged for the video.

These are its whole instructions. For casting:

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.

For the shots:

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.

Review the scenes before rendering#

With "auto_render": false the video stops at status ready once every scene has its prompt and its first frame, before anything is rendered. Look at the sheets and frames, rewrite any scene you like, then start the render:

# Rewrite scene 3 (indexes start at 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."}]}'

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

A scene's prompt is exactly what it renders: the character and its look's outfit (with mode: "text", your character text), the style, then the shot. A prompt you send replaces it as it is, so keep the description of the people in it. The first frames are already made at ready; a rewritten prompt changes the scene's motion, not its first frame. A plan that isn't rendered within a day is cancelled; nothing is charged for it.

Timing#

• Analysis: under a minute.
• Character profile and first frames: usually a few minutes, depending on the image model. The first frames are drawn side by side. mode: "text" skips this.
• Scenes: rendered one after another once a GPU is warm — about 20–25 seconds each with ltx-music-video, about 45 seconds with minimax-h3-music-video. A 3-minute song at 5-second scenes (about 36 scenes) takes roughly 12–15 minutes with ltx-music-video and 25–30 minutes with minimax-h3-music-video.
• Cold start: add about a minute and a half when no GPU is running.

Each scene's clip is available as soon as it is rendered (scenes[n].url), so you can show the video building up.

Pricing#

You pay per second of the song, at least 15 seconds per video:

The director's calls and the pictures of the character profile (typically one per look plus one per scene) are billed separately, as their own chat and image calls at those models' prices (other_usd in the object adds them up).

• Starting a video needs a balance that covers the 15-second minimum.
• After analysis, when the song's length is known, the price of the whole song is held from your balance (hold_usd). If your balance doesn't cover it, the video fails with insufficient_quota and nothing is charged.
• When it finishes, the video's seconds are billed as one call in your logs (charge_usd) and the hold is released.
• No cancelling once it starts: a video runs to the end once it is sent. Review the plan first with auto_render: false if you want to check it; a plan at ready can be discarded with DELETE for free (the director's calls and pictures already made are still billed).
• If it fails on our side, nothing is charged for the video.

Limits#

• Two music videos in progress per account; a third is refused with 429 until one finishes.
• Songs from 5 seconds to 6 minutes, up to 60 MB. A longer song fails after analysis, without charge — or send a slice of it (5 seconds to 6 minutes).
• scene_seconds from 2 to 10. Cuts land on beats, so scenes vary around the length you choose.