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). Работа выполняется асинхронно.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
ПолеТипЧто делает
nameстрока, от 1 до 40 символовИмя персонажа
kindстрокаwoman, man или существо, описанное на английском (baby dragon). Задаёт местоимения в инструкциях, никогда "они".
image_b64base64Фото: чёткое, один человек, не менее 1024 пикселей по длинной стороне, не более 12 МБ, JPEG, PNG или WebP
photo_rolebust (по умолчанию) или 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Нет ни одного используемого ракурса
json
{
  "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.

json
{ "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Готовые ракурсы, по тем же правилам, что и при загрузке ракурса
generatetrue (по умолчанию) или 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):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
ПолеТипЧто делает
typelocation, object, animal, style или outfitЧто представляет собой объект
nameодно слово, от 1 до 40 букв, цифр или _Слово, которое пишется после @ в промпте
descriptionтекст на английском, не более 300 символов, необязательноa glossy white futuristic tram with round windows
images_b64от 1 до 6 изображений в base64JPEG, 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 для фильтрации) возвращает твои объекты, включая объекты из Библиотека приложения (origin app), и лимит max. Объект из приложения, чьи изображения ещё не все синхронизированы, имеет complete: false: он используется с уже имеющимися изображениями.
  • Подаренные элементы: Tendre.AI дарит готовые элементы с фиксированным id (например, officiel-red-beetle, предмет). Каждый добавляется в твой список один раз при первом чтении (GET /subjects, MCP tendre_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 Видео и в Создать изображение и появляется в Библиотеке приложения.

ПолеТипЧто делает
typeobject, 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_onlytrueВозвращает только цену, ничего не создаётся

Ракурсы по типу (постоянные ключи), в выходном формате типа:

typeФорматviews
object1024 × 1024three_quarter, side, back, top, detail (крупный план)
location1216 × 832reverse_shot, side, high_angle, night, detail (крупный план)
animal1216 × 832front, three_quarter, back, sitting, lying
style1024 × 1024portrait, landscape, interior, object, animal
outfit832 × 1216three_quarter, side, back, detail (крупный план)

Цена: каждое отрендеренное изображение (старт и каждый ракурс) стоит как одно изображение (1 кредит); импортированный старт бесплатен, а неудачное изображение не списывается. Не более 6 изображений на объект, включая старт. Ответ, 202, это объект с cost_estimate и generation:

json
"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).

От начала до конца, предмет с двумя ракурсами:

http
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 Видео.

Windows · Mac · облако или локально

Генерируй приватно. Уже сегодня вечером.

Скачай tendre.AI бесплатно и генерируй без ограничений, приватно, на своём собственном GPU.

OS Windows 10/11GPU NVIDIA 8ГБ+VRAM 12ГБ рекомендуетсяДиск 20ГБ

Mac с чипом Apple (M1 или новее): macOS 13 или новее. Intel Mac: macOS 12 или новее, всё работает онлайн.

Для локальной генерации изображений на Mac нужен M4 с 24 ГБ памяти, либо M2 или M3 Pro, Max или Ultra с 24 ГБ. Если у тебя устройство послабее, всё работает онлайн через кредиты. Ретушь и видео на Mac пока тоже работают только онлайн.

Всё о tendre.AI для Mac

Нет видеокарты NVIDIA? Начни на 100% в облаке: 5 бесплатных изображений и 1 бесплатное видео каждый день. Карта NVIDIA (от 8 ГБ) открывает безлимитную локальную генерацию.