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ôleVue
1Buste, de face, expression neutre
4En pied, de face
5En pied, de dos
6En pied, de profil, le personnage regarde vers la gauche de l'image
7Gros plan du visage, de face
8Gros plan de la tenue, de la poitrine aux genoux
9Gros 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.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<la photo>", "photo_role": "bust" }
ChampTypeRôle
nametexte, 1 à 40 caractèresLe prénom du personnage
kindtextewoman, man, ou une créature décrite en anglais (baby dragon). Il fixe les pronoms des consignes, jamais « they ».
image_b64base64La photo : nette, une seule personne, 1024 px au moins sur le grand côté, 12 Mo au plus, JPEG, PNG ou WebP
photo_rolebust (défaut) ou full_bodyLa photo est un buste (elle devient la vue 1) ou un plan en pied (la vue 4)
outfittexte anglais, facultatifAvec 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 :

statusSens
pendingLes vues sont en fabrication
readyLes sept vues sont là
partialDes vues manquent ou ont échoué
failed, emptyAucune vue utilisable
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"
}
  • Vérifie les vues avant le premier rendu. GET /characters/{id}/views/{role}/file rend 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 sans outfit. 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 (sinon 409 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} avec image_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 /characters rend tes personnages, ceux de l'appli compris, et le plafond max.
  • 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.

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
ChampTypeRôle
namechaîne, 1 à 40 caractèresLe nom de la sheet
outfittexte anglais, 700 caractères au plusLa tenue à mettre ; obligatoire sans views
viewsobjet, rôle "1" ou "4" à "9" : une image en base64Des vues prêtes, avec les mêmes règles que le dépôt d'une vue
generatetrue (défaut) ou falseGénérer les rôles manquants, ou aucun
from_sheet_idchaîne, facultatifSans views : la sheet dont partir
kindchaîneSeulement 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 sans views. generate: false n'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_id part 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_estimate donne 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) dans views (409 single_image_sheet).
  • Utilise la sheet comme les autres, avec ?sheet=<sheet_id> : sur GET /characters/{id}, le fichier d'une vue, redo (instruction comprise) et le PUT d'une vue. Dans un clip Multi-Ref, characters[].sheet_id la 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: false sans 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) :

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
ChampTypeRôle
typelocation, object, animal, style ou outfitLe genre du sujet
nameun mot, 1 à 40 lettres, chiffres ou _Celui écrit après @ dans le prompt
descriptiontexte anglais, 300 caractères au plus, facultatifa glossy white futuristic tram with round windows
images_b641 à 6 images en base64JPEG, 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}/images avec image_b64 (6 au plus).
  • Lister : GET /subjects (?type=location pour filtrer) rend tes sujets, ceux de la Bibliothèque de l'appli compris (origin app), et le plafond max. Un sujet de l'appli dont toutes les images ne sont pas encore synchronisées a complete: 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, MCP tendre_subject_list) et ne compte pas dans le plafond max. 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} avec type, name, description et/ou images_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.

ChampTypeCe que ça fait
typeobject, location, animal, style ou outfitLe genre du sujet (le mouvement ne se génère pas)
nameun mot, 1 à 40 lettres, chiffres ou _Celui écrit après @ dans le prompt
descriptiontexte anglais, 300 caractères au plusL'é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
prompttexte anglais, 2 000 caractères au plus, facultatifLe texte complet de l'image de départ, à la place du texte automatique tiré de description
start_image_b64image en base64, facultativeUne image de départ importée (512 px au moins), gardée telle quelle et gratuite
viewsliste de clés, facultativeLes vues voulues, dans l'ordre (tableau ci-dessous)
count1 à 6, facultatifÀ la place de views : le nombre d'images en tout, départ compris (les premières vues du tableau)
seedentier, facultatifSeed de l'image de départ
quote_onlytrueRend seulement le prix, rien n'est créé

Vues par genre (clés stables), au format de sortie du genre :

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

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

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}/views avec views (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 besoin instructions. La vue repart de l'image de départ et remplace la précédente (même n).
  • Refaire le départ : POST /subjects/{id}/views/start/redo, seulement tant qu'aucune vue n'en est partie (refus views_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: true rend 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 :

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

Windows · Mac · Cloud ou local

Génère en privé. Ce soir.

Télécharge tendre.AI gratuitement et génère sans limites, en privé, sur ton propre GPU.

OS Windows 10/11GPU NVIDIA 8 Go+VRAM 12 Go recommandésDisque 20 Go

Mac avec puce Apple (M1 ou plus récente) : macOS 13 ou plus récent. Mac Intel : macOS 12 ou plus récent, tout se fait en ligne.

Sur Mac, la génération d'images en local demande un M4 avec 24 Go de mémoire, ou un M2 ou M3 Pro, Max ou Ultra avec 24 Go. En dessous, tout fonctionne en ligne avec les crédits. La retouche et la vidéo se font en ligne sur Mac pour l'instant.

Tout sur tendre.AI pour Mac

Pas de GPU NVIDIA ? Démarre à 100 % dans le cloud : 5 images et 1 vidéo gratuites chaque jour. Une carte NVIDIA (8 Go+) débloque la génération locale illimitée.