Музыкальные клипы

POST /v1/videos/music превращает песню в музыкальный клип. Вы отправляете аудио и короткий бриф — сюжет, визуальный стиль, людей — и получаете один mp4 длиной в песню, где песня служит саундтреком. Попробуйте без кода в песочнице. Все поля и ответы описаны в справочнике API.

Как это работает#

1. Анализ. Мы находим биты песни и нарезаем её на сцены, которые заканчиваются на бите, длиной примерно scene_seconds каждая (по умолчанию 5 с); длины выравниваются по всей песне, чтобы последняя сцена не оказалась обрубком, а клип заканчивается ровно вместе с песней. Текст песни расшифровывается по сценам.
2. Кастинг. Выбранная вами чат-модель — режиссёр — читает бриф и текст песни и один раз описывает исполнителя: описание персонажа (лицо, волосы, телосложение, без одежды) и образы (наряды), которые нужны сюжету, не больше четырёх.
3. Профиль персонажа. Модель изображений рисует для каждого образа референсный лист с разворотом: исполнитель спереди, в три четверти, сбоку и со спины.
4. Режиссура. Режиссёр пишет по одному кадру на сцену, исходя из брифа, текста этой сцены и соседних сцен, — что в кадре, что происходит, что делает камера, какой свет — и выбирает образ, в котором исполнитель в ней появляется. Когда исполнитель в кадре, в описании кадра указано, что он поёт.
5. Первые кадры. Первый кадр каждой сцены рисуется по листу её образа, поэтому каждая сцена начинается с одного и того же человека. minimax-h3-music-video пропускает этот шаг, если вы не попросите (first_frames): она снимает исполнителя прямо по листу.
6. Рендеринг. Каждая сцена рендерится по своему первому кадру (или по листу своего образа) и своему промпту, а её фрагмент песни управляет картинкой: губы исполнителя следуют за словами, движение и монтажные склейки — за музыкой.
7. Склейка. Сцены склеиваются по порядку поверх исходной песни, так что звук — это отправленный вами трек без изменений.

Шаги 2, 3 и 5 составляют профиль персонажа, он включён по умолчанию; mode: "text" пропускает их и рендерит каждую сцену только по её промпту. За всем процессом вы следите, опрашивая объект музыкального клипа: его status, процент progress, образы с их листами и каждую сцену с её текстом, промптом и, после рендеринга, собственным клипом.

Модели#

Обе модели принимают песни длиной от 5 секунд до 6 минут и работают на наших собственных GPU в группе каналов creative-hosted. В каждом запросе задаётся consent: true: так вы принимаете условия модели и ответственность за их соблюдение — условия LTX для ltx-music-video, условия MiniMax H3 для minimax-h3-music-video, включая запрет использовать её или её результаты в ЕС, Великобритании, Южной Корее и США (территория).

Создание музыкального клипа#

Отправьте песню как файл song (multipart) или как URL http(s) либо data: в song или song_url (JSON). MP3, WAV, FLAC, OGG или M4A, до 60 МБ.

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 дней.

Как написать бриф#

Все поля необязательны, каждое — до 4000 символов. Если брифа нет совсем, режиссёр сам придумывает сюжет, исполнителя и образ по тексту песни.

language сообщает расшифровке, на каком языке песня (например, en, zh или ja); без него язык определяется автоматически.

Клип на часть песни#

Передайте start и end (секунды от начала песни), чтобы сделать клип на одну её часть — припев, первую минуту. Песня обрезается до всего остального, поэтому биты, сцены, текст и саундтрек готового клипа берутся из этого фрагмента, и вы платите за длину фрагмента, а не всей песни.

