Справочник API

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

Все эндпоинты /v1/characters и /v1/scenes — сохраняйте персонажа (имя, описание и лист разворота) или сцену (место и её изображение), получайте их список, читайте, обновляйте и удаляйте, скачивайте изображения и используйте их в музыкальных клипах, заменах персонажа и видеокадрах.

Сохранённый персонаж — это человек, которого вы хотите использовать снова: имя, описание (лицо, волосы, телосложение, одежда, которую он обычно носит) и лист разворота — тот же человек спереди, в три четверти, сбоку и со спины, а под этим крупные планы лица с шестью выражениями, всё на одном изображении, — плюс, по желанию, фото, из которого он был сделан, и голос. Передавайте его id как character_id в музыкальные клипы и замены персонажа, вместо того чтобы каждый раз отправлять изображение.

Сохранённые персонажи необязательны. Каждый видеоэндпоинт по-прежнему принимает изображение и текст прямо в запросе, так что разовому вызову сохранённый персонаж вообще не нужен.

Эндпоинты находятся под https://lovelyrouter.com/v1/characters. Аутентифицируйтесь API-ключом в виде Authorization: Bearer $LOVELY_API_KEY (Аутентификация). Хранить персонажей бесплатно, они видны только вашему аккаунту и хранятся, пока вы их не удалите; в аккаунте может быть до 100 персонажей.

Объект персонажа#

Атрибуты

idstring

Уникальный id: chr_ и 24 символа.

objectstring

Всегда character.

namestring

Как вы называете персонажа, до 80 символов.

descriptionstring

Кто этот человек, в ваших формулировках: лицо, волосы, тело и обычная одежда. До 4 000 символов; может быть пустым.

sheet_urlstring

Лист разворота. См. Скачивание изображений. Значение параметра v меняется, когда вы заменяете лист.

photo_urlstring | null

Исходное фото, если вы его сохранили.

voiceobject | null

Голос персонажа в видеокадрах: id (сохранённый голос), description (как он был создан, или null) и audio_url (образец). null, если у персонажа нет голоса. См. Голос для персонажа.

created_atinteger

Unix-время в секундах.

updated_atinteger

Unix-время последнего изменения в секундах.

The character object

{
  "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "object": "character",
  "name": "Mara",
  "description": "A woman in her thirties with a long black braid, brown eyes, freckles and an athletic build; a green bomber jacket over a grey hoodie, black cargo trousers and white sneakers.",
  "sheet_url": "https://lovelyrouter.com/v1/characters/chr_3b9e1f0c7a2d4e58b6c1a9f2/sheet?v=mh2x7k1c",
  "photo_url": null,
  "voice": {
    "id": "voice_7d2a9c4e1b6f3a8d0c5e2b1f",
    "description": "A low, calm alto, unhurried",
    "audio_url": "https://lovelyrouter.com/v1/audio/voices/voice_7d2a9c4e1b6f3a8d0c5e2b1f/audio"
  },
  "created_at": 1792915200,
  "updated_at": 1792915200
}

Создание персонажа#

POST/v1/characters

Сохраняет персонажа и возвращает 201 с объектом персонажа. Отправляйте multipart (sheet и photo как файлы) или JSON (те же поля как URL http(s) или data:). Чтобы сохранить лист, созданный через API изображений, вместо файла передайте id задания изображения как sheet_image_job.

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

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

До 80 символов.

descriptionstring

Лицо, волосы, тело и обычная одежда, до 4 000 символов. Музыкальные клипы используют его как описание character, если вы не отправили своё.

sheetfile or stringОбязательно

Лист разворота: PNG, JPEG или WebP до 10 МБ, файлом или URL http(s) / data: (также sheet_url). Чтобы взять его из задания изображения, используйте вместо этого sheet_image_job.

sheet_image_jobstring

Id задания изображения (img_…) вашего аккаунта в статусе succeeded: его первое изображение становится листом. Отправляйте либо его, либо sheet.

photofile or string

Фото, из которого сделан лист, PNG, JPEG или WebP до 10 МБ (также photo_url или photo_image_job). Хранится для вашего архива; видео используют лист.

voice_idstring

Один из ваших сохранённых голосов (voice_…), который получит персонаж.

voicefile or string

Вместо этого — новый образец голоса: WAV, MP3, OGG/Opus, FLAC, M4A или WebM до 10 МБ, файлом или URL http(s) / data:. Он сохраняется как один из ваших голосов с именем персонажа и привязывается к нему. Требует consent.

voice_transcriptstring

Что произносится в образце (до 1 000 символов) — с ним голос клонируется лучше.

consentboolean

true подтверждает, что образец — ваш голос или у вас есть разрешение говорящего на его использование. Обязателен вместе с voice.

voice_descriptionstring

Как был создан голос, например описание, которое вы дали qwen3-tts (до 1 000 символов). Хранится вместе с голосом для вашего архива.

Shell

curl https://lovelyrouter.com/v1/characters \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name=Mara \
  -F description="A woman in her thirties with a long black braid, brown eyes and freckles; a green bomber jacket" \
  -F sheet=@mara-sheet.png

Список персонажей#

GET/v1/characters

Ваши персонажи, сначала новые.

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

limitintegerПо умолчанию 20

От 1 до 100.

afterstring

Id персонажа: вывести тех, кто сохранён до него (следующая страница).

cURL

curl "https://lovelyrouter.com/v1/characters?limit=50" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [{ "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2", "object": "character", "name": "Mara" }],
  "first_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "last_id": "chr_3b9e1f0c7a2d4e58b6c1a9f2",
  "has_more": false
}

Получение персонажа#

GET/v1/characters/{id}

Возвращает объект персонажа; 404 для id, который вам не принадлежит.

cURL

curl https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Обновление персонажа#

PATCH/v1/characters/{id}

Изменяет отправленные поля и возвращает объект персонажа. Принимает JSON или multipart, как и Создание. Уже готовые видео сохраняют лист, с которым были сделаны.

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

namestring

Новое имя.

descriptionstring

Новое описание (пустая строка очищает его).

sheetfile or string

Новый лист или sheet_image_job.

photofile

Новое фото (или photo_image_job); null удаляет его.

voice_idstring or null

Привязать один из ваших сохранённых голосов; null отвязывает голос (сам сохранённый голос остаётся).

voicefile

Новый образец (с voice_transcript и consent, как при Создании); null отвязывает.

voice_descriptionstring or null

Как был создан голос. Новый привязанный голос получает описание, отправленное вместе с ним, или никакого.

cURL

curl -X PATCH https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"description": "A woman in her thirties with a long black braid, now in a red raincoat"}'

Скачивание изображений#

GET/v1/characters/{id}/sheet

Изображение листа с его собственным типом содержимого; GET /v1/characters/{id}/photo — фото (404, если его нет). Прочитать их может только ваш ключ.

cURL

curl https://lovelyrouter.com/v1/characters/CHARACTER_ID/sheet \
  -H "Authorization: Bearer $LOVELY_API_KEY" -o sheet.png

Удаление персонажа#

DELETE/v1/characters/{id}

Удаляет персонажа и его изображения. Уже готовые видео с ним не затрагиваются.

cURL

curl -X DELETE https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{ "id": "chr_3b9e1f0c7a2d4e58b6c1a9f2", "object": "character.deleted", "deleted": true }

Голос для персонажа#

У персонажа может быть голос — один из ваших сохранённых голосов. В видеокадре персонаж с голосом произносит свои реплики этим голосом — с его тембром, высотой и манерой, но не его словами.

Загрузите голос: отправьте образец как voice (с voice_transcript и consent: true) при создании или обновлении персонажа. Он сохраняется как голос с именем персонажа.
Создайте голос: сделайте образец с помощью qwen3-tts по описанию и реплике, которую сказал бы персонаж (instructions = описание, input = реплика, без voice), сохраните его через POST /v1/audio/voices, затем привяжите как voice_id — с описанием в voice_description.

voice_id: null (или voice: null) отвязывает голос. При удалении персонажа его голос сохраняется; при удалении голоса он отвязывается от всех персонажей.

cURL

# Link a saved voice to a character.
curl -X PATCH https://lovelyrouter.com/v1/characters/CHARACTER_ID \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"voice_id": "voice_7d2a9c4e1b6f3a8d0c5e2b1f", "voice_description": "A low, calm alto, unhurried"}'

Сохранённые сцены#

POST/v1/scenes

Сохранённая сцена — это место, которое вы хотите снова использовать в видеокадрах: имя, описание места и его изображение. Сцены работают так же, как персонажи, под https://lovelyrouter.com/v1/scenes; изображение называется image (файл, URL http(s) / data: или image_image_job), а фото нет. До 100 на аккаунт, помимо персонажей; бесплатно.

Объект сцены: {id: "scn_…", object: "scene", name, description, image_url, created_at, updated_at}.

Запрос	Что делает
`POST /v1/scenes`	`name` (обязательно, до 80 символов), `description`, `image` (обязательно). Возвращает `201`.
`GET /v1/scenes`	Ваши сцены, сначала новые (`?limit`, `?after`).
`GET /v1/scenes/{id}`	Одна сцена.
`PATCH /v1/scenes/{id}`	`name`, `description`, `image`.
`GET /v1/scenes/{id}/image`	Изображение (только для вашего ключа).
`DELETE /v1/scenes/{id}`	Удаляет сцену и её изображение.

cURL

curl https://lovelyrouter.com/v1/scenes \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F name="Night Café" \
  -F description="A small café at night, rain on the windows, warm lamps" \
  -F image=@cafe.jpg

Использование персонажа#

Передавайте character_id там, где отправили бы изображение. Поля для передачи прямо в запросе продолжают работать, так что выбирайте для каждого вызова:

Эндпоинт	Разовый вызов (прямо в запросе)	С сохранённым персонажем
`POST /v1/videos/music`	`character` (текст) и/или `character_image` (файл или URL)	`character_id`: его лист — референсное изображение, его описание — текст `character`, если вы не отправили свой. Не вместе с `character_image` и только с `mode: "image"`.
`POST /v1/videos`	`input_reference` (файл или URL)	`character_id`: его лист — референсное изображение. Отправляйте ровно одно из двух.
`POST /v1/videos/shots`	`characters` / `scenes`: объекты `{name, image}`	`characters` / `scenes`: id; промпт отмечает их тегами (`@Mara`), каждый отмеченный становится референсным изображением.

Объект музыкального клипа и объект видео показывают character_id, с которым они сделаны (null для вызовов с данными в запросе).

cURL

# A one-off music video: the picture sent with the call.
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 -F consent=true \
  -F character="A woman with a long black braid" -F character_image=@mara.png

# The same with a saved character.
curl https://lovelyrouter.com/v1/videos/music \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=ltx-music-video -F song=@song.mp3 -F consent=true \
  -F character_id=chr_3b9e1f0c7a2d4e58b6c1a9f2

Ошибки#

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

Статус	`type`	Причина
`400`	`invalid_request_error`	Нет `name` или `sheet`, слишком длинное поле, изображение не в формате PNG, JPEG или WebP или больше 10 МБ, задание изображения не ваше или не завершилось успешно, либо уже сохранено 100 персонажей. `voice_id`, не относящийся к вашим голосам, `voice`, который не является аудио или больше 10 МБ, или отправлен без `consent`, либо уже сохранено 100 голосов.
`401`	`authentication_error`	API-ключ отсутствует или недействителен.
`404`	`not_found_error`	Неизвестный или удалённый персонаж либо персонаж другого аккаунта — в том числе как `character_id` в запросе на видео.

← Назад

Эндпоинты музыкальных клипов

Справочник API

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

Справочник API