Pro API: crear personajes para Multi-Ref Vídeo
Un personaje es una character sheet de siete vistas de la misma persona (o criatura), generada a partir de una sola foto
y almacenada con un character_id. Es lo que usa Multi-Ref Vídeo para
reconocer a alguien en un clip: sus vistas guardan el parecido, sin necesidad de entrenamiento.
Face swap también las utiliza para colocar al personaje en el lugar de la persona en tu
propio vídeo.
Los personajes que creaste en la app ya están ahí: misma licencia, misma lista (ver Personajes desde la app). Los lugares, objetos y animales se almacenan del mismo modo, a partir de imágenes que tú proporcionas, y aparecen en los mismos clips (ver Lugares, objetos y animales).
Las siete vistas
| Rol | Vista |
|---|---|
| 1 | Busto de frente, expresión neutra |
| 4 | Cuerpo entero de frente |
| 5 | Cuerpo entero, de espaldas |
| 6 | Cuerpo entero de perfil, el personaje mira hacia la izquierda de la imagen |
| 7 | Primer plano de la cara, de frente |
| 8 | Primer plano del outfit, del pecho a las rodillas |
| 9 | Primer plano de los pies, calzados o descalzos según la ropa |
Cada vista se genera de forma independiente: ninguna se obtiene dando la vuelta a otra. Los roles 2 y 3 (bustos de tres cuartos) ya no se crean desde el 21 de octubre de 2026: un personaje creado antes los conserva, y se pueden seguir leyendo (archivo de una vista, lista views), pero ya no rehacer (400 invalid_role).
Crear un personaje
POST /characters (permiso images). El trabajo es asíncrono.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Campo | Tipo | Qué hace |
|---|---|---|
name | cadena, de 1 a 40 caracteres | El nombre del personaje |
kind | cadena | woman, man, o una criatura descrita en inglés (baby dragon). Establece los pronombres de las instrucciones, nunca "they". |
image_b64 | base64 | La foto: nítida, una sola persona, al menos 1024 px en el lado largo, 12 MB como máximo, JPEG, PNG o WebP |
photo_role | bust (por defecto) o full_body | La foto es un busto (se convierte en la vista 1) o una imagen de cuerpo entero (vista 4) |
outfit | texto en inglés, opcional | Con una foto de busto, la ropa de la vista de cuerpo entero (a red leather jacket and black jeans): la parte inferior del cuerpo, que el busto no muestra. Con una foto de cuerpo entero, manda la foto y la ropa no se aplica |
La respuesta, 202, es el personaje con status pending y cost_estimate. La foto se convierte en la vista de su rol, tal cual (nunca se le cambia la ropa), y el servidor genera las otras seis en 2 a 5 minutos, igual que la app: el cuerpo (espalda, perfil, ropa, pies) parte de la vista de cuerpo entero, el primer plano de la cara parte del busto. Una foto de busto se prolonga en vista de cuerpo entero (con outfit si se da); una foto de cuerpo entero da el busto mediante un encuadre.
Precio: un crédito por vista generada, es decir 6 créditos, con o sin outfit. Una vista que falla no se cobra. POST /characters/quote da el precio de antemano.
Reenviar la misma creación. Si la conexión se corta antes de la respuesta, o si se interrumpe la espera de un agente, el servidor sigue creando el personaje. Vuelve a enviar la misma solicitud (misma foto, name, kind, photo_role y outfit): devuelve el personaje ya creado, con existing: true y un cost_estimate de 0, y no se cobra nada dos veces. Solo crea uno nuevo si todas las vistas generadas del primero fallaron; unas pocas vistas fallidas se rehacen una a una (redo). Si dos solicitudes idénticas llegan en el mismo instante, la segunda recibe 409 character_busy: vuelve a enviarla unos segundos después.
Seguimiento, comprobación y rehecho
GET /characters/{id} devuelve su estado:
status | Significado |
|---|---|
pending | Las vistas se están generando |
ready | Las siete vistas están listas |
partial | Faltan o han fallado algunas vistas |
failed, empty | Ninguna vista utilizable |
{
"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"
}- Comprueba las vistas antes del primer render.
GET /characters/{id}/views/{role}/filedevuelve la imagen. Las vistas de cuerpo entero (4, 5 y 6) se generan en 2K, 1024 x 2048, y el busto y los primeros planos en 832 x 1216 (1216 x 832 para los pies), en PNG, o en JPEG por encima de 2,9 MB. La vista que sale de tu foto conserva su tamaño (2048 px como máximo). Las vistas ya hechas conservan su tamaño; una vista rehecha sale con estos tamaños. Una vista fallida, o un perfil que mira hacia el lado equivocado, arruina el parecido en todos los vídeos. - Rehacer una vista:
POST /characters/{id}/views/{role}/redo, 1 crédito: una nueva generación desde su punto de partida (la vista de cuerpo entero o el busto). La vista que proviene de la foto original no puede rehacerse (photo_view), con o sinoutfit. Una sheet importada en la app como una sola imagen (una lámina entera, conservada tal cual) no se rehace vista por vista (409 single_image_sheet). - Guiar una vista rehecha: añade
instruction(200 caracteres, en inglés) al cuerpo del redo, para un personaje creado a través de la API, o una character sheet añadida a través de la API (de lo contrario409 app_character). Especifica lo que la vista debe mostrar del personaje, como el lado de una prótesis o la presencia de un detalle, nunca otro cambio: ropa, cabello, pose, entorno y expresión se cambian en otro lugar. Escríbela en imperativo (el motor ignora un estado descrito):"Put the robotic arm on her left side only, remove any second robotic arm."En la vista trasera (5), nombra el lado de las dos maneras:"her left arm, which appears on the left side of the image when seen from behind". Mismo precio, 1 crédito. - Subir tu propia imagen para una vista:
PUT /characters/{id}/views/{role}conimage_b64(las mismas reglas que la foto de creación: al menos 1024 px en el lado largo, 12 MB, JPEG, PNG o WebP), para un personaje creado a través de la API, o una character sheet añadida a través de la API (?sheet=). Gratis, no se genera nada. La imagen se guarda tal cual y se trata como una foto real: las vistas rehechas después parten de ella según la regla de la creación (la espalda, el perfil y los primeros planos del outfit y de los pies, de la vista de cuerpo entero; el primer plano de la cara, del busto). - Listar:
GET /charactersdevuelve tus personajes, incluidos los de la app, y el límitemax. - Eliminar:
DELETE /characters/{id}borra el personaje y sus vistas.
En la app (versión 0.8.6 y posteriores): un personaje creado a través de la API o del MCP aparece en la
pantalla Mis personajes de la app, con la misma licencia, con su nombre y sus vistas, igual que los creados en
la app. Una vista rehecha en la app reemplaza la vista en línea, la que lee Multi-Ref Vídeo. Eliminarlo
en la app lo borra aquí también, de forma definitiva (la app pide confirmación antes): un pipeline que conserva un
character_id debe esperar un 404 unknown_character una vez que el personaje haya sido eliminado en la app.
Personajes desde la app
Un personaje creado en la pantalla Mis personajes de la app aparece en GET /characters con origin
app, y funciona en Multi-Ref Vídeo como cualquier otro. En la app, un personaje puede tener varias
character sheets (outfits, estados de ánimo): sheet_id indica cuál se sirve (la más reciente por defecto), sheets
las lista, y ?sheet=<id> solicita otra al leer, al consultar el archivo de una vista y al rehacer una vista.
En un clip Multi-Ref, characters[].sheet_id elige la character sheet. Lleva el name y el kind de su perfil en la app en cuanto la app los ha enviado (app 0.9.1 y posteriores; antes, ambos valen null). Para rehacer una vista de un personaje de la app cuyo kind aún vale null,
indica su kind en el cuerpo.
Voz. has_voice indica si la voz del perfil del personaje está en línea: la app la envía con el personaje, y Face swap y Multi-Ref Vídeo la usan por defecto.
Añadir un outfit a un personaje
POST /characters/{id}/sheets da a un personaje existente una nueva character sheet (un outfit, un look), tanto si se creó a través de la API como en la app, presets de la app incluidos. El personaje conserva sus otras character sheets. La respuesta, 202, es el personaje con la nueva character sheet: su sheet_id (empieza por api-), sheet_name, sheet_outfit, sheet_origin: "api" y cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Campo | Tipo | Qué hace |
|---|---|---|
name | cadena, de 1 a 40 caracteres | El nombre de la character sheet |
outfit | texto en inglés, 700 caracteres como máximo | El outfit que ponerle; obligatorio sin views |
views | objeto, rol "1" o "4" a "9": una imagen en base64 | Vistas ya listas, con las mismas reglas que al subir una vista |
generate | true (por defecto) o false | Generar los roles que faltan, o ninguno |
from_sheet_id | cadena, opcional | Sin views: la character sheet de la que partir |
kind | cadena | Solo para un personaje creado en la app cuyo kind aún vale null en GET /characters, como en la creación |
- Con
views: las vistas que envías se guardan tal cual, gratis. Los roles que faltan se generan, 1 crédito por vista, según la regla de la creación, a partir de la vista de cuerpo entero y del busto enviados; sin ninguno de los dos, como sinviews.generate: falseno genera ninguno. - Sin
views: el outfit se pone sobre la vista de cuerpo entero del personaje (sobre su busto si no tiene;from_sheet_idparte de otra character sheet). El resultado se convierte en la vista de cuerpo entero de la nueva character sheet, y las otras seis vistas parten de él: 7 vistas generadas, 7 créditos.cost_estimateda el precio. Si la sheet de origen (from_sheet_id, o la que se toma por defecto) es una imagen única así, envía la vista 4 (cuerpo entero) o 1 (busto) enviews(409 single_image_sheet). - Usa la character sheet como las demás, con
?sheet=<sheet_id>: enGET /characters/{id}, en el archivo de una vista, enredo(instructionincluida) y en elPUTde una vista. En un clip Multi-Ref,characters[].sheet_idla elige. - Para un personaje de la app, pasa
sheet_id: la character sheet que se sirve por defecto sigue siendo la modificada más recientemente, es decir, la que acabas de añadir. - Borrar una character sheet añadida:
DELETE /characters/{id}/sheets/{sheet_id}borra solo sus vistas. Una character sheet hecha en la app no se borra así (404 unknown_sheet). - En la app: la app de la misma licencia trae la nueva character sheet a la ficha del personaje.
- Errores:
400 outfit_or_views_required(ni outfit ni vistas),400 views_required(generate: falsesin vista),409 source_sheet_empty(ni vista de cuerpo entero ni busto del que partir),409 character_busy.
Lugares, objetos, animales, estilos y outfits
Un sujeto es un lugar (location), un objeto (object: un vehículo, un accesorio, un mueble...), un animal (animal), un estilo (style: imágenes de ambiente cuyo aspecto toma el vídeo) o un outfit (outfit: una prenda que lleva un personaje),
guardado a partir de 1 a 6 imágenes que tú proporcionas (varios ángulos lo hacen más fiel), para poder usarlo de nuevo en
Multi-Ref Vídeo sin tener que describirlo en cada toma. No se genera ninguna imagen, por lo que es gratuito.
Sin imágenes, el servidor también puede generarlo: consulta Generar un sujeto sin imágenes.
POST /subjects (permiso images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Campo | Tipo | Qué hace |
|---|---|---|
type | location, object, animal, style o outfit | Lo que es el sujeto |
name | una sola palabra, de 1 a 40 letras, dígitos o _ | La palabra que se escribe tras @ en el prompt |
description | texto en inglés, 300 caracteres como máximo, opcional | a glossy white futuristic tram with round windows |
images_b64 | de 1 a 6 imágenes en base64 | JPEG, PNG o WebP, al menos 512 px en el lado largo, 12 MB cada una como máximo (28 MB para el cuerpo completo: a partir de ahí, añade las siguientes de una en una) |
La respuesta, 201, es el sujeto: subject_id, type, name, description, origin, sus images
(cada una con una file_url), complete y expires_at.
- Añadir una imagen:
POST /subjects/{id}/imagesconimage_b64(6 como máximo). - Listar:
GET /subjects(?type=locationpara filtrar) devuelve tus sujetos, incluidos los de la Biblioteca de la app (originapp), y el límitemax. Un sujeto de la app cuyas imágenes no están todas sincronizadas aún tienecomplete: false: funciona con las imágenes ya disponibles. - Elementos regalados: Tendre.AI regala elementos listos para usar, con un id fijo (por ejemplo
officiel-red-beetle, un objeto). Cada uno se añade una vez a tu lista la primera vez que la lees (GET /subjects, MCPtendre_subject_list) y no cuenta en el límitemax. Después es un sujeto como los demás: utilizable en Multi-Ref (subject_id), modificable, eliminable; una vez eliminado, no vuelve nunca. - Leer:
GET /subjects/{id}; una imagen:GET /subjects/{id}/images/{n}/file. - Modificar:
PUT /subjects/{id}contype,name,descriptiony/oimages_b64(la lista completa, que reemplaza las imágenes). - Eliminar:
DELETE /subjects/{id}, aquí y en la app.
Un estilo da su aspecto a un clip: su description indica la técnica, en inglés (loose watercolor painting on textured paper), no lo que muestran sus imágenes. Un outfit es una prenda que lleva un personaje. Los estilos y los outfits solo funcionan en Multi-Ref Vídeo, en Ultra.
Para usar un sujeto en un clip, consulta Multi-Ref Vídeo; en una imagen, consulta Crear una imagen.
Generar un sujeto sin imágenes
¿No tienes ninguna imagen a mano? POST /subjects/generate (permiso images) fabrica el sujeto como la ventana «Generar» de los Elementos de la aplicación: una imagen de partida creada a partir de tu descripción (o importada), y luego vistas que parten de ella (otros ángulos, un primer plano, de noche...), cada una retocada desde la imagen de partida para conservar la misma forma. El resultado es un sujeto normal: funciona en Multi-Ref Vídeo y en Crear una imagen, y aparece en la Biblioteca de la aplicación.
| Campo | Tipo | Qué hace |
|---|---|---|
type | object, location, animal, style u outfit | Lo que es el sujeto (un movimiento no se genera) |
name | una palabra, de 1 a 40 letras, cifras o _ | La palabra escrita después de @ en el prompt |
description | texto en inglés, 300 caracteres como máximo | El elemento solo: forma, materiales, colores, detalles, sin fondo ni personaje (a glossy white futuristic tram with round windows). Obligatorio salvo con prompt o start_image_b64 |
prompt | texto en inglés, 2000 caracteres como máximo, opcional | El texto completo de la imagen de partida, en lugar del texto automático sacado de description |
start_image_b64 | imagen en base64, opcional | Una imagen de partida importada (512 px como mínimo), conservada tal cual y gratuita |
views | lista de claves, opcional | Las vistas que quieres, en orden (tabla de abajo) |
count | de 1 a 6, opcional | En lugar de views: el número de imágenes en total, partida incluida (las primeras vistas de la tabla) |
seed | entero, opcional | Seed de la imagen de partida |
quote_only | true | Solo devuelve el precio, no se crea nada |
Vistas por tipo (claves estables), en el formato de salida del tipo:
type | Formato | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (primer plano) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (primer plano) |
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 (primer plano) |
Precio: cada imagen renderizada (la partida y cada vista) cuesta el precio de una imagen (1 crédito); una partida importada es gratuita, y una imagen fallida no se cobra. 6 imágenes como máximo por sujeto, partida incluida. La respuesta, 202, es el sujeto con cost_estimate y 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"]
}Síguelo con GET /subjects/{id} hasta que generation.status deje de ser pending (ready, partial o failed); n es el número de la imagen en images. Las imágenes se hacen una a una: la partida y luego las vistas en orden. Un fallo detiene la serie: las vistas siguientes pasan a failed, sin cobro.
- Añadir vistas:
POST /subjects/{id}/viewsconviews(claves aún no hechas). Con una vista,instructions(en inglés, 1000 caracteres como máximo) sustituye su consigna: di lo que debe mostrar la vista. - Rehacer una vista:
POST /subjects/{id}/views/{key}/redo, coninstructionssi hace falta. La vista vuelve a partir de la imagen de partida y sustituye a la anterior (mismon). - Rehacer la partida:
POST /subjects/{id}/views/start/redo, solo mientras ninguna vista parta de ella (si no,views_exist); una partida importada no se rehace. Las vistas detenidas por el fallo de la partida vuelven a lanzarse después de ella. quote_only: truedevuelve el precio en las tres rutas. Una sola serie a la vez por sujeto (subject_busy).
De principio a fin, un objeto con dos vistas:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }La respuesta, 202, da el subject_id con generation.status pending. Consulta GET /subjects/{id} cada pocos segundos hasta ready y luego usa @Tram con ese subject_id. Tres imágenes (la partida y dos vistas), es decir, tres veces el precio de una imagen.
Almacenamiento
Las vistas del personaje y las imágenes de los sujetos están cifradas (una clave por archivo) y vinculadas a tu
licencia. Las imágenes de los sujetos se conservan tal como las enviaste y se comparten con la Biblioteca de la app. Límites con la
licencia Pro: 50 personajes, incluidos los de la app, y 50 sujetos (lugares, objetos, animales, estilos y outfits en conjunto), contados
por separado (10 con una licencia personal, en la app). Un personaje o sujeto que no se use durante un año
se elimina (expires_at): cada render de Multi-Ref, cada Face swap y cada lectura de una vista o imagen
retrasa esa fecha. La foto que envías para crear un personaje se conserva como la vista de su rol, cifrada, igual que las
vistas generadas. Puedes eliminar cualquiera de ellas en cualquier momento.
A través de un agente (MCP)
Con el servidor MCP, solo tienes que pedir: "crea un personaje a partir de esta foto". El agente
usa tendre_character_create (la foto llega a través de un enlace de subida, un archivo adjunto en ChatGPT,
una imagen generada en la conversación o una dirección pública), te muestra las siete vistas y rehace una
fallida con tendre_character_redo_view, con una instruction cuando la vista necesita orientación, o
la reemplaza con tu propia imagen mediante tendre_character_set_view. tendre_character_get,
tendre_character_list y tendre_character_delete cubren el resto, y tendre_quote da el precio antes.
Para un lugar, un objeto o un animal, proporciona al agente tus imágenes e indícale qué es: utiliza
tendre_subject_create, luego tendre_subject_list, tendre_subject_get y tendre_subject_delete. Sin imágenes, utiliza tendre_subject_generate, luego tendre_subject_add_views y tendre_subject_redo_view para añadir o rehacer una vista.
Después reparte el personaje: consulta Multi-Ref Vídeo.