Pro API: criar personagens para Multi-Ref Vídeo

Uma personagem é uma character sheet de sete vistas da mesma pessoa (ou criatura), criada a partir de uma foto e guardada com um character_id. É o que o Multi-Ref Vídeo usa para reconhecer alguém num clip: as suas vistas transportam a semelhança, sem treino. O Face swap também as usa, para colocar a personagem no lugar da pessoa no teu próprio vídeo.

As personagens que criaste na app já estão disponíveis: mesma licença, mesma lista (ver Personagens da app). Lugares, objetos e animais são guardados da mesma forma, a partir de imagens que forneces, e aparecem nos mesmos clips (ver Lugares, objetos e animais).

As sete vistas

PapelVista
1Busto de frente, expressão neutra
4Corpo inteiro de frente
5Corpo inteiro de costas
6Corpo inteiro de perfil, a personagem olha para a esquerda da imagem
7Grande plano do rosto, de frente
8Grande plano da roupa, do peito aos joelhos
9Grande plano dos pés, calçados ou descalços conforme a roupa

Cada vista é gerada de forma independente: nenhuma é obtida por inversão de outra. Os papéis 2 e 3 (bustos a três quartos) deixaram de ser criados a 21 de outubro de 2026: uma personagem criada antes mantém-nos, e continuam a poder ser lidos (ficheiro de uma vista, lista views), mas já não se refazem (400 invalid_role).

Criar uma personagem

POST /characters (permissão images). O trabalho é assíncrono.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
CampoTipoO que faz
namestring, 1 a 40 caracteresO primeiro nome da personagem
kindstringwoman, man, ou uma criatura descrita em inglês (baby dragon). Define os pronomes das instruções, nunca "they".
image_b64base64A foto: nítida, uma só pessoa, pelo menos 1024 px no lado maior, no máximo 12 MB, JPEG, PNG ou WebP
photo_rolebust (padrão) ou full_bodyA foto é um busto (torna-se a vista 1) ou uma foto de corpo inteiro (vista 4)
outfitTexto em inglês, opcionalCom uma foto de busto, a roupa da vista de corpo inteiro (a red leather jacket and black jeans): a parte de baixo do corpo, que o busto não mostra. Com uma foto de corpo inteiro, vale a foto e a roupa não é aplicada

A resposta, 202, é a personagem com status pending e cost_estimate. A foto torna-se a vista do seu papel, mantida tal como está (nunca vestida de novo), e o servidor gera as outras seis, em 2 a 5 minutos, da mesma forma que a app: o corpo (costas, perfil, roupa, pés) parte da vista de corpo inteiro, o grande plano do rosto parte do busto. Uma foto de busto é prolongada em vista de corpo inteiro (com outfit, se for dado); uma foto de corpo inteiro dá o busto por enquadramento.

Preço: um crédito por vista gerada, ou seja, 6 créditos, com ou sem outfit. Uma vista que falhe não é cobrada. POST /characters/quote fornece o preço antecipadamente.

Reenviar a mesma criação. Se a ligação cair antes da resposta, ou se a espera de um agente for interrompida, o servidor continua a criar a personagem. Volta a enviar o mesmo pedido (mesma foto, name, kind, photo_role e outfit): devolve a personagem já criada, com existing: true e um cost_estimate de 0, e nada é cobrado duas vezes. Só cria uma nova se todas as vistas geradas da primeira tiverem falhado; algumas vistas falhadas refazem-se uma a uma (redo). Se dois pedidos idênticos chegarem no mesmo instante, o segundo recebe 409 character_busy: volta a enviá-lo alguns segundos depois.

Acompanhar, verificar, refazer

GET /characters/{id} devolve o estado:

statusSignificado
pendingAs vistas estão a ser criadas
readyAs sete vistas estão prontas
partialAlgumas vistas estão em falta ou falharam
failed, emptyNenhuma vista utilizável
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"
}
  • Verifica as vistas antes do primeiro render. GET /characters/{id}/views/{role}/file devolve a imagem. As vistas de corpo inteiro (4, 5 e 6) são geradas em 2K, 1024 x 2048, e o busto e os grandes planos em 832 x 1216 (1216 x 832 para os pés), em PNG, ou em JPEG acima de 2,9 MB. A vista que vem da tua foto mantém o seu tamanho (2048 px no máximo). As vistas já feitas mantêm o seu tamanho; uma vista refeita sai com estes tamanhos. Uma vista que falhou, ou um perfil que olha para o lado errado, prejudica a semelhança em todos os vídeos.
  • Refazer uma vista: POST /characters/{id}/views/{role}/redo, 1 crédito: uma nova geração a partir do seu ponto de partida (a vista de corpo inteiro ou o busto). A vista que veio da foto original não pode ser refeita (photo_view), com ou sem outfit. Uma sheet importada na aplicação como uma única imagem (uma prancha inteira, mantida tal como está) não se refaz vista a vista (409 single_image_sheet).
  • Guiar uma vista refeita: adiciona instruction (200 caracteres, em inglês) ao corpo do redo, para uma personagem criada através da API, ou uma character sheet adicionada através da API (caso contrário 409 app_character). Especifica o que a vista deve mostrar da personagem, como o lado de uma prótese ou a presença de um detalhe, nunca outra alteração: roupa, cabelo, pose, cenário e expressão alteram-se noutros locais. Escreve no imperativo (o motor ignora um estado descrito): "Put the robotic arm on her left side only, remove any second robotic arm." Na vista de costas (5), indica o lado das duas formas: "her left arm, which appears on the left side of the image when seen from behind". Mesmo preço, 1 crédito.
  • Fazer upload da tua própria imagem para uma vista: PUT /characters/{id}/views/{role} com image_b64 (as mesmas regras da foto de criação: pelo menos 1024 px no lado maior, 12 MB, JPEG, PNG ou WebP), para uma personagem criada através da API, ou uma character sheet adicionada através da API (?sheet=). Gratuito, nada é gerado. A imagem é mantida tal como está e conta como uma foto real: as vistas refeitas a seguir partem dela segundo a regra da criação (as costas, o perfil e os grandes planos da roupa e dos pés, da vista de corpo inteiro; o grande plano do rosto, do busto).
  • Listar: GET /characters devolve as tuas personagens, incluindo as da app, e o limite max.
  • Eliminar: DELETE /characters/{id} apaga a personagem e as suas vistas.

Na app (versão 0.8.6 e posterior): uma personagem criada através da API ou do MCP aparece no ecrã Meus personagens da app, na mesma licença, com o seu nome e vistas, tal como as criadas na app. Uma vista refeita na app substitui a vista online, a que o Multi-Ref Vídeo lê. Eliminá-la na app apaga-a aqui também, de forma definitiva (a app pede confirmação primeiro): um pipeline que guarda um character_id deve esperar um 404 unknown_character quando a personagem for eliminada na app.

Personagens da app

Uma personagem criada no ecrã Meus personagens da app aparece em GET /characters com origin app, e é usada no Multi-Ref Vídeo como qualquer outra. Na app, uma personagem pode ter várias character sheets (roupas, estados de espírito): sheet_id indica qual é servida (a mais recente por padrão), sheets lista-as, e ?sheet=<id> pede outra na leitura, no ficheiro de uma vista e numa vista refeita. Num clip Multi-Ref, characters[].sheet_id escolhe a character sheet. Traz o name e o kind do seu perfil na app assim que a app os enviar (app 0.9.1 e seguintes; antes, ambos valem null). Para refazer uma vista de uma personagem da app cujo kind ainda vale null, indica o seu kind no corpo.

Voz. has_voice indica se a voz do perfil da personagem está online: a app envia-a com a personagem, e o Face swap e o Multi-Ref Vídeo usam-na por predefinição.

Adicionar uma roupa a uma personagem

POST /characters/{id}/sheets dá a uma personagem existente uma nova character sheet (uma roupa, um visual), quer tenha sido criada através da API quer na app, presets da app incluídos. A personagem mantém as suas outras character sheets. A resposta, 202, é a personagem com a nova character sheet: o seu sheet_id (começa por api-), sheet_name, sheet_outfit, sheet_origin: "api" e cost_estimate.

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
CampoTipoO que faz
namestring, 1 a 40 caracteresO nome da character sheet
outfittexto em inglês, 700 caracteres no máximoA roupa a vestir; obrigatória sem views
viewsobjeto, papel "1" ou "4" a "9": uma imagem em base64Vistas já prontas, com as mesmas regras do envio de uma vista
generatetrue (padrão) ou falseGerar os papéis em falta, ou nenhum
from_sheet_idstring, opcionalSem views: a character sheet de onde partir
kindstringSó para uma personagem criada na app cujo kind ainda vale null em GET /characters, como na criação
  • Com views: as vistas que envias são guardadas tal como estão, grátis. Os papéis em falta são gerados, 1 crédito por vista, segundo a regra da criação, a partir da vista de corpo inteiro e do busto enviados; sem nenhum dos dois, como sem views. generate: false não gera nenhum.
  • Sem views: a roupa é posta na vista de corpo inteiro da personagem (no seu busto se não tiver; from_sheet_id parte de outra character sheet). O resultado torna-se a vista de corpo inteiro da nova character sheet, e as outras seis vistas partem dele: 7 vistas geradas, 7 créditos. cost_estimate dá o preço. Se a sheet de origem (from_sheet_id, ou a usada por omissão) for uma imagem única destas, envie a vista 4 (corpo inteiro) ou 1 (busto) em views (409 single_image_sheet).
  • Usa a character sheet como as outras, com ?sheet=<sheet_id>: em GET /characters/{id}, no ficheiro de uma vista, em redo (instruction incluída) e no PUT de uma vista. Num clip Multi-Ref, characters[].sheet_id escolhe-a.
  • Para uma personagem da app, passa sheet_id: a character sheet servida por predefinição continua a ser a alterada mais recentemente, ou seja, a que acabaste de adicionar.
  • Apagar uma character sheet adicionada: DELETE /characters/{id}/sheets/{sheet_id} apaga só as suas vistas. Uma character sheet feita na app não se apaga assim (404 unknown_sheet).
  • Na app: a app da mesma licença traz a nova character sheet para o perfil da personagem.
  • Erros: 400 outfit_or_views_required (nem roupa nem vistas), 400 views_required (generate: false sem vista), 409 source_sheet_empty (nem vista de corpo inteiro nem busto de onde partir), 409 character_busy.

Lugares, objetos, animais, estilos e roupas

Um sujeito é um lugar (location), um objeto (object: um veículo, um adereço, um móvel...), um animal (animal), um estilo (style: imagens de ambiente cujo aspeto o vídeo adota) ou uma roupa (outfit: uma peça usada por uma personagem), guardado a partir de 1 a 6 imagens que forneces (vários ângulos tornam-no mais fiel), para que o possas usar novamente no Multi-Ref Vídeo sem o descrever de novo em cada cena. Nenhuma imagem é gerada, por isso é gratuito.

Sem imagens, o servidor também o pode gerar: ver Gerar um sujeito sem imagens.

POST /subjects (permissão images):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
CampoTipoO que faz
typelocation, object, animal, style ou outfitO que o sujeito é
nameuma palavra, 1 a 40 letras, dígitos ou _A palavra escrita depois de @ no prompt
descriptionTexto em inglês, no máximo 300 caracteres, opcionala glossy white futuristic tram with round windows
images_b641 a 6 imagens em base64JPEG, PNG ou WebP, pelo menos 512 px no lado maior, no máximo 12 MB cada (28 MB para o corpo completo: acima disso, adiciona as seguintes uma a uma)

A resposta, 201, é o sujeito: subject_id, type, name, description, origin, as suas images (cada uma com um file_url), complete e expires_at.

  • Adicionar uma imagem: POST /subjects/{id}/images com image_b64 (no máximo 6).
  • Listar: GET /subjects (?type=location para filtrar) devolve os teus sujeitos, incluindo os da Biblioteca da app (origin app), e o limite max. Um sujeito da app cujas imagens ainda não estão todas sincronizadas tem complete: false: é usado com as imagens já disponíveis.
  • Elementos oferecidos: a Tendre.AI oferece elementos prontos a usar, com um id fixo (por exemplo officiel-red-beetle, um objeto). Cada um é adicionado uma vez à tua lista na primeira leitura (GET /subjects, MCP tendre_subject_list) e não conta no limite max. Depois é um sujeito como os outros: utilizável em Multi-Ref (subject_id), modificável, eliminável; depois de eliminado, nunca volta.
  • Ler: GET /subjects/{id}; uma imagem: GET /subjects/{id}/images/{n}/file.
  • Alterar: PUT /subjects/{id} com type, name, description e/ou images_b64 (a lista completa, que substitui as imagens).
  • Eliminar: DELETE /subjects/{id}, aqui e na app.

Um estilo dá o seu aspeto a um clip: a sua description indica a técnica, em inglês (loose watercolor painting on textured paper), não o que as suas imagens mostram. Uma roupa é uma peça usada por uma personagem. Estilos e roupas só funcionam no Multi-Ref Vídeo, em Ultra.

Para usar um sujeito num clip, ver Multi-Ref Vídeo; numa imagem, ver Criar uma imagem.

Gerar um sujeito sem imagens

Não tens nenhuma imagem à mão? POST /subjects/generate (permissão images) cria o sujeito como a janela «Gerar» dos Elementos da aplicação: uma imagem de partida tirada da tua descrição (ou importada), e depois vistas que partem dela (outros ângulos, um grande plano, de noite...), cada uma retocada a partir da imagem de partida para manter a mesma forma. O resultado é um sujeito normal: funciona no Multi-Ref Vídeo e em Criar uma imagem, e aparece na Biblioteca da aplicação.

CampoTipoO que faz
typeobject, location, animal, style ou outfitO que é o sujeito (um movimento não é gerado)
nameuma palavra, de 1 a 40 letras, algarismos ou _A palavra escrita depois de @ no prompt
descriptiontexto em inglês, 300 caracteres no máximoO elemento sozinho: forma, materiais, cores, detalhes, sem fundo nem personagem (a glossy white futuristic tram with round windows). Obrigatório, exceto com prompt ou start_image_b64
prompttexto em inglês, 2000 caracteres no máximo, opcionalO texto completo da imagem de partida, em vez do texto automático tirado de description
start_image_b64imagem em base64, opcionalUma imagem de partida importada (512 px no mínimo), mantida tal como está e gratuita
viewslista de chaves, opcionalAs vistas que queres, por ordem (tabela abaixo)
countde 1 a 6, opcionalEm vez de views: o número de imagens no total, partida incluída (as primeiras vistas da tabela)
seedinteiro, opcionalSeed da imagem de partida
quote_onlytrueDevolve apenas o preço, nada é criado

Vistas por tipo (chaves estáveis), no formato de saída do tipo:

typeFormatoviews
object1024 × 1024three_quarter, side, back, top, detail (grande plano)
location1216 × 832reverse_shot, side, high_angle, night, detail (grande plano)
animal1216 × 832front, three_quarter, back, sitting, lying
style1024 × 1024portrait, landscape, interior, object, animal
outfit832 × 1216three_quarter, side, back, detail (grande plano)

Preço: cada imagem renderizada (a partida e cada vista) custa o preço de uma imagem (1 crédito); uma partida importada é gratuita, e uma imagem falhada não é debitada. 6 imagens no máximo por sujeito, partida incluída. A resposta, 202, é o sujeito com cost_estimate e 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"]
}

Acompanha-o com GET /subjects/{id} até generation.status deixar de ser pending (ready, partial ou failed); n é o número da imagem em images. As imagens são feitas uma de cada vez: a partida e depois as vistas por ordem. Uma falha para a série: as vistas seguintes passam a failed, sem débito.

  • Adicionar vistas: POST /subjects/{id}/views com views (chaves ainda não feitas). Com uma vista, instructions (em inglês, 1000 caracteres no máximo) substitui a sua instrução: diz o que a vista deve mostrar.
  • Refazer uma vista: POST /subjects/{id}/views/{key}/redo, com instructions se for preciso. A vista volta a partir da imagem de partida e substitui a anterior (mesmo n).
  • Refazer a partida: POST /subjects/{id}/views/start/redo, só enquanto nenhuma vista partir dela (caso contrário, views_exist); uma partida importada não se refaz. As vistas paradas pela falha da partida voltam a ser feitas depois dela.
  • quote_only: true devolve o preço nas três rotas. Uma só série de cada vez por sujeito (subject_busy).

Do início ao fim, um objeto com duas vistas:

http
POST /pro/v1/subjects/generate

{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }

A resposta, 202, dá o subject_id com generation.status pending. Consulta GET /subjects/{id} de poucos em poucos segundos até ready e depois usa @Tram com esse subject_id. Três imagens (a partida e duas vistas), ou seja, três vezes o preço de uma imagem.

Armazenamento

As vistas das personagens e as imagens dos sujeitos estão encriptadas (uma chave por ficheiro) e associadas à tua licença. As imagens dos sujeitos são guardadas tal como as enviaste e partilhadas com a Biblioteca da app. Limites com a licença Pro: 50 personagens, incluindo as da app, e 50 sujeitos (lugares, objetos, animais, estilos e roupas no conjunto), contados separadamente (10 com uma licença pessoal, na app). Uma personagem ou sujeito sem utilização durante um ano é apagado (expires_at): cada render Multi-Ref, cada Face swap e cada leitura de uma vista ou imagem adiam a data. A foto que envias para criar uma personagem é guardada como a vista do seu papel, encriptada, tal como as vistas geradas. Podes eliminar qualquer uma delas a qualquer momento.

Através de um agente (MCP)

Com o servidor MCP, basta pedires: "cria uma personagem a partir desta foto". O agente usa tendre_character_create (a foto chega através de um link de upload, um ficheiro anexado no ChatGPT, uma imagem gerada na conversa ou um endereço público), mostra-te as sete vistas e refaz uma que falhou com tendre_character_redo_view, com uma instruction quando a vista precisa de orientação, ou substitui-a pela tua própria imagem através de tendre_character_set_view. tendre_character_get, tendre_character_list e tendre_character_delete cobrem o resto, e tendre_quote fornece o preço primeiro.

Para um lugar, um objeto ou um animal, fornece as tuas imagens ao agente e diz o que é: ele usa tendre_subject_create, depois tendre_subject_list, tendre_subject_get e tendre_subject_delete. Sem imagens, ele usa tendre_subject_generate, depois tendre_subject_add_views e tendre_subject_redo_view para adicionar ou refazer uma vista.

De seguida distribui a personagem: ver Multi-Ref Vídeo.

Windows · Mac · Cloud ou local

Gera em privado. Esta noite.

Descarrega a tendre.AI gratuitamente e gera sem limites, de forma privada, na tua própria GPU.

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

Mac com chip Apple (M1 ou posterior): macOS 13 ou posterior. Mac Intel: macOS 12 ou posterior, tudo corre online.

A geração local de imagens no Mac precisa de um M4 com 24 GB de memória, ou um M2 ou M3 Pro, Max ou Ultra com 24 GB. Abaixo disso, tudo corre online com créditos. Por agora, a retoque e o vídeo correm online no Mac.

Tudo sobre o tendre.AI para Mac

Sem GPU NVIDIA? Começa 100% na cloud: 5 imagens grátis e 1 vídeo grátis todos os dias. Uma placa NVIDIA (8GB+) desbloqueia a geração local ilimitada.