• Только start — фрагмент идёт до конца песни; только end — начинается с 0.
• Длина фрагмента (end − start) — от 5 секунд до 6 минут; сама песня может быть длиннее.
• end за пределами песни становится её концом; start за её пределами приводит к ошибке после анализа, без списания.
• Объект показывает применённый фрагмент в start и end (null для всей песни). Время сцен (scenes[n].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

В песочнице для этого есть нарезчик с предпросмотром.

Профиль персонажа#

mode: "image" используется по умолчанию: до того как будет написана хоть одна сцена, исполнителя подбирают и рисуют, поэтому каждую сцену поёт один и тот же человек.

• Кастинг. Режиссёр возвращает персонажа (character в объекте) и образы (looks): образ 1 — основной наряд, а другой образ добавляется только там, где сюжет требует смены одежды, — не больше четырёх, обычно один или два.
• Листы. image_model (по умолчанию gpt-image-2; подойдёт любая модель изображений, доступная вашему ключу) рисует для каждого образа референсный лист с разворотом: спереди, в три четверти, сбоку и со спины на однотонном фоне. Образ 1 создаётся из character_image, если вы его отправили, — снимка вашего исполнителя, PNG, JPEG или WebP до 20 МБ, — или из листа сохранённого персонажа (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 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. За один вызов она пишет восемь кадров; её вызовы идут через ваш ключ, как любой чат-вызов, и тарифицируются по цене этой модели. Быстрой недорогой модели вполне достаточно. Если ей не удаётся подобрать исполнителя или написать кадры, клип останавливается до начала рендеринга и за клип ничего не списывается.

Ниже — её инструкции целиком. Для кастинга:

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.

Для кадров:

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, когда у каждой сцены есть промпт и первый кадр, до начала рендеринга. Посмотрите листы и кадры, перепишите любые сцены, затем запустите рендеринг:

# 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"

prompt сцены — это ровно то, что она рендерит: персонаж и наряд её образа (с mode: "text" — ваш текст character), style, затем сам кадр. Отправленный вами промпт заменяет его как есть, поэтому сохраняйте в нём описание людей. К статусу ready первые кадры уже готовы; переписанный промпт меняет движение в сцене, но не её первый кадр. План, не отрендеренный в течение суток, отменяется; за него ничего не списывается.

Сроки#

• Анализ: меньше минуты.
• Профиль персонажа и первые кадры: обычно несколько минут, в зависимости от модели изображений. Первые кадры рисуются параллельно. mode: "text" пропускает этот шаг.
• Сцены: рендерятся одна за другой, как только GPU прогрет, — около 20–25 секунд каждая с ltx-music-video, около 45 секунд с minimax-h3-music-video. Трёхминутная песня со сценами по 5 секунд (около 36 сцен) занимает примерно 12–15 минут с ltx-music-video и 25–30 минут с minimax-h3-music-video.
• Холодный старт: добавьте около полутора минут, если ни один GPU не запущен.

Клип каждой сцены доступен сразу после рендеринга (scenes[n].url), так что можно показывать, как клип собирается.

Цены#

Вы платите за секунду песни, не менее 15 секунд за клип:

Вызовы режиссёра и изображения профиля персонажа (обычно одно на образ плюс одно на сцену) тарифицируются отдельно, как собственные чат-вызовы и вызовы изображений по ценам этих моделей (other_usd в объекте суммирует их).

• Для запуска клипа нужен баланс, покрывающий минимум в 15 секунд.
• После анализа, когда длина песни известна, стоимость всей песни резервируется на вашем балансе (hold_usd). Если баланса не хватает, клип завершается ошибкой insufficient_quota и ничего не списывается.
• По завершении секунды клипа списываются одним вызовом в ваших логах (charge_usd), а резерв снимается.
• После старта отменить нельзя: отправленный клип выполняется до конца. Если хотите проверить план, сначала просмотрите его с auto_render: false; план в статусе ready можно бесплатно отбросить через DELETE (уже сделанные вызовы режиссёра и изображения всё равно тарифицируются).
• Если сбой произошёл на нашей стороне, за клип ничего не списывается.

Ограничения#

• Два музыкальных клипа в работе на учётную запись; третий отклоняется с 429, пока один из них не завершится.
• Песни от 5 секунд до 6 минут, до 60 МБ. Более длинная песня приводит к ошибке после анализа, без списания, — или отправьте её фрагмент (от 5 секунд до 6 минут).
• scene_seconds от 2 до 10. Склейки приходятся на биты, поэтому длина сцен колеблется вокруг выбранного значения.