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

RuoloVista
1Busto frontale, espressione neutra
4Figura intera frontale
5Figura intera, di schiena
6Figura intera di profilo, il personaggio guarda verso la sinistra dell'immagine
7Primo piano del viso, frontale
8Primo piano dell'outfit, dal petto alle ginocchia
9Primo 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.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
CampoTipoCosa fa
namestringa, da 1 a 40 caratteriIl nome del personaggio
kindstringawoman, man, o una creatura descritta in inglese (baby dragon). Imposta i pronomi delle istruzioni, mai "they".
image_b64base64La foto: nitida, una sola persona, almeno 1024 px sul lato lungo, massimo 12 MB, JPEG, PNG o WebP
photo_rolebust (predefinito) o full_bodyLa foto è un busto (diventa la vista 1) o una figura intera (vista 4)
outfittesto in inglese, facoltativoCon 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:

statusSignificato
pendingLe viste sono in fase di generazione
readyLe sette viste sono pronte
partialAlcune viste mancano o sono fallite
failed, emptyNessuna vista utilizzabile
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 le viste prima del primo render. GET /characters/{id}/views/{role}/file restituisce 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 senza outfit. 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 (altrimenti 409 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} con image_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 /characters restituisce i tuoi personaggi, inclusi quelli dell'app, e il limite max.
  • 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.

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
CampoTipoCosa fa
namestringa, da 1 a 40 caratteriIl nome della character sheet
outfittesto in inglese, al massimo 700 caratteriL'outfit da indossare; obbligatorio senza views
viewsoggetto, ruolo "1" o da "4" a "9": un'immagine in base64Viste già pronte, con le stesse regole del caricamento di una vista
generatetrue (predefinito) o falseGenerare i ruoli mancanti, o nessuno
from_sheet_idstringa, facoltativoSenza views: la character sheet da cui partire
kindstringaSolo 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 senza views. generate: false non 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_id parte 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_estimate indica 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) in views (409 single_image_sheet).
  • Usa la character sheet come le altre, con ?sheet=<sheet_id>: su GET /characters/{id}, sul file di una vista, su redo (instruction compresa) e sul PUT di una vista. In un clip Multi-Ref, characters[].sheet_id la 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: false senza 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):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
CampoTipoCosa fa
typelocation, object, animal, style o outfitCosa rappresenta il soggetto
nameuna sola parola, da 1 a 40 tra lettere, cifre o _La parola scritta dopo @ nel prompt
descriptiontesto in inglese, massimo 300 caratteri, facoltativoa glossy white futuristic tram with round windows
images_b64da 1 a 6 immagini in base64JPEG, 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}/images con image_b64 (massimo 6).
  • Lista: GET /subjects (?type=location per filtrare) restituisce i tuoi soggetti, inclusi quelli della Libreria dell'app (origin app), e il limite max. Un soggetto dell'app le cui immagini non sono ancora tutte sincronizzate ha complete: 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, MCP tendre_subject_list) e non conta nel limite max. 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} con type, name, description e/o images_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.

CampoTipoCosa fa
typeobject, location, animal, style o outfitChe cos'è il soggetto (un movimento non si genera)
nameuna parola, da 1 a 40 lettere, cifre o _La parola scritta dopo @ nel prompt
descriptiontesto in inglese, al massimo 300 caratteriL'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
prompttesto in inglese, al massimo 2000 caratteri, facoltativoIl testo completo dell'immagine di partenza, al posto del testo automatico ricavato da description
start_image_b64immagine in base64, facoltativaUn'immagine di partenza importata (almeno 512 px), conservata così com'è e gratuita
viewselenco di chiavi, facoltativoLe viste che vuoi, in ordine (tabella qui sotto)
countda 1 a 6, facoltativoAl posto di views: il numero di immagini in tutto, partenza compresa (le prime viste della tabella)
seedintero, facoltativoSeed dell'immagine di partenza
quote_onlytrueRestituisce solo il prezzo, non viene creato nulla

Viste per tipo (chiavi stabili), nel formato di uscita del tipo:

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

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

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}/views con views (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, con instructions se serve. La vista riparte dall'immagine di partenza e sostituisce la precedente (stesso n).
  • Rifare la partenza: POST /subjects/{id}/views/start/redo, solo finché nessuna vista ne è partita (altrimenti views_exist); una partenza importata non si rifà. Le viste fermate dall'errore della partenza ripartono dopo di essa.
  • quote_only: true restituisce il prezzo sulle tre route. Una sola serie alla volta per soggetto (subject_busy).

Dall'inizio alla fine, un oggetto con due viste:

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

Windows · Mac · Cloud o locale

Genera in privato. Stasera.

Scarica tendre.AI gratis e genera senza limiti, in privato, sulla tua GPU.

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

Mac con chip Apple (M1 o successivo): macOS 13 o successivo. Mac Intel: macOS 12 o successivo, tutto funziona online.

La generazione di immagini in locale su Mac richiede un M4 con 24 GB di memoria, oppure un M2 o M3 Pro, Max o Ultra con 24 GB. Al di sotto, tutto funziona online con i crediti. Per ora, ritocco e video su Mac funzionano online.

Tutto su tendre.AI per Mac

Non hai una GPU NVIDIA? Parti al 100% nel cloud: 5 immagini gratuite e 1 video gratuito ogni giorno. Una scheda NVIDIA (8GB+) sblocca la generazione locale illimitata.