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
| Papel | Vista |
|---|---|
| 1 | Busto de frente, expressão neutra |
| 4 | Corpo inteiro de frente |
| 5 | Corpo inteiro de costas |
| 6 | Corpo inteiro de perfil, a personagem olha para a esquerda da imagem |
| 7 | Grande plano do rosto, de frente |
| 8 | Grande plano da roupa, do peito aos joelhos |
| 9 | Grande 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.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Campo | Tipo | O que faz |
|---|---|---|
name | string, 1 a 40 caracteres | O primeiro nome da personagem |
kind | string | woman, man, ou uma criatura descrita em inglês (baby dragon). Define os pronomes das instruções, nunca "they". |
image_b64 | base64 | A foto: nítida, uma só pessoa, pelo menos 1024 px no lado maior, no máximo 12 MB, JPEG, PNG ou WebP |
photo_role | bust (padrão) ou full_body | A foto é um busto (torna-se a vista 1) ou uma foto de corpo inteiro (vista 4) |
outfit | Texto em inglês, opcional | Com 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:
status | Significado |
|---|---|
pending | As vistas estão a ser criadas |
ready | As sete vistas estão prontas |
partial | Algumas vistas estão em falta ou falharam |
failed, empty | Nenhuma vista utilizável |
{
"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}/filedevolve 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 semoutfit. 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ário409 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}comimage_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 /charactersdevolve as tuas personagens, incluindo as da app, e o limitemax. - 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.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Campo | Tipo | O que faz |
|---|---|---|
name | string, 1 a 40 caracteres | O nome da character sheet |
outfit | texto em inglês, 700 caracteres no máximo | A roupa a vestir; obrigatória sem views |
views | objeto, papel "1" ou "4" a "9": uma imagem em base64 | Vistas já prontas, com as mesmas regras do envio de uma vista |
generate | true (padrão) ou false | Gerar os papéis em falta, ou nenhum |
from_sheet_id | string, opcional | Sem views: a character sheet de onde partir |
kind | string | Só 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 semviews.generate: falsenão gera nenhum. - Sem
views: a roupa é posta na vista de corpo inteiro da personagem (no seu busto se não tiver;from_sheet_idparte 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_estimatedá 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) emviews(409 single_image_sheet). - Usa a character sheet como as outras, com
?sheet=<sheet_id>: emGET /characters/{id}, no ficheiro de uma vista, emredo(instructionincluída) e noPUTde uma vista. Num clip Multi-Ref,characters[].sheet_idescolhe-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: falsesem 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):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Campo | Tipo | O que faz |
|---|---|---|
type | location, object, animal, style ou outfit | O que o sujeito é |
name | uma palavra, 1 a 40 letras, dígitos ou _ | A palavra escrita depois de @ no prompt |
description | Texto em inglês, no máximo 300 caracteres, opcional | a glossy white futuristic tram with round windows |
images_b64 | 1 a 6 imagens em base64 | JPEG, 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}/imagescomimage_b64(no máximo 6). - Listar:
GET /subjects(?type=locationpara filtrar) devolve os teus sujeitos, incluindo os da Biblioteca da app (originapp), e o limitemax. Um sujeito da app cujas imagens ainda não estão todas sincronizadas temcomplete: 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, MCPtendre_subject_list) e não conta no limitemax. 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}comtype,name,descriptione/ouimages_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.
| Campo | Tipo | O que faz |
|---|---|---|
type | object, location, animal, style ou outfit | O que é o sujeito (um movimento não é gerado) |
name | uma palavra, de 1 a 40 letras, algarismos ou _ | A palavra escrita depois de @ no prompt |
description | texto em inglês, 300 caracteres no máximo | O 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 |
prompt | texto em inglês, 2000 caracteres no máximo, opcional | O texto completo da imagem de partida, em vez do texto automático tirado de description |
start_image_b64 | imagem em base64, opcional | Uma imagem de partida importada (512 px no mínimo), mantida tal como está e gratuita |
views | lista de chaves, opcional | As vistas que queres, por ordem (tabela abaixo) |
count | de 1 a 6, opcional | Em vez de views: o número de imagens no total, partida incluída (as primeiras vistas da tabela) |
seed | inteiro, opcional | Seed da imagem de partida |
quote_only | true | Devolve apenas o preço, nada é criado |
Vistas por tipo (chaves estáveis), no formato de saída do tipo:
type | Formato | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (grande plano) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (grande 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 (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:
"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}/viewscomviews(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, cominstructionsse for preciso. A vista volta a partir da imagem de partida e substitui a anterior (mesmon). - 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: truedevolve 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:
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.