Pro API: создание персонажей для Multi-Ref Видео
Персонаж: это набор из семи ракурсов одного человека (или существа), созданный из одной фотографии
и хранящийся под character_id. Именно это использует Multi-Ref Видео, чтобы
узнать человека в клипе: его ракурсы несут сходство без какого-либо обучения.
Face swap тоже их использует, чтобы поместить персонажа вместо человека в твоём
собственном видео.
Персонажи, которых ты создал в приложении, уже здесь: та же лицензия, тот же список (см. Персонажи из приложения). Места, объекты и животные хранятся так же, из изображений, которые ты загружаешь, и участвуют в тех же клипах (см. Места, объекты и животные).
Семь ракурсов
| Роль | Ракурс |
|---|---|
| 1 | Бюст анфас, нейтральное выражение |
| 4 | В полный рост анфас |
| 5 | В полный рост, со спины |
| 6 | В полный рост в профиль, персонаж смотрит влево на изображении |
| 7 | Крупный план лица, анфас |
| 8 | Крупный план одежды, от груди до колен |
| 9 | Крупный план ступней, в обуви или босых, в зависимости от одежды |
Каждый ракурс генерируется отдельно: ни один не получается зеркальным отражением другого. Роли 2 и 3 (бюсты в три четверти) с 21 октября 2026 года больше не создаются: у персонажа, созданного раньше, они остаются, их можно читать (файл ракурса, список views), но нельзя повторить (400 invalid_role).
Создать персонажа
POST /characters (разрешение images). Работа выполняется асинхронно.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Поле | Тип | Что делает |
|---|---|---|
name | строка, от 1 до 40 символов | Имя персонажа |
kind | строка | woman, man или существо, описанное на английском (baby dragon). Задаёт местоимения в инструкциях, никогда "они". |
image_b64 | base64 | Фото: чёткое, один человек, не менее 1024 пикселей по длинной стороне, не более 12 МБ, JPEG, PNG или WebP |
photo_role | bust (по умолчанию) или full_body | Фото является бюстом (становится ракурсом 1) или снимком в полный рост (ракурс 4) |
outfit | текст на английском, необязательно | При фото бюста: одежда для ракурса в полный рост (a red leather jacket and black jeans), то есть нижняя часть тела, которую бюст не показывает. При фото в полный рост решает фото, и одежда не надевается |
Ответ, 202, это персонаж со status pending и cost_estimate. Фото становится ракурсом своей роли и сохраняется как есть (его никогда не переодевают), а сервер генерирует остальные шесть за 2-5 минут, так же, как приложение: тело (спина, профиль, одежда, ступни) строится на основе ракурса в полный рост, крупный план лица на основе бюста. Фото бюста достраивается до ракурса в полный рост (в одежде из outfit, если она указана); фото в полный рост даёт бюст кадрированием.
Цена: один кредит за каждый сгенерированный ракурс, то есть 6 кредитов, с outfit или без. Неудавшийся ракурс не тарифицируется. POST /characters/quote даёт цену заранее.
Повторная отправка того же создания. Если соединение оборвалось до ответа или ожидание агента прервалось, сервер продолжает создавать персонажа. Отправь тот же запрос ещё раз (то же фото, name, kind, photo_role и outfit): он вернёт уже созданного персонажа, с existing: true и cost_estimate, равным 0, и ничего не спишется дважды. Новый персонаж создаётся, только если все сгенерированные ракурсы первого не удались; отдельные неудачные ракурсы переделываются по одному (redo). Если два одинаковых запроса приходят в один и тот же момент, второй получает 409 character_busy: отправь его снова через несколько секунд.
Отслеживание, проверка, повтор
GET /characters/{id} возвращает его состояние:
status | Значение |
|---|---|
pending | Ракурсы создаются |
ready | Все семь ракурсов готовы |
partial | Некоторые ракурсы отсутствуют или не удались |
failed, empty | Нет ни одного используемого ракурса |
{
"character_id": "chr_8f3a...",
"name": "Lea",
"kind": "woman",
"origin": "api",
"status": "ready",
"progress": { "ready": 7, "total": 7 },
"views": [
{ "role": 1, "name": "bust_front", "status": "ready", "file_url": "https://api.tendre.ai/pro/v1/characters/chr_8f3a.../views/1/file" }
],
"expires_at": "2026-10-19T18:02:11.000Z"
}- Проверяй ракурсы перед первым рендером.
GET /characters/{id}/views/{role}/fileвозвращает изображение. Ракурсы в полный рост (4, 5 и 6) генерируются в 2K, 1024 x 2048, а бюст и крупные планы в 832 x 1216 (1216 x 832 для ступней), в PNG или в JPEG, если файл больше 2,9 МБ. Ракурс из твоего фото сохраняет свой размер (не больше 2048 px). Уже готовые ракурсы сохраняют свой размер; повторённый ракурс выходит в этих размерах. Неудавшийся ракурс или профиль, смотрящий в неверную сторону, испортит сходство в каждом видео. - Повторить ракурс:
POST /characters/{id}/views/{role}/redo, 1 кредит: новая генерация от его исходной точки (ракурса в полный рост или бюста). Ракурс, полученный из оригинальной фотографии, повторить нельзя (photo_view), сoutfitили без. Sheet, импортированный в приложение одним изображением (целый лист, сохранённый как есть), не переделывается по ракурсам (409 single_image_sheet). - Направить повторный ракурс: добавь
instruction(200 символов, на английском) в тело запроса redo для персонажа, созданного через API, или для character sheet, добавленного через API (иначе409 app_character). Это уточняет, что именно ракурс должен показывать о персонаже, например расположение протеза или наличие детали, но не что-то другое: одежда, причёска, поза, обстановка и выражение лица меняются в другом месте. Пиши в повелительном наклонении (движок игнорирует описание состояния):"Put the robotic arm on her left side only, remove any second robotic arm."На ракурсе со спины (5) называй сторону двумя способами:"her left arm, which appears on the left side of the image when seen from behind". Та же цена, 1 кредит. - Загрузить собственное изображение для ракурса:
PUT /characters/{id}/views/{role}сimage_b64(те же правила, что и для фото при создании: не менее 1024 пикселей по длинной стороне, 12 МБ, JPEG, PNG или WebP) для персонажа, созданного через API, или для character sheet, добавленного через API (?sheet=). Бесплатно, ничего не генерируется. Изображение сохраняется как есть и считается настоящей фотографией: ракурсы, повторяемые впоследствии, строятся на его основе по правилу создания (спина, профиль и крупные планы одежды и ступней на основе ракурса в полный рост, крупный план лица на основе бюста). - Список:
GET /charactersвозвращает твоих персонажей, включая персонажей из приложения, и лимитmax. - Удалить:
DELETE /characters/{id}удаляет персонажа и его ракурсы.
В приложении (версия 0.8.6 и выше): персонаж, созданный через API или MCP, отображается на экране
Мои персонажи приложения, на той же лицензии, с его именем и ракурсами, как и созданные в приложении.
Ракурс, повторённый в приложении, заменяет онлайн-ракурс, который читает Multi-Ref Видео. Удаление в приложении стирает его и здесь, безвозвратно (приложение сначала запрашивает подтверждение): пайплайн, хранящий character_id, должен ожидать 404 unknown_character, если персонаж был удалён в приложении.
Персонажи из приложения
Персонаж, созданный на экране Мои персонажи в приложении, появляется в GET /characters с origin
app и участвует в Multi-Ref Видео, как и любой другой. В приложении у персонажа может быть несколько
character sheet (одежда, настроения): sheet_id указывает, какой из них используется (по умолчанию самый последний), sheets
их перечисляет, а ?sheet=<id> запрашивает другой при чтении, при получении файла ракурса и при повторе ракурса.
В клипе Multi-Ref characters[].sheet_id выбирает нужный character sheet. Он получает name и kind из своего профиля в приложении, как только приложение их отправило (приложение 0.9.1 и новее; до этого оба равны null). Чтобы повторить ракурс персонажа из приложения, у которого kind всё ещё равен null,
укажи его kind в теле запроса.
Голос. has_voice показывает, есть ли онлайн голос из профиля персонажа: приложение отправляет его вместе с персонажем, а Face swap и Multi-Ref Видео используют его по умолчанию.
Добавить образ персонажу
POST /characters/{id}/sheets даёт существующему персонажу новый character sheet (образ, наряд), созданному через API или в приложении, включая пресеты приложения. Персонаж сохраняет свои другие character sheet. Ответ, 202, это персонаж с новым character sheet: его sheet_id (начинается с api-), sheet_name, sheet_outfit, sheet_origin: "api" и cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Поле | Тип | Что делает |
|---|---|---|
name | строка, от 1 до 40 символов | Название character sheet |
outfit | текст на английском, не более 700 символов | Образ, который нужно надеть; обязателен без views |
views | объект, роль "1" или от "4" до "9": изображение в base64 | Готовые ракурсы, по тем же правилам, что и при загрузке ракурса |
generate | true (по умолчанию) или false | Сгенерировать недостающие роли или ни одной |
from_sheet_id | строка, необязательно | Без views: character sheet, от которого отталкиваться |
kind | строка | Только для персонажа, созданного в приложении, у которого kind всё ещё равен null в GET /characters, как при создании |
- С
views: присланные ракурсы сохраняются как есть, бесплатно. Недостающие роли генерируются, 1 кредит за ракурс, по правилу создания, на основе присланных ракурса в полный рост и бюста; если нет ни того, ни другого, как безviews.generate: falseне генерирует ни одного. - Без
views: образ надевается на ракурс персонажа в полный рост (на бюст, если такого нет;from_sheet_idберёт за основу другой character sheet). Результат становится ракурсом в полный рост нового character sheet, а шесть остальных ракурсов строятся на его основе: 7 сгенерированных ракурсов, 7 кредитов.cost_estimateпоказывает цену. Если исходный sheet (from_sheet_idили используемый по умолчанию) является таким единым изображением, передайте ракурс 4 (в полный рост) или 1 (бюст) вviews(409 single_image_sheet). - Используй character sheet как остальные, с
?sheet=<sheet_id>: вGET /characters/{id}, при получении файла ракурса, вredo(включаяinstruction) и вPUTракурса. В клипе Multi-Ref его выбираетcharacters[].sheet_id. - Для персонажа из приложения передавай
sheet_id: по умолчанию по-прежнему используется последний изменённый character sheet, то есть только что добавленный. - Удалить добавленный character sheet:
DELETE /characters/{id}/sheets/{sheet_id}удаляет только его ракурсы. Character sheet, сделанный в приложении, так не удаляется (404 unknown_sheet). - В приложении: приложение с той же лицензией переносит новый character sheet в профиль персонажа.
- Ошибки:
400 outfit_or_views_required(нет ни образа, ни ракурсов),400 views_required(generate: falseбез ракурса),409 source_sheet_empty(нет ни ракурса в полный рост, ни бюста, которые можно взять за основу),409 character_busy.
Места, объекты, животные, стили и наряды
Объект: это место (location), предмет (object: транспортное средство, реквизит, мебель...),
животное (animal), стиль (style: атмосферные изображения, визуальный облик которых перенимает видео) или наряд (outfit: одежда, которую носит персонаж), сохранённое из 1-6 изображений, которые ты загружаешь (несколько ракурсов
делают его более точным), чтобы использовать его снова в Multi-Ref Видео
без повторного описания в каждом кадре. Изображения не генерируются, поэтому это бесплатно.
Без изображений сервер может и сгенерировать его: см. Сгенерировать объект без изображений.
POST /subjects (разрешение images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Поле | Тип | Что делает |
|---|---|---|
type | location, object, animal, style или outfit | Что представляет собой объект |
name | одно слово, от 1 до 40 букв, цифр или _ | Слово, которое пишется после @ в промпте |
description | текст на английском, не более 300 символов, необязательно | a glossy white futuristic tram with round windows |
images_b64 | от 1 до 6 изображений в base64 | JPEG, PNG или WebP, не менее 512 пикселей по длинной стороне, не более 12 МБ каждое (28 МБ для всего тела: если больше, добавляй следующие по одному) |
Ответ, 201, это объект: subject_id, type, name, description, origin, его images
(каждое с file_url), complete и expires_at.
- Добавить изображение:
POST /subjects/{id}/imagesсimage_b64(не более 6). - Список:
GET /subjects(?type=locationдля фильтрации) возвращает твои объекты, включая объекты из Библиотека приложения (originapp), и лимитmax. Объект из приложения, чьи изображения ещё не все синхронизированы, имеетcomplete: false: он используется с уже имеющимися изображениями. - Подаренные элементы: Tendre.AI дарит готовые элементы с фиксированным id (например,
officiel-red-beetle, предмет). Каждый добавляется в твой список один раз при первом чтении (GET /subjects, MCPtendre_subject_list) и не учитывается в лимитеmax. Дальше это такой же объект, как остальные: его можно использовать в Multi-Ref (subject_id), изменять и удалять; после удаления он больше не возвращается. - Чтение:
GET /subjects/{id}; одно изображение:GET /subjects/{id}/images/{n}/file. - Изменить:
PUT /subjects/{id}сtype,name,descriptionи/илиimages_b64(полный список, который заменяет все изображения). - Удалить:
DELETE /subjects/{id}, здесь и в приложении.
Стиль задаёт визуальный облик клипа: его description описывает технику, на английском (loose watercolor painting on textured paper), а не то, что изображено на его картинках. Наряд: одежда, которую носит персонаж. Стили и наряды работают только в Multi-Ref Видео, в Ультра.
Чтобы добавить объект в клип, см. Multi-Ref Видео; в изображение, см. Создать изображение.
Сгенерировать объект без изображений
Нет изображения под рукой? POST /subjects/generate (право images) создаёт объект так же, как окно «Создать» в Элементах приложения: стартовое изображение по твоему описанию (или импортированное), затем ракурсы, которые из него исходят (другие углы, крупный план, ночью...), каждый ретушируется из стартового изображения, чтобы сохранить ту же форму. Получается обычный объект: он работает в Multi-Ref Видео и в Создать изображение и появляется в Библиотеке приложения.
| Поле | Тип | Что делает |
|---|---|---|
type | object, location, animal, style или outfit | Что это за объект (движение не генерируется) |
name | одно слово, от 1 до 40 букв, цифр или _ | Слово после @ в промпте |
description | текст на английском, не более 300 символов | Сам элемент: форма, материалы, цвета, детали, без фона и без персонажа (a glossy white futuristic tram with round windows). Обязателен, кроме случаев с prompt или start_image_b64 |
prompt | текст на английском, не более 2000 символов, необязателен | Полный текст стартового изображения вместо автоматического текста из description |
start_image_b64 | изображение в base64, необязательно | Импортированное стартовое изображение (не менее 512 px), сохраняется как есть и бесплатно |
views | список ключей, необязателен | Нужные ракурсы по порядку (таблица ниже) |
count | от 1 до 6, необязательно | Вместо views: число изображений всего, включая старт (первые ракурсы таблицы) |
seed | целое число, необязательно | Seed стартового изображения |
quote_only | true | Возвращает только цену, ничего не создаётся |
Ракурсы по типу (постоянные ключи), в выходном формате типа:
type | Формат | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (крупный план) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (крупный план) |
animal | 1216 × 832 | front, three_quarter, back, sitting, lying |
style | 1024 × 1024 | portrait, landscape, interior, object, animal |
outfit | 832 × 1216 | three_quarter, side, back, detail (крупный план) |
Цена: каждое отрендеренное изображение (старт и каждый ракурс) стоит как одно изображение (1 кредит); импортированный старт бесплатен, а неудачное изображение не списывается. Не более 6 изображений на объект, включая старт. Ответ, 202, это объект с cost_estimate и generation:
"generation": {
"status": "pending",
"start": { "status": "ready", "origin": "generated", "n": 1 },
"views": [{ "key": "three_quarter", "status": "ready", "n": 2 }, { "key": "detail", "status": "pending" }],
"available_views": ["three_quarter", "side", "back", "top", "detail"]
}Следи за ним через GET /subjects/{id}, пока generation.status не перестанет быть pending (ready, partial или failed); n это номер изображения в images. Изображения идут по одному: старт, затем ракурсы по порядку. Сбой останавливает серию: следующие ракурсы переходят в failed, без списания.
- Добавить ракурсы:
POST /subjects/{id}/viewsсviews(ключи, которых ещё нет). С одним ракурсомinstructions(на английском, не более 1000 символов) заменяет его задание: скажи, что должен показать ракурс. - Переделать ракурс:
POST /subjects/{id}/views/{key}/redo, при необходимости сinstructions. Ракурс снова исходит из стартового изображения и заменяет предыдущий (тот жеn). - Переделать старт:
POST /subjects/{id}/views/start/redo, только пока из него не исходит ни один ракурс (иначеviews_exist); импортированный старт не переделывается. Ракурсы, остановленные сбоем старта, запускаются снова после него. quote_only: trueвозвращает цену на всех трёх маршрутах. Одна серия за раз на объект (subject_busy).
От начала до конца, предмет с двумя ракурсами:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Ответ, 202, даёт subject_id с generation.status pending. Опрашивай GET /subjects/{id} каждые несколько секунд до ready, затем используй @Tram с этим subject_id. Три изображения (старт и два ракурса), то есть трижды цена одного изображения.
Хранилище
Ракурсы персонажей и изображения объектов зашифрованы (один ключ на файл) и привязаны к твоей
лицензии. Изображения объектов хранятся в том виде, в каком ты их отправил, и доступны в Библиотека приложения. Лимиты по Pro-лицензии: 50 персонажей, включая персонажей из приложения, и 50 объектов (места, предметы, животные, стили и наряды вместе), считаются отдельно (10 при персональной лицензии, в приложении). Персонаж или объект, не использованный в течение одного года, удаляется (expires_at): каждый рендер Multi-Ref, каждый Face swap и каждое чтение ракурса или изображения отодвигают эту дату. Фото, которое ты отправляешь для создания персонажа, хранится как ракурс его роли, зашифрованным, как и сгенерированные ракурсы. Ты можешь удалить любой из них в любое время.
Через агента (MCP)
С помощью MCP-сервера достаточно написать: "сделай персонажа из этой фотографии". Агент
использует tendre_character_create (фото поступает через ссылку для загрузки, прикреплённый файл в ChatGPT,
изображение, сгенерированное в разговоре, или публичный адрес), показывает тебе семь ракурсов и повторяет
неудавшийся через tendre_character_redo_view, с instruction, когда ракурс требует направления, или
заменяет его твоим собственным изображением через tendre_character_set_view. tendre_character_get,
tendre_character_list и tendre_character_delete охватывают остальное, а tendre_quote заранее сообщает цену.
Для места, объекта или животного передай агенту свои изображения и скажи, что это такое: он использует
tendre_subject_create, затем tendre_subject_list, tendre_subject_get и tendre_subject_delete. Без изображений он использует tendre_subject_generate, затем tendre_subject_add_views и tendre_subject_redo_view, чтобы добавить или переделать ракурс.
Затем добавь персонажа в клип: см. Multi-Ref Видео.