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

RolVista
1Busto de frente, expresión neutra
4Cuerpo entero de frente
5Cuerpo entero, de espaldas
6Cuerpo entero de perfil, el personaje mira hacia la izquierda de la imagen
7Primer plano de la cara, de frente
8Primer plano del outfit, del pecho a las rodillas
9Primer 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.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
CampoTipoQué hace
namecadena, de 1 a 40 caracteresEl nombre del personaje
kindcadenawoman, man, o una criatura descrita en inglés (baby dragon). Establece los pronombres de las instrucciones, nunca "they".
image_b64base64La foto: nítida, una sola persona, al menos 1024 px en el lado largo, 12 MB como máximo, JPEG, PNG o WebP
photo_rolebust (por defecto) o full_bodyLa foto es un busto (se convierte en la vista 1) o una imagen de cuerpo entero (vista 4)
outfittexto en inglés, opcionalCon 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:

statusSignificado
pendingLas vistas se están generando
readyLas siete vistas están listas
partialFaltan o han fallado algunas vistas
failed, emptyNinguna vista utilizable
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"
}
  • Comprueba las vistas antes del primer render. GET /characters/{id}/views/{role}/file devuelve 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 sin outfit. 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 contrario 409 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} con image_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 /characters devuelve tus personajes, incluidos los de la app, y el límite max.
  • 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.

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
CampoTipoQué hace
namecadena, de 1 a 40 caracteresEl nombre de la character sheet
outfittexto en inglés, 700 caracteres como máximoEl outfit que ponerle; obligatorio sin views
viewsobjeto, rol "1" o "4" a "9": una imagen en base64Vistas ya listas, con las mismas reglas que al subir una vista
generatetrue (por defecto) o falseGenerar los roles que faltan, o ninguno
from_sheet_idcadena, opcionalSin views: la character sheet de la que partir
kindcadenaSolo 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 sin views. generate: false no genera ninguno.
  • Sin views: el outfit se pone sobre la vista de cuerpo entero del personaje (sobre su busto si no tiene; from_sheet_id parte 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_estimate da 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) en views (409 single_image_sheet).
  • Usa la character sheet como las demás, con ?sheet=<sheet_id>: en GET /characters/{id}, en el archivo de una vista, en redo (instruction incluida) y en el PUT de una vista. En un clip Multi-Ref, characters[].sheet_id la 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: false sin 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):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
CampoTipoQué hace
typelocation, object, animal, style o outfitLo que es el sujeto
nameuna sola palabra, de 1 a 40 letras, dígitos o _La palabra que se escribe tras @ en el prompt
descriptiontexto en inglés, 300 caracteres como máximo, opcionala glossy white futuristic tram with round windows
images_b64de 1 a 6 imágenes en base64JPEG, 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}/images con image_b64 (6 como máximo).
  • Listar: GET /subjects (?type=location para filtrar) devuelve tus sujetos, incluidos los de la Biblioteca de la app (origin app), y el límite max. Un sujeto de la app cuyas imágenes no están todas sincronizadas aún tiene complete: 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, MCP tendre_subject_list) y no cuenta en el límite max. 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} con type, name, description y/o images_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.

CampoTipoQué hace
typeobject, location, animal, style u outfitLo que es el sujeto (un movimiento no se genera)
nameuna palabra, de 1 a 40 letras, cifras o _La palabra escrita después de @ en el prompt
descriptiontexto en inglés, 300 caracteres como máximoEl 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
prompttexto en inglés, 2000 caracteres como máximo, opcionalEl texto completo de la imagen de partida, en lugar del texto automático sacado de description
start_image_b64imagen en base64, opcionalUna imagen de partida importada (512 px como mínimo), conservada tal cual y gratuita
viewslista de claves, opcionalLas vistas que quieres, en orden (tabla de abajo)
countde 1 a 6, opcionalEn lugar de views: el número de imágenes en total, partida incluida (las primeras vistas de la tabla)
seedentero, opcionalSeed de la imagen de partida
quote_onlytrueSolo devuelve el precio, no se crea nada

Vistas por tipo (claves estables), en el formato de salida del tipo:

typeFormatoviews
object1024 × 1024three_quarter, side, back, top, detail (primer plano)
location1216 × 832reverse_shot, side, high_angle, night, detail (primer plano)
animal1216 × 832front, three_quarter, back, sitting, lying
style1024 × 1024portrait, landscape, interior, object, animal
outfit832 × 1216three_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:

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"]
}

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}/views con views (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, con instructions si hace falta. La vista vuelve a partir de la imagen de partida y sustituye a la anterior (mismo n).
  • 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: true devuelve 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:

http
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.

Windows · Mac · Nube o local

Genera en privado. Esta noche.

Descarga tendre.AI gratis y genera sin límites, de forma privada, en tu propia GPU.

OS Windows 10/11GPU NVIDIA 8GB+VRAM 12GB recomendadoDisco 20GB

Mac con chip Apple (M1 o posterior): macOS 13 o posterior. Mac Intel: macOS 12 o posterior, todo funciona en línea.

La generación de imágenes local en Mac necesita un M4 con 24 GB de memoria, o un M2 o M3 Pro, Max o Ultra con 24 GB. Por debajo de eso, todo se ejecuta online con créditos. El retoque y el video se ejecutan online en Mac por ahora.

Todo sobre tendre.AI para Mac

¿No tienes GPU NVIDIA? Empieza 100% en la nube: 5 imágenes y 1 vídeo gratis cada día. Una tarjeta NVIDIA (8GB+) desbloquea la generación local ilimitada.