Справочник 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

Когда файлы будут удалены: через 7 дней после completed_at.

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

Исполнитель в том виде, в каком его задал режиссёр: лицо, волосы, телосложение, без одежды. null при mode: "text" и пока кастинг не завершён.

looksarray

Образы (наряды) исполнителя, не больше четырёх; пусто при mode: "text" и пока кастинг не завершён.

scenesarray

По одной записи на сцену, по порядку; пусто, пока песня не проанализирована.

errorobject | null

Для клипов в статусе failed и cancelled: code и message (в нём сказано, было ли что-то списано).

urlstring | null

Готовый mp4, после перехода в completed. См. Скачивание клипа.

hold_usdnumber

Сумма, зарезервированная на балансе: цена всей песни, от окончания анализа до расчёта по клипу. До этого — 0.

charge_usdnumber | null

Сколько стоил клип, после расчёта. До этого — null.

other_usdnumber

Сколько на данный момент стоили вызовы чата режиссёра и вызовы генерации изображений для референс-листов и первых кадров. Они оплачиваются как отдельные вызовы и не входят в charge_usd.

powered_bystring

LTX или MiniMax H3.

Объект музыкального клипа

{
  "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 (то же самое в виде URL http(s) или data:). Исполнителя можно передать прямо в вызове (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 МБ. Файл или URL http(s) / data: (также принимается как 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: 1472×832, 832×1472 или 1152×1152 с ltx-music-video; 1344×768, 768×1344 или 1024×1024 с minimax-h3-music-video.

modestringПо умолчанию image

image: профиль персонажа — режиссёр проводит кастинг исполнителя и до четырёх образов, image_model рисует референс-лист для каждого образа, а каждая сцена начинается с первого кадра, нарисованного по листу её образа (minimax-h3-music-video: каждая сцена снимается прямо по листу; см. first_frames). text: без изображений, каждая сцена только по своему промпту; недоступно с minimax-h3-music-video, которой нужен профиль.

image_modelstringПо умолчанию gpt-image-2

Только при mode: "image". Модель изображений, доступная вашему ключу и принимающая референсные изображения (edits), например 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 МБ, файлом или по URL (также character_image_url).

character_idstring

Только при mode: "image". Сохранённый персонаж вашего аккаунта: его лист используется так же, как character_image, а описание — как 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

# With a saved character instead of the inline character text and picture:
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

Ответ

{
  "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. Long polling: ответ приходит, как только сменится этап или будет готова очередная сцена, либо когда истечёт время. Клип в статусе 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"

Ответ

{
  "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 дней; 409 до перехода в completed, 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. 404, пока лист не нарисован, а также при mode: "text".

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"

Ответ (удалено)

{ "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 минут, `character_image`, `character_id` или `first_frames` без `mode: "image"`, `mode: "text"` с `minimax-h3-music-video`, одновременно `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). Ни в одном из этих случаев за клип ничего не списывается.