API Pro : créer des personnages pour le Multi-Ref Vidéo
Un personnage est une fiche de sept vues d'une même personne (ou créature), fabriquée à partir
d'une seule photo et rangée sous un character_id. C'est elle que le
Multi-Ref Vidéo utilise pour reconnaître quelqu'un dans un clip : ses
vues portent la ressemblance, sans entraînement. Le Face swap s'en sert
aussi, pour mettre le personnage à la place de la personne filmée dans ta propre vidéo.
Les personnages que tu as créés dans l'appli y sont déjà : même licence, même liste (voir Les personnages de l'appli). Les lieux, objets et animaux se rangent de la même façon, à partir de tes propres images, et jouent dans les mêmes clips (voir Lieux, objets et animaux).
Les sept vues
| Rôle | Vue |
|---|---|
| 1 | Buste, de face, expression neutre |
| 4 | En pied, de face |
| 5 | En pied, de dos |
| 6 | En pied, de profil, le personnage regarde vers la gauche de l'image |
| 7 | Gros plan du visage, de face |
| 8 | Gros plan de la tenue, de la poitrine aux genoux |
| 9 | Gros plan des pieds, chaussés ou nus selon la tenue |
Chaque vue se génère à part : aucune n'est obtenue en retournant une autre. Les rôles 2 et 3 (bustes de trois-quarts) ne sont plus créés depuis le 21 octobre 2026 : un personnage fait avant les garde, et ils se lisent encore (fichier d'une vue, liste views), mais ne se refont plus (400 invalid_role).
Créer un personnage
POST /characters (droit images). Le travail est asynchrone.
{ "name": "Lea", "kind": "woman", "image_b64": "<la photo>", "photo_role": "bust" }| Champ | Type | Rôle |
|---|---|---|
name | texte, 1 à 40 caractères | Le prénom du personnage |
kind | texte | woman, man, ou une créature décrite en anglais (baby dragon). Il fixe les pronoms des consignes, jamais « they ». |
image_b64 | base64 | La photo : nette, une seule personne, 1024 px au moins sur le grand côté, 12 Mo au plus, JPEG, PNG ou WebP |
photo_role | bust (défaut) ou full_body | La photo est un buste (elle devient la vue 1) ou un plan en pied (la vue 4) |
outfit | texte anglais, facultatif | Avec une photo en buste, la tenue de la vue en pied (a red leather jacket and black jeans) : le bas du corps, que le buste ne montre pas. Avec une photo en pied, la photo fait foi et la tenue n'est pas posée |
La réponse, 202, est le personnage avec status pending et cost_estimate. La photo devient la vue de son rôle, gardée telle quelle (jamais rhabillée), et le serveur génère les six autres, en 2 à 5 minutes, de la même façon que l'application : le corps (dos, profil, tenue, pieds) part de la vue en pied, le gros plan du visage part du buste. Une photo en buste est prolongée en vue en pied (dans outfit s'il est donné) ; une photo en pied donne le buste par un cadrage.
Prix : un crédit par vue générée, soit 6 crédits, avec ou sans outfit. Une vue en échec n'est pas facturée. POST /characters/quote donne le prix à l'avance.
Renvoyer la même création. Si la connexion se coupe avant la réponse, ou si l'attente d'un agent est interrompue, le serveur continue de fabriquer le personnage. Renvoie la même demande (même photo, name, kind, photo_role et outfit) : elle rend le personnage déjà créé, avec existing: true et un cost_estimate à 0, et rien n'est facturé deux fois. Elle n'en crée un nouveau que si toutes les vues générées du premier ont échoué ; quelques vues en échec se refont une à une (redo). Si deux demandes identiques arrivent au même instant, la seconde reçoit 409 character_busy : renvoie-la quelques secondes plus tard.
Suivre, vérifier, refaire
GET /characters/{id} donne son état :
status | Sens |
|---|---|
pending | Les vues sont en fabrication |
ready | Les sept vues sont là |
partial | Des vues manquent ou ont échoué |
failed, empty | Aucune vue utilisable |
{
"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"
}- Vérifie les vues avant le premier rendu.
GET /characters/{id}/views/{role}/filerend l'image. Les vues en pied (4, 5 et 6) sont générées en 2K, 1024 x 2048, et le buste et les gros plans en 832 x 1216 (1216 x 832 pour les pieds), en PNG, ou en JPEG au-delà de 2,9 Mo. La vue issue de ta photo garde sa taille (2048 px au plus). Les vues déjà faites gardent leur taille ; une vue refaite sort à ces tailles. Une vue ratée, ou un profil tourné du mauvais côté, gâche la ressemblance dans toutes les vidéos. - Refaire une vue :
POST /characters/{id}/views/{role}/redo, 1 crédit : un nouveau tirage depuis son point de départ (la vue en pied ou le buste). La vue issue de la photo d'origine ne se refait pas (photo_view), avec ou sansoutfit. Une sheet importée dans l'application en une seule image (une planche, gardée telle quelle) ne se refait pas vue par vue (409 single_image_sheet). - Guider une vue refaite : ajoute
instruction(200 caractères, en anglais) au corps du redo, pour un personnage créé par l'API, ou une sheet ajoutée par l'API (sinon409 app_character). Elle précise ce que la vue doit montrer du personnage, comme le côté d'une prothèse ou la présence d'un détail, jamais une autre transformation : tenue, coiffure, pose, décor et expression se changent ailleurs. Écris-la à l'impératif (le moteur ignore un état décrit) :"Put the robotic arm on her left side only, remove any second robotic arm."Sur la vue de dos (5), nomme le côté des deux façons :"her left arm, which appears on the left side of the image when seen from behind". Même prix, 1 crédit. - Déposer ta propre image pour une vue :
PUT /characters/{id}/views/{role}avecimage_b64(les mêmes règles que la photo de création : 1024 px au moins sur le grand côté, 12 Mo, JPEG, PNG ou WebP), pour un personnage créé par l'API, ou une sheet ajoutée par l'API (?sheet=). Gratuit, rien n'est généré. L'image est gardée telle quelle et compte comme une vraie photo : les vues refaites ensuite partent d'elle selon la règle de la création (le dos, le profil et les gros plans de la tenue et des pieds de la vue en pied, le gros plan du visage du buste). - Lister :
GET /charactersrend tes personnages, ceux de l'appli compris, et le plafondmax. - Effacer :
DELETE /characters/{id}efface le personnage et ses vues.
Dans l'appli (depuis la version 0.8.6) : un personnage créé par l'API ou le MCP apparaît dans
l'écran Mes personnages de l'appli de la même licence, avec son nom et ses vues, comme ceux créés
dans l'appli. Une vue refaite dans l'appli remplace la vue en ligne, celle que lit le Multi-Ref Vidéo.
Le supprimer dans l'appli l'efface aussi ici, définitivement (l'appli demande confirmation) : un
pipeline qui garde un character_id doit s'attendre à un 404 unknown_character si le personnage a
été supprimé dans l'appli.
Les personnages de l'appli
Un personnage créé dans l'écran Mes personnages de l'appli apparaît dans GET /characters avec
origin app, et joue dans le Multi-Ref Vidéo comme les autres. Dans l'appli, un personnage peut
avoir plusieurs sheets (tenues, humeurs) : sheet_id dit laquelle est servie (la plus récente par
défaut), sheets les liste, et ?sheet=<id> en demande une autre sur la lecture, le fichier d'une
vue et la vue refaite. Dans un clip Multi-Ref, characters[].sheet_id choisit la sheet. Il porte le name et le kind de sa fiche dans l'appli dès que l'appli les a envoyés (appli 0.9.1 et suivantes ; avant, ils valent null). Pour refaire
une vue d'un personnage de l'appli dont le kind vaut encore null, précise son kind dans le corps.
Voix. has_voice dit si la voix de la fiche du personnage est en ligne : l'appli l'envoie avec le personnage, et le Face swap et le Multi-Ref Vidéo la prennent par défaut.
Ajouter une tenue à un personnage
POST /characters/{id}/sheets donne une nouvelle sheet (une tenue, un look) à un personnage existant, qu'il ait été créé par l'API ou dans l'appli, presets de l'appli compris. Le personnage garde ses autres sheets. La réponse, 202, est le personnage avec la nouvelle sheet : son sheet_id (il commence par api-), sheet_name, sheet_outfit, sheet_origin: "api" et cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Champ | Type | Rôle |
|---|---|---|
name | chaîne, 1 à 40 caractères | Le nom de la sheet |
outfit | texte anglais, 700 caractères au plus | La tenue à mettre ; obligatoire sans views |
views | objet, rôle "1" ou "4" à "9" : une image en base64 | Des vues prêtes, avec les mêmes règles que le dépôt d'une vue |
generate | true (défaut) ou false | Générer les rôles manquants, ou aucun |
from_sheet_id | chaîne, facultatif | Sans views : la sheet dont partir |
kind | chaîne | Seulement pour un personnage créé dans l'appli dont le kind vaut encore null dans GET /characters, comme à la création |
- Avec
views: les vues envoyées sont déposées telles quelles, gratuitement. Les rôles manquants sont générés, 1 crédit par vue, selon la règle de la création, depuis la vue en pied et le buste envoyés ; sans l'un ni l'autre, comme sansviews.generate: falsen'en génère aucun. - Sans
views: la tenue est mise sur la vue en pied du personnage (sur son buste s'il n'en a pas ;from_sheet_idpart d'une autre sheet). Le résultat devient la vue en pied de la nouvelle sheet, et les six autres vues partent de lui : 7 vues générées, 7 crédits.cost_estimatedonne le prix. Si la sheet de départ (from_sheet_id, ou celle prise par défaut) est une sheet importée dans l'application en une seule image, fournissez la vue 4 (en pied) ou 1 (buste) dansviews(409 single_image_sheet). - Utilise la sheet comme les autres, avec
?sheet=<sheet_id>: surGET /characters/{id}, le fichier d'une vue,redo(instructioncomprise) et lePUTd'une vue. Dans un clip Multi-Ref,characters[].sheet_idla choisit. - Pour un personnage de l'appli, passe
sheet_id: la sheet servie par défaut reste la plus récemment modifiée, c'est-à-dire celle que tu viens d'ajouter. - Effacer une sheet ajoutée :
DELETE /characters/{id}/sheets/{sheet_id}efface ses vues seulement. Une sheet faite dans l'appli ne s'efface pas ainsi (404 unknown_sheet). - Dans l'appli : l'appli de la même licence ramène la nouvelle sheet dans la fiche du personnage.
- Erreurs :
400 outfit_or_views_required(ni tenue ni vues),400 views_required(generate: falsesans vue),409 source_sheet_empty(ni vue en pied ni buste à reprendre),409 character_busy.
Lieux, objets, animaux, styles et tenues
Un sujet est un lieu (location), un objet (object : un véhicule, un accessoire, un meuble...),
un animal (animal), un style (style : des images d'ambiance dont la vidéo prend le rendu) ou une tenue (outfit : un vêtement porté par un personnage), enregistré à partir de 1 à 6 images que tu fournis (plusieurs angles le
rendent plus fidèle), pour le réutiliser dans le Multi-Ref Vidéo sans le
redécrire à chaque plan. Aucune image n'est générée : c'est gratuit.
Sans image, le serveur peut aussi le générer : voir Générer un sujet sans image.
POST /subjects (droit images) :
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Champ | Type | Rôle |
|---|---|---|
type | location, object, animal, style ou outfit | Le genre du sujet |
name | un mot, 1 à 40 lettres, chiffres ou _ | Celui écrit après @ dans le prompt |
description | texte anglais, 300 caractères au plus, facultatif | a glossy white futuristic tram with round windows |
images_b64 | 1 à 6 images en base64 | JPEG, PNG ou WebP, 512 px au moins sur le grand côté, 12 Mo chacune au plus (28 Mo pour le corps entier : au-delà, ajoute les suivantes une par une) |
La réponse, 201, est le sujet : subject_id, type, name, description, origin, ses images
(chacune avec un file_url), complete et expires_at.
- Ajouter une image :
POST /subjects/{id}/imagesavecimage_b64(6 au plus). - Lister :
GET /subjects(?type=locationpour filtrer) rend tes sujets, ceux de la Bibliothèque de l'appli compris (originapp), et le plafondmax. Un sujet de l'appli dont toutes les images ne sont pas encore synchronisées acomplete: false: il joue avec les images déjà là. - Éléments offerts : Tendre.AI offre des éléments prêts à l'emploi, avec un id fixe (par exemple
officiel-red-beetle, un objet). Chacun est ajouté une fois à ta liste à sa première lecture (GET /subjects, MCPtendre_subject_list) et ne compte pas dans le plafondmax. C'est ensuite un sujet comme les autres : utilisable en Multi-Ref (subject_id), modifiable, supprimable ; une fois supprimé, il ne revient jamais. - Lire :
GET /subjects/{id}; une image :GET /subjects/{id}/images/{n}/file. - Modifier :
PUT /subjects/{id}avectype,name,descriptionet/ouimages_b64(la liste complète, qui remplace les images). - Effacer :
DELETE /subjects/{id}, ici et dans l'appli.
Un style donne son rendu à un clip : sa description dit la technique, en anglais (loose watercolor painting on textured paper), pas ce que montrent ses images. Une tenue est un vêtement porté par un personnage. Styles et tenues ne servent que dans le Multi-Ref Vidéo, en Ultra.
Pour faire jouer un sujet dans un clip, voir Multi-Ref Vidéo ; dans une image, voir Créer une image.
Générer un sujet sans image
Pas d'image sous la main ? POST /subjects/generate (droit images) fabrique le sujet comme la fenêtre « Générer » des Éléments de l'application : une image de départ tirée de ta description (ou importée), puis des vues qui en partent (autres angles, gros plan, de nuit...), chacune retouchée depuis l'image de départ pour garder la même forme. Le sujet obtenu est un sujet ordinaire : il sert dans le Multi-Ref Vidéo et dans Créer une image, et il apparaît dans la Bibliothèque de l'application.
| Champ | Type | Ce que ça fait |
|---|---|---|
type | object, location, animal, style ou outfit | Le genre du sujet (le mouvement ne se génère pas) |
name | un mot, 1 à 40 lettres, chiffres ou _ | Celui écrit après @ dans le prompt |
description | texte anglais, 300 caractères au plus | L'élément seul : forme, matières, couleurs, détails, sans décor ni personnage (a glossy white futuristic tram with round windows). Requis sauf avec prompt ou start_image_b64 |
prompt | texte anglais, 2 000 caractères au plus, facultatif | Le texte complet de l'image de départ, à la place du texte automatique tiré de description |
start_image_b64 | image en base64, facultative | Une image de départ importée (512 px au moins), gardée telle quelle et gratuite |
views | liste de clés, facultative | Les vues voulues, dans l'ordre (tableau ci-dessous) |
count | 1 à 6, facultatif | À la place de views : le nombre d'images en tout, départ compris (les premières vues du tableau) |
seed | entier, facultatif | Seed de l'image de départ |
quote_only | true | Rend seulement le prix, rien n'est créé |
Vues par genre (clés stables), au format de sortie du genre :
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (gros plan) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (gros plan) |
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 (gros plan) |
Prix : chaque image rendue (le départ et chaque vue) coûte le prix d'une image (1 crédit) ; un départ importé est gratuit, et une image en échec n'est pas débitée. 6 images au plus par sujet, départ compris. La réponse, 202, est la fiche du sujet avec cost_estimate et 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"]
}Suis-la par GET /subjects/{id} jusqu'à ce que generation.status ne soit plus pending (ready, partial ou failed) ; n est le numéro de l'image dans images. Les images partent une à la fois : le départ, puis les vues dans l'ordre. Un échec arrête la série : les vues suivantes passent en failed, sans débit.
- Ajouter des vues :
POST /subjects/{id}/viewsavecviews(clés pas encore faites). Avec une vue,instructions(en anglais, 1 000 caractères au plus) remplace sa consigne : dis ce que la vue doit montrer. - Refaire une vue :
POST /subjects/{id}/views/{key}/redo, avec au besoininstructions. La vue repart de l'image de départ et remplace la précédente (mêmen). - Refaire le départ :
POST /subjects/{id}/views/start/redo, seulement tant qu'aucune vue n'en est partie (refusviews_exist) ; un départ importé ne se refait pas. Les vues arrêtées par l'échec du départ repartent derrière lui. quote_only: truerend le prix sur les trois routes. Une seule série à la fois par sujet (subject_busy).
De bout en bout, un objet avec deux vues :
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }La réponse, 202, donne le subject_id avec generation.status pending. Interroge GET /subjects/{id} toutes les quelques secondes jusqu'à ready, puis fais jouer @Tram avec ce subject_id. Trois images (le départ et deux vues), donc trois fois le prix d'une image.
Stockage
Les vues des personnages et les images des sujets sont chiffrées (une clé par fichier) et rattachées
à ta licence. Les images d'un sujet sont gardées telles que tu les as envoyées, et partagées avec la
Bibliothèque de l'appli. Plafonds avec la licence Pro : 50 personnages, ceux de l'appli compris, et
50 sujets (lieux, objets, animaux, styles et tenues confondus), comptés à part (10 avec une licence personnelle, dans l'appli). Un
personnage ou un sujet inutilisé pendant un an est effacé (expires_at) : chaque rendu
Multi-Ref, chaque Face swap et chaque lecture d'une vue ou d'une image repoussent l'échéance. La photo envoyée pour créer
un personnage est gardée comme vue de son rôle, chiffrée, au même titre que les vues générées. Tu peux
effacer chacun d'eux à tout moment.
Par un agent (MCP)
Avec le serveur MCP, il suffit de demander : « fais un personnage avec cette photo ».
L'agent utilise tendre_character_create (la photo passe par un lien de dépôt, un fichier joint dans
ChatGPT, une image rendue dans la conversation ou une adresse publique), te montre les sept vues, et
refait une vue ratée avec tendre_character_redo_view, avec une instruction quand la vue doit être
guidée, ou la remplace par ta propre image avec tendre_character_set_view. tendre_character_get,
tendre_character_list et tendre_character_delete font le reste, et tendre_quote donne le prix
avant.
Pour un lieu, un objet ou un animal, donne tes images à l'agent et dis-lui ce que c'est : il utilise
tendre_subject_create, puis tendre_subject_list, tendre_subject_get et tendre_subject_delete. Sans image, il utilise tendre_subject_generate, puis tendre_subject_add_views et tendre_subject_redo_view pour ajouter ou refaire une vue.
Ensuite, fais jouer le personnage : voir Multi-Ref Vidéo.