Справочник API

Эндпоинты видеокадров

Все эндпоинты /v1/videos/shots, /v1/videos/joins и /v1/videos/projects — рендер кадров по промпту с отмеченными персонажами и сценами, бесплатная склейка готовых кадров в одно видео и хранение раскадровок в проектах.

Кадр — это несколько секунд видео, созданных по промпту и изображениям: отметьте в промпте своих сохранённых персонажей и сцены — @Mia_Wong, @[Night Café] или @chr_… — и каждый отмеченный станет референсным изображением. Люди сохраняют лица, причёски и одежду со своих изображений, место — свой вид со своего изображения, а кадр получает собственный звук и озвученные диалоги. Рендерьте каждый кадр отдельно, а затем бесплатно склейте готовые кадры в одно видео.

Эндпоинты находятся под https://lovelyrouter.com/v1/videos. Аутентифицируйтесь API-ключом в виде Authorization: Bearer $LOVELY_API_KEY (Аутентификация). Модель — minimax-h3-video на базе MiniMax H3, она работает на условиях MiniMax H3: каждый кадр указывает consent: true. Попробуйте без кода в песочнице.

Теги и изображения#

Изображения выбирает промпт. Перечислите персонажей и сцены, которые может использовать кадр, в characters и scenes (можно передать всю библиотеку проекта); каждый, кого отмечает промпт, становится изображением в порядке первого упоминания.

@handle — имя, где пробелы заменены на _: Mia Wong → @Mia_Wong. Регистр не важен.
@[Full Name] — любое имя как есть: @[Night Café].
@chr_… / @scn_… — id, если у двоих одинаковые имена.

Слова в двойных кавычках — это реплика, которую произносит персонаж, отмеченный последним перед ней: @Leo looks up: "You came.". Не описывайте одежду и лица — их передают изображения. Кадр принимает от 1 до 9 изображений; промпт без тегов использует единственного указанного персонажа (и единственную указанную сцену), если он ровно один.

Голоса#

Отмеченный персонаж с голосом приносит его с собой: его реплики звучат этим голосом (тембр, высота и манера; но не слова и не фоновый звук образца). Голоса приносят первые 3 озвученных персонажа кадра в порядке изображений — модель принимает не больше 3 аудиореференсов; остальных озвучивает сама модель. Встроенный персонаж тоже может иметь voice: id сохранённого голоса (voice_…) или URL образца http(s) / data:. Голоса не влияют на цену.

Кто есть кто: чистка промпта#

Видеомодели нужно знать, о ком каждое слово, поэтому местоимения — he, she, his, her, they (и 他, 她, 彼, 彼女) — вне диалога до неё не доходят. Перед рендером кадра:

Один персонаж: каждое местоимение заменяется тегом этого персонажа (her coat → @Mia's coat), сразу и бесплатно.
Два и больше: модель чата (sweep_model, по умолчанию gemini-3.8-flash) переписывает промпт так, чтобы каждый человек каждый раз назывался своим тегом. Ответ проверяется — те же теги, те же реплики слово в слово, ни одного оставшегося местоимения — и при неудаче генерируется ещё раз; если проверка снова не пройдена, промпт рендерится в том виде, в каком вы его отправили. Из-за чистки кадр никогда не завершается ошибкой.

Отрендеренный промпт хранится в поле кадра prompt_rendered (null, если ничего не изменилось); prompt остаётся таким, каким вы его отправили. Вызов чата оплачивается как обычный запрос к чату по тому же ключу и показывается как other_usd; в цену кадра он не входит. Отправьте sweep: false, чтобы рендерить промпт ровно в том виде, как он написан. Слова в двойных кавычках никогда не меняются.

Цены#

Кадр оплачивается за каждую отрендеренную секунду: модель рендерит по сетке из 17k+5 фреймов при 24 fps (не меньше 124 фреймов), поэтому кадр на 5 с рендерится 5,17 с, а кадр на 10 с — 10,13 с; это rendered_seconds в объекте кадра. Цена — $0.13 за отрендеренную секунду с одним изображением плюс $0.06 за секунду за каждое дополнительное изображение: кадр на 5 с с двумя персонажами и сценой стоит ($0.13 + 2 × $0.06) × 5,17 с. Цена резервируется при отправке и списывается, когда кадр готов; неудачные и отменённые кадры ничего не стоят. Склейки и проекты бесплатны.

Объект кадра#

Атрибуты

idstring

shot_ и 24 символа.

objectstring

Всегда video.shot.

statusstring

queued, in_progress, completed, failed или cancelled.

progressinteger

0–100, оценка во время рендера.

promptstring

Промпт в том виде, в каком вы его отправили.

prompt_renderedstring | null

Промпт после чистки, если она что-то изменила.

secondsnumber

Запрошенная длительность, 5–15.

rendered_secondsnumber

Отрендеренная и оплаченная длительность.

sizestring

16:9, 9:16 или 1:1; width и height — размер в пикселях после завершения.

referencesarray

Отмеченные персонажи и сцены в порядке изображений: {picture, kind, name, id} (id равен null для встроенных). Затем пришедшие с ними голоса по порядку: {audio, kind, name, id} (audio = 1–3).

project_idstring | null

Проект, к которому относится кадр.

urlstring | null

Файл mp4, когда статус completed. Хранится 7 дней.

hold_usdcharge_usd` number

Зарезервированная сумма и списание после расчёта.

other_usdnumber

Вызовы чата при чистке, оплачиваемые как чат по тому же ключу (не входят в hold_usd / charge_usd).

errorobject | null

{code, message} при ошибке.

Объект кадра

{
  "id": "shot_8c1f0a7d3b9e4c2a6f5d1e0b",
  "object": "video.shot",
  "model": "minimax-h3-video",
  "status": "completed",
  "progress": 100,
  "project_id": "prj_2a9e7c1b5d3f4e6a8c0b1d2e",
  "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
  "prompt_rendered": null,
  "seconds": 5,
  "rendered_seconds": 5.167,
  "size": "16:9",
  "width": 1344,
  "height": 768,
  "seed": null,
  "language": "en",
  "style": null,
  "references": [
    { "picture": 1, "kind": "scene", "name": "Night Café", "id": "scn_5b2d9e0c1a7f4b3e8d6c2a1f" },
    { "picture": 2, "kind": "character", "name": "Leo", "id": "chr_1e4b7d0a9c3f2e5b8a6d0c1f" },
    { "picture": 3, "kind": "character", "name": "Mia Wong", "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2" },
    { "audio": 1, "kind": "character", "name": "Mia Wong", "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2" }
  ],
  "url": "https://lovelyrouter.com/v1/videos/shots/shot_8c1f0a7d3b9e4c2a6f5d1e0b/content",
  "hold_usd": 1.291667,
  "charge_usd": 1.291667,
  "other_usd": 0,
  "error": null,
  "powered_by": "MiniMax H3"
}

Создание кадра#

POST/v1/videos/shots

Запускает кадр и возвращает 202 с объектом кадра (200, если он завершился в пределах wait). Отправляйте JSON или multipart, где characters / scenes передаются текстовыми полями с JSON.

Параметры тела запроса

modelstringОбязательно

minimax-h3-video.

promptstringОбязательно

Что происходит, с отмеченными персонажами и сценами. До 4000 символов.

consentbooleanОбязательно

true означает принятие условий MiniMax H3.

charactersarray

Id сохранённых персонажей (chr_…) или встроенные персонажи: {name, image, description?}, где image — URL http(s) или data:, а в multipart — имя файловой части. Встроенные персонажи могут добавлять voice: id сохранённого голоса или URL образца http(s) / data: (см. Голоса).

scenesarray

Id сохранённых сцен (scn_…) или встроенные {name, image, description?}.

secondsnumberПо умолчанию 5

5–15.

sizestringПо умолчанию 16:9

16:9, 9:16 или 1:1.

languagestring

Язык, на котором звучат реплики, например en, zh, ja. По умолчанию английский.

stylestring

Визуальный стиль, например warm 35mm film. По умолчанию живая съёмка.

seedinteger

0–2147483647, для воспроизводимых результатов.

sweepbooleanПо умолчанию true

false рендерит промпт как написан, без чистки.

sweep_modelstringПо умолчанию gemini-3.8-flash

Модель чата, которая называет всех по именам, когда в кадре два персонажа или больше. Подойдёт любая модель чата, доступная вашему ключу.

project_idstring

Ваш проект, в который нужно поместить кадр.

waitinteger

0–300 секунд, в течение которых запрос удерживается до завершения (также ?wait=).

Shell

curl https://lovelyrouter.com/v1/videos/shots \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "minimax-h3-video",
    "consent": true,
    "prompt": "In @[Night Café], @Leo looks up as @Mia_Wong sits down: \"You came.\"",
    "characters": ["chr_3b9e1f0c7a2d4e58b6c1a9f2", "chr_1e4b7d0a9c3f2e5b8a6d0c1f"],
    "scenes": ["scn_5b2d9e0c1a7f4b3e8d6c2a1f"],
    "seconds": 5
  }'

Получение, список и удаление кадров#

GET/v1/videos/shots/{id}

Объект кадра. ?wait=1–300 удерживает запрос, пока кадр не завершится или не истечёт время. GET /v1/videos/shots/{id}/content отдаёт mp4 (запросы Range поддерживаются). GET /v1/videos/shots возвращает список ваших кадров, сначала новые: ?limit=1–100, ?before=<shot id> для следующей страницы, ?project_id= для кадров одного проекта.

DELETE /v1/videos/shots/{id} убирает кадр из вашего списка и удаляет его файл. Кадр в очереди отменяется бесплатно; кадр, который уже рендерится, всё равно будет завершён и оплачен.

cURL

curl "https://lovelyrouter.com/v1/videos/shots/SHOT_ID?wait=60" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

curl https://lovelyrouter.com/v1/videos/shots/SHOT_ID/content \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o shot.mp4

Склейка кадров#

POST/v1/videos/joins

Склеивает ваши готовые кадры в одно видео в указанном порядке, каждый со своим звуком. Бесплатно. У кадров должен быть один размер, и они должны быть моложе 7 дней. Возвращает 202 с объектом склейки: {id: "join_…", object: "video.join", status, shots, size, seconds, width, height, url, charge_usd: 0}. GET /v1/videos/joins/{id} (с ?wait=), /content, GET /v1/videos/joins и DELETE работают так же, как для кадров.

Параметры тела запроса

shotsarrayОбязательно

2–50 id кадров в порядке воспроизведения.

project_idstring

Ваш проект, в который нужно поместить склейку.

cURL

curl https://lovelyrouter.com/v1/videos/joins \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"shots": ["shot_8c1f0a7d3b9e4c2a6f5d1e0b", "shot_0d2e4f6a8b1c3e5d7f9a0b2c"]}'

Проекты#

POST/v1/videos/projects

Проект хранит раскадровку: имя и ваш собственный JSON-документ (doc) — песочница сохраняет туда размер, стиль, язык, кадры, персонажей и сцены. Бесплатно; до 100 на аккаунт. POST принимает {name?, doc?} и возвращает 201 с {id: "prj_…", object: "video.project", name, doc, created_at, updated_at}.

Запрос	Что делает
`GET /v1/videos/projects`	Ваши проекты, сначала недавно изменённые, без `doc` (`?limit`, `?after`).
`GET /v1/videos/projects/{id}`	Один проект вместе с `doc`.
`PATCH /v1/videos/projects/{id}`	`{name?, doc?}`; `doc` заменяется целиком, до 200 КБ.
`DELETE /v1/videos/projects/{id}`	Удаляет проект; его кадры остаются.

cURL

curl https://lovelyrouter.com/v1/videos/projects \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Night café", "doc": {"size": "16:9", "shots": []}}'

Ошибки#

Ошибки используют стандартное тело ошибки. Ошибки промпта содержат code и затронутые tags.

Статус	`code` / `type`	Причина
`400`	`unknown_tags`	Промпт отмечает имя, которого нет в `characters` или `scenes`; они перечислены в `error.tags`.
`400`	`ambiguous_tag`	Отмеченное имя есть у двух указанных персонажей или сцен: отметьте нужный по id.
`400`	`no_pictures` / `too_many_pictures`	Нет ни одного изображения или их больше 9.
`400`	`consent_required`	`consent` не равен `true`.
`400`	`mixed_sizes`	Склейка кадров разных размеров.
`400`	`invalid_request_error`	Поле вне допустимого диапазона, нечитаемое изображение, изображения общим объёмом больше 24 МБ, склейка кадров, которые не завершились или устарели.
`402`	`insufficient_quota`	Баланса не хватает на резерв.
`404`	`not_found_error`	Неизвестная модель, кадр, склейка, проект, персонаж или сцена либо объект другого аккаунта.
`429`	`rate_limit_exceeded`	На вашем аккаунте уже пять кадров или склеек в очереди или в рендере.

← Назад

Эндпоинты персонажей

Справочник API

Эндпоинты замены в видео

Справочник API