Pro API: creare personaggi per Multi-Ref Video
Un personaggio è una character sheet di sette viste della stessa persona (o creatura), creata da una foto
e salvata sotto un character_id. È ciò che Multi-Ref Video usa per
riconoscere qualcuno in un clip: le sue viste portano la somiglianza, senza alcun addestramento.
Anche Face swap le utilizza, per sostituire il personaggio alla persona nel tuo
video.
I personaggi che hai creato nell'app sono già presenti: stessa licenza, stessa lista (vedi Personaggi dall'app). Luoghi, oggetti e animali vengono salvati allo stesso modo, a partire dalle immagini che fornisci, e vengono usati negli stessi clip (vedi Luoghi, oggetti e animali).
Le sette viste
| Ruolo | Vista |
|---|---|
| 1 | Busto frontale, espressione neutra |
| 4 | Figura intera frontale |
| 5 | Figura intera, di schiena |
| 6 | Figura intera di profilo, il personaggio guarda verso la sinistra dell'immagine |
| 7 | Primo piano del viso, frontale |
| 8 | Primo piano dell'outfit, dal petto alle ginocchia |
| 9 | Primo piano dei piedi, con le scarpe o scalzi secondo l'outfit |
Ogni vista è generata autonomamente: nessuna viene ottenuta specchiando un'altra. I ruoli 2 e 3 (busti di tre quarti) non vengono più creati dal 21 ottobre 2026: un personaggio creato prima li conserva, e si possono ancora leggere (file di una vista, elenco views), ma non più rifare (400 invalid_role).
Creare un personaggio
POST /characters (permesso images). Il processo è asincrono.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Campo | Tipo | Cosa fa |
|---|---|---|
name | stringa, da 1 a 40 caratteri | Il nome del personaggio |
kind | stringa | woman, man, o una creatura descritta in inglese (baby dragon). Imposta i pronomi delle istruzioni, mai "they". |
image_b64 | base64 | La foto: nitida, una sola persona, almeno 1024 px sul lato lungo, massimo 12 MB, JPEG, PNG o WebP |
photo_role | bust (predefinito) o full_body | La foto è un busto (diventa la vista 1) o una figura intera (vista 4) |
outfit | testo in inglese, facoltativo | Con una foto del busto, l'outfit della vista a figura intera (a red leather jacket and black jeans): la parte bassa del corpo, che il busto non mostra. Con una foto a figura intera, vale la foto e l'outfit non viene applicato |
La risposta, 202, è il personaggio con status pending e cost_estimate. La foto diventa la vista del suo ruolo, mantenuta così com'è (mai rivestita), e il server genera le altre sei, in 2-5 minuti, come l'app: il corpo (schiena, profilo, outfit, piedi) parte dalla vista a figura intera, il primo piano del viso parte dal busto. Una foto del busto viene prolungata in vista a figura intera (con outfit, se indicato); una foto a figura intera dà il busto con un'inquadratura.
Prezzo: un credito per vista generata, quindi 6 crediti, con o senza outfit. Una vista che fallisce non viene addebitata. POST /characters/quote fornisce il prezzo in anticipo.
Inviare di nuovo la stessa creazione. Se la connessione si interrompe prima della risposta, o se l'attesa di un agente viene interrotta, il server continua a creare il personaggio. Invia di nuovo la stessa richiesta (stessa foto, name, kind, photo_role e outfit): restituisce il personaggio già creato, con existing: true e un cost_estimate pari a 0, e non viene addebitato nulla due volte. Ne crea uno nuovo solo se tutte le viste generate del primo sono fallite; qualche vista fallita si rifà una per una (redo). Se due richieste identiche arrivano nello stesso istante, la seconda riceve 409 character_busy: inviala di nuovo qualche secondo dopo.
Seguire, verificare, rifare
GET /characters/{id} restituisce lo stato:
status | Significato |
|---|---|
pending | Le viste sono in fase di generazione |
ready | Le sette viste sono pronte |
partial | Alcune viste mancano o sono fallite |
failed, empty | Nessuna vista utilizzabile |
{
"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 le viste prima del primo render.
GET /characters/{id}/views/{role}/filerestituisce l'immagine. Le viste a figura intera (4, 5 e 6) sono generate in 2K, 1024 x 2048, e il busto e i primi piani in 832 x 1216 (1216 x 832 per i piedi), in PNG, oppure in JPEG oltre 2,9 MB. La vista ricavata dalla tua foto mantiene le sue dimensioni (al massimo 2048 px). Le viste già fatte mantengono le loro dimensioni; una vista rifatta esce con queste dimensioni. Una vista fallita, o un profilo che guarda nella direzione sbagliata, compromette la somiglianza in ogni video. - Rifare una vista:
POST /characters/{id}/views/{role}/redo, 1 credito: una nuova generazione dal suo punto di partenza (la vista a figura intera o il busto). La vista ottenuta dalla foto originale non può essere rifatta (photo_view), con o senzaoutfit. Una sheet importata nell'app come immagine unica (una tavola intera, mantenuta così com'è) non si rifà vista per vista (409 single_image_sheet). - Guidare una vista rifatta: aggiungi
instruction(200 caratteri, in inglese) al corpo della richiesta di redo, per un personaggio creato tramite API, o una character sheet aggiunta tramite API (altrimenti409 app_character). Specifica cosa la vista deve mostrare del personaggio, come il lato di una protesi o la presenza di un dettaglio, mai un'altra modifica: outfit, capelli, posa, ambientazione ed espressione si cambiano altrove. Scrivila all'imperativo (il motore ignora uno stato descritto):"Put the robotic arm on her left side only, remove any second robotic arm."Nella vista di schiena (5), indica il lato in entrambi i modi:"her left arm, which appears on the left side of the image when seen from behind". Stesso prezzo, 1 credito. - Caricare un'immagine personalizzata per una vista:
PUT /characters/{id}/views/{role}conimage_b64(le stesse regole della foto di creazione: almeno 1024 px sul lato lungo, 12 MB, JPEG, PNG o WebP), per un personaggio creato tramite API, o una character sheet aggiunta tramite API (?sheet=). Gratuito, non viene generato nulla. L'immagine viene mantenuta così com'è e vale come foto reale: le viste rifatte in seguito partono da essa secondo la regola della creazione (la schiena, il profilo e i primi piani dell'outfit e dei piedi dalla vista a figura intera, il primo piano del viso dal busto). - Lista:
GET /charactersrestituisce i tuoi personaggi, inclusi quelli dell'app, e il limitemax. - Eliminare:
DELETE /characters/{id}cancella il personaggio e le sue viste.
Nell'app (versione 0.8.6 e successive): un personaggio creato tramite API o MCP appare nella
schermata I miei personaggi dell'app, sulla stessa licenza, con il suo nome e le sue viste, come quelli creati nell'app. Una vista rifatta nell'app sostituisce quella online, quella che Multi-Ref Video legge. Eliminarlo nell'app lo cancella anche qui, definitivamente (l'app chiede conferma prima): una pipeline che conserva un
character_id deve aspettarsi un 404 unknown_character una volta che il personaggio è stato eliminato nell'app.
Personaggi dall'app
Un personaggio creato nella schermata I miei personaggi dell'app appare in GET /characters con origin
app, e viene usato in Multi-Ref Video come qualsiasi altro. Nell'app, un personaggio può avere più
character sheet (outfit, stati d'animo): sheet_id indica quale viene servita (la più recente per impostazione predefinita), sheets
le elenca, e ?sheet=<id> ne richiede un'altra in lettura, sul file di una vista e su una vista rifatta.
In un clip Multi-Ref, characters[].sheet_id sceglie la character sheet. Porta il name e il kind del suo profilo nell'app non appena l'app li ha inviati (app 0.9.1 e successive; prima, entrambi valgono null). Per rifare una vista di un personaggio dell'app il cui kind vale ancora null,
fornisci il suo kind nel corpo.
Voce. has_voice indica se la voce del profilo del personaggio è online: l'app la invia con il personaggio, e Face swap e Multi-Ref Video la usano per default.
Aggiungere un outfit a un personaggio
POST /characters/{id}/sheets dà a un personaggio esistente una nuova character sheet (un outfit, un look), che sia stato creato tramite API o nell'app, preset dell'app compresi. Il personaggio mantiene le sue altre character sheet. La risposta, 202, è il personaggio con la nuova character sheet: il suo sheet_id (inizia con 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 | Cosa fa |
|---|---|---|
name | stringa, da 1 a 40 caratteri | Il nome della character sheet |
outfit | testo in inglese, al massimo 700 caratteri | L'outfit da indossare; obbligatorio senza views |
views | oggetto, ruolo "1" o da "4" a "9": un'immagine in base64 | Viste già pronte, con le stesse regole del caricamento di una vista |
generate | true (predefinito) o false | Generare i ruoli mancanti, o nessuno |
from_sheet_id | stringa, facoltativo | Senza views: la character sheet da cui partire |
kind | stringa | Solo per un personaggio creato nell'app il cui kind vale ancora null in GET /characters, come alla creazione |
- Con
views: le viste che invii vengono salvate così come sono, gratis. I ruoli mancanti vengono generati, 1 credito per vista, secondo la regola della creazione, dalla vista a figura intera e dal busto inviati; senza nessuno dei due, come senzaviews.generate: falsenon ne genera nessuno. - Senza
views: l'outfit viene messo sulla vista a figura intera del personaggio (sul suo busto se non ne ha;from_sheet_idparte da un'altra character sheet). Il risultato diventa la vista a figura intera della nuova character sheet, e le altre sei viste partono da esso: 7 viste generate, 7 crediti.cost_estimateindica il prezzo. Se la sheet di partenza (from_sheet_id, o quella predefinita) è un'immagine unica di questo tipo, invia la vista 4 (figura intera) o 1 (busto) inviews(409 single_image_sheet). - Usa la character sheet come le altre, con
?sheet=<sheet_id>: suGET /characters/{id}, sul file di una vista, suredo(instructioncompresa) e sulPUTdi una vista. In un clip Multi-Ref,characters[].sheet_idla sceglie. - Per un personaggio dell'app, passa
sheet_id: la character sheet servita per default resta quella modificata più di recente, cioè quella che hai appena aggiunto. - Eliminare una character sheet aggiunta:
DELETE /characters/{id}/sheets/{sheet_id}elimina solo le sue viste. Una character sheet fatta nell'app non si elimina così (404 unknown_sheet). - Nell'app: l'app con la stessa licenza riporta la nuova character sheet nel profilo del personaggio.
- Errori:
400 outfit_or_views_required(né outfit né viste),400 views_required(generate: falsesenza vista),409 source_sheet_empty(né vista a figura intera né busto da cui partire),409 character_busy.
Luoghi, oggetti, animali, stili e outfit
Un soggetto è un'ambientazione (location), un oggetto (object: un veicolo, un oggetto di scena, un mobile...),
un animale (animal), uno stile (style: immagini d'atmosfera di cui il video riprende la resa) o un outfit (outfit: un capo indossato da un personaggio), salvato da 1 a 6 immagini che fornisci (più angolazioni lo rendono più fedele), in modo da poterlo riutilizzare in Multi-Ref Video
senza doverlo descrivere di nuovo in ogni scena. Non viene generata alcuna immagine, quindi è gratuito.
Senza immagini, il server può anche generarlo: vedi Generare un soggetto senza immagini.
POST /subjects (permesso images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Campo | Tipo | Cosa fa |
|---|---|---|
type | location, object, animal, style o outfit | Cosa rappresenta il soggetto |
name | una sola parola, da 1 a 40 tra lettere, cifre o _ | La parola scritta dopo @ nel prompt |
description | testo in inglese, massimo 300 caratteri, facoltativo | a glossy white futuristic tram with round windows |
images_b64 | da 1 a 6 immagini in base64 | JPEG, PNG o WebP, almeno 512 px sul lato lungo, massimo 12 MB ciascuna (28 MB per l'intero corpo: oltre questo limite, aggiungi le successive una alla volta) |
La risposta, 201, è il soggetto: subject_id, type, name, description, origin, le sue images
(ognuna con un file_url), complete e expires_at.
- Aggiungere un'immagine:
POST /subjects/{id}/imagesconimage_b64(massimo 6). - Lista:
GET /subjects(?type=locationper filtrare) restituisce i tuoi soggetti, inclusi quelli della Libreria dell'app (originapp), e il limitemax. Un soggetto dell'app le cui immagini non sono ancora tutte sincronizzate hacomplete: false: viene usato con le immagini già presenti. - Elementi offerti: Tendre.AI offre elementi pronti all'uso, con un id fisso (per esempio
officiel-red-beetle, un oggetto). Ognuno viene aggiunto una volta alla tua lista alla prima lettura (GET /subjects, MCPtendre_subject_list) e non conta nel limitemax. Poi è un soggetto come gli altri: utilizzabile in Multi-Ref (subject_id), modificabile, eliminabile; una volta eliminato, non torna mai. - Leggere:
GET /subjects/{id}; una singola immagine:GET /subjects/{id}/images/{n}/file. - Modificare:
PUT /subjects/{id}contype,name,descriptione/oimages_b64(la lista completa, che sostituisce le immagini). - Eliminare:
DELETE /subjects/{id}, qui e nell'app.
Uno stile dà a un clip la sua resa: la sua description indica la tecnica, in inglese (loose watercolor painting on textured paper), non ciò che mostrano le sue immagini. Un outfit è un capo indossato da un personaggio. Stili e outfit funzionano solo in Multi-Ref Video, in Ultra.
Per inserire un soggetto in un clip, vedi Multi-Ref Video; in un'immagine, vedi Crea un'immagine.
Generare un soggetto senza immagini
Nessuna immagine a portata di mano? POST /subjects/generate (permesso images) crea il soggetto come la finestra «Generare» degli Elementi dell'app: un'immagine di partenza ricavata dalla tua descrizione (o importata), poi delle viste che partono da essa (altre angolazioni, un primo piano, di notte...), ognuna ritoccata dall'immagine di partenza per mantenere la stessa forma. Il risultato è un soggetto normale: funziona in Multi-Ref Video e in Crea un'immagine, e compare nella Libreria dell'app.
| Campo | Tipo | Cosa fa |
|---|---|---|
type | object, location, animal, style o outfit | Che cos'è il soggetto (un movimento non si genera) |
name | una parola, da 1 a 40 lettere, cifre o _ | La parola scritta dopo @ nel prompt |
description | testo in inglese, al massimo 300 caratteri | L'elemento da solo: forma, materiali, colori, dettagli, senza sfondo né personaggio (a glossy white futuristic tram with round windows). Obbligatorio, salvo con prompt o start_image_b64 |
prompt | testo in inglese, al massimo 2000 caratteri, facoltativo | Il testo completo dell'immagine di partenza, al posto del testo automatico ricavato da description |
start_image_b64 | immagine in base64, facoltativa | Un'immagine di partenza importata (almeno 512 px), conservata così com'è e gratuita |
views | elenco di chiavi, facoltativo | Le viste che vuoi, in ordine (tabella qui sotto) |
count | da 1 a 6, facoltativo | Al posto di views: il numero di immagini in tutto, partenza compresa (le prime viste della tabella) |
seed | intero, facoltativo | Seed dell'immagine di partenza |
quote_only | true | Restituisce solo il prezzo, non viene creato nulla |
Viste per tipo (chiavi stabili), nel formato di uscita del tipo:
type | Formato | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (primo piano) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (primo piano) |
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 (primo piano) |
Prezzo: ogni immagine renderizzata (la partenza e ogni vista) costa il prezzo di un'immagine (1 credito); una partenza importata è gratuita, e un'immagine non riuscita non viene addebitata. Al massimo 6 immagini per soggetto, partenza compresa. La risposta, 202, è il soggetto con 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"]
}Seguilo con GET /subjects/{id} finché generation.status non è più pending (ready, partial o failed); n è il numero dell'immagine in images. Le immagini partono una alla volta: la partenza, poi le viste in ordine. Un errore ferma la serie: le viste successive passano a failed, senza addebito.
- Aggiungere viste:
POST /subjects/{id}/viewsconviews(chiavi non ancora fatte). Con una vista,instructions(in inglese, al massimo 1000 caratteri) sostituisce la sua consegna: di' cosa deve mostrare la vista. - Rifare una vista:
POST /subjects/{id}/views/{key}/redo, coninstructionsse serve. La vista riparte dall'immagine di partenza e sostituisce la precedente (stesson). - Rifare la partenza:
POST /subjects/{id}/views/start/redo, solo finché nessuna vista ne è partita (altrimentiviews_exist); una partenza importata non si rifà. Le viste fermate dall'errore della partenza ripartono dopo di essa. quote_only: truerestituisce il prezzo sulle tre route. Una sola serie alla volta per soggetto (subject_busy).
Dall'inizio alla fine, un oggetto con due viste:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }La risposta, 202, dà il subject_id con generation.status pending. Interroga GET /subjects/{id} ogni pochi secondi fino a ready, poi inserisci @Tram con quel subject_id. Tre immagini (la partenza e due viste), quindi tre volte il prezzo di un'immagine.
Archiviazione
Le viste dei personaggi e le immagini dei soggetti sono cifrate (una chiave per file) e collegate alla tua
licenza. Le immagini dei soggetti vengono conservate così come le hai inviate e condivise con la Libreria dell'app. Limiti con la
licenza Pro: 50 personaggi, inclusi quelli dell'app, e 50 soggetti (ambientazioni, oggetti, animali, stili e outfit insieme), contati
separatamente (10 con una licenza personale, nell'app). Un personaggio o un soggetto non utilizzato per un anno
viene eliminato (expires_at): ogni render Multi-Ref, ogni Face swap e ogni lettura di una vista o un'immagine
posticipa la data. La foto che invii per creare un personaggio viene conservata come vista del suo ruolo, cifrata, come le
viste generate. Puoi eliminarle in qualsiasi momento.
Tramite un agente (MCP)
Con il server MCP, ti basta chiedere: "crea un personaggio da questa foto". L'agente
usa tendre_character_create (la foto arriva tramite un link di upload, un file allegato in ChatGPT,
un'immagine generata nella conversazione o un indirizzo pubblico), ti mostra le sette viste, e rifà
una vista fallita con tendre_character_redo_view, con un instruction quando la vista richiede una guida, oppure
la sostituisce con un'immagine tua tramite tendre_character_set_view. tendre_character_get,
tendre_character_list e tendre_character_delete coprono il resto, e tendre_quote fornisce il
prezzo prima.
Per un'ambientazione, un oggetto o un animale, fornisci all'agente le tue immagini e digli di cosa si tratta: usa
tendre_subject_create, poi tendre_subject_list, tendre_subject_get e tendre_subject_delete. Senza immagini, usa tendre_subject_generate, poi tendre_subject_add_views e tendre_subject_redo_view per aggiungere o rifare una vista.
Poi inserisci il personaggio: vedi Multi-Ref Video.