Pro API: personages maken voor Multi-Ref Video
Een personage is een sheet van zeven weergaven van dezelfde persoon (of een wezen), gemaakt van één foto
en opgeslagen onder een character_id. Dit is wat Multi-Ref Video gebruikt om
iemand in een clip te herkennen: de weergaven dragen de gelijkenis, zonder training.
Face swap gebruikt ze ook, om het personage in de plaats te zetten van de persoon in je
eigen video.
De personages die je in de app hebt gemaakt, zijn er al: zelfde licentie, zelfde lijst (zie Personages uit de app). Locaties, objecten en dieren worden op dezelfde manier opgeslagen, van afbeeldingen die je aanlevert, en spelen in dezelfde clips (zie Locaties, objecten en dieren).
De zeven weergaven
| Rol | Weergave |
|---|---|
| 1 | Buste vooraanzicht, neutrale uitdrukking |
| 4 | Ten voeten uit, vooraanzicht |
| 5 | Ten voeten uit, rug |
| 6 | Ten voeten uit en profil, het personage kijkt naar links in de afbeelding |
| 7 | Close-up van het gezicht, vooraanzicht |
| 8 | Close-up van de outfit, van de borst tot de knieën |
| 9 | Close-up van de voeten, met schoenen of blootsvoets afhankelijk van de outfit |
Elke weergave wordt afzonderlijk gegenereerd: geen enkele wordt verkregen door een andere te spiegelen. De rollen 2 en 3 (driekwart bustes) worden sinds 21 oktober 2026 niet meer gemaakt: een personage van daarvoor houdt ze, en ze zijn nog te lezen (bestand van een weergave, lijst views), maar niet meer opnieuw te maken (400 invalid_role).
Een personage aanmaken
POST /characters (permissie images). Het werk is asynchroon.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Veld | Type | Wat het doet |
|---|---|---|
name | string, 1 tot 40 tekens | De voornaam van het personage |
kind | string | woman, man, of een wezen beschreven in het Engels (baby dragon). Bepaalt de voornaamwoorden in de instructies, nooit "they". |
image_b64 | base64 | De foto: scherp, slechts één persoon, minimaal 1024 px aan de lange zijde, maximaal 12 MB, JPEG, PNG of WebP |
photo_role | bust (standaard) of full_body | De foto is een buste (wordt weergave 1) of een volledige opname (weergave 4) |
outfit | Engelse tekst, optioneel | Bij een bustefoto de outfit van de volledige weergave (a red leather jacket and black jeans): het onderlichaam, dat de buste niet toont. Bij een foto van het hele lichaam geldt de foto en wordt de outfit niet aangebracht |
Het antwoord, 202, is het personage met status pending en cost_estimate. De foto wordt de weergave van zijn rol, ongewijzigd bewaard (nooit omgekleed), en de server genereert de andere zes, in 2 tot 5 minuten, op dezelfde manier als de app: het lichaam (rug, profiel, outfit, voeten) gaat uit van de volledige weergave, de close-up van het gezicht van de buste. Een bustefoto wordt doorgetrokken tot een volledige weergave (in outfit als die is opgegeven); een foto van het hele lichaam geeft de buste door een uitsnede.
Prijs: één credit per gegenereerde weergave, dus 6 credits, met of zonder outfit. Een mislukte weergave wordt niet in rekening gebracht. POST /characters/quote geeft de prijs vooraf.
Dezelfde aanmaak opnieuw sturen. Valt de verbinding weg vóór het antwoord, of wordt het wachten van een agent onderbroken, dan maakt de server het personage gewoon verder af. Stuur hetzelfde verzoek opnieuw (dezelfde foto, name, kind, photo_role en outfit): je krijgt het al aangemaakte personage terug, met existing: true en een cost_estimate van 0, en er wordt niets twee keer in rekening gebracht. Er komt alleen een nieuw personage als alle gegenereerde weergaven van het eerste mislukt zijn; een paar mislukte weergaven worden een voor een opnieuw gemaakt (redo). Komen twee identieke verzoeken op hetzelfde moment binnen, dan krijgt het tweede 409 character_busy: stuur het een paar seconden later opnieuw.
Volgen, controleren, opnieuw maken
GET /characters/{id} geeft de toestand:
status | Betekenis |
|---|---|
pending | De weergaven worden aangemaakt |
ready | De zeven weergaven zijn er |
partial | Sommige weergaven ontbreken of zijn mislukt |
failed, empty | Geen bruikbare weergave |
{
"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"
}- Controleer de weergaven vóór de eerste render.
GET /characters/{id}/views/{role}/filegeeft de afbeelding terug. De volledige weergaven (4, 5 en 6) worden in 2K gemaakt, 1024 x 2048, en de buste en de close-ups in 832 x 1216 (1216 x 832 voor de voeten), als PNG, of als JPEG boven 2,9 MB. De weergave uit je foto behoudt haar formaat (maximaal 2048 px). Weergaven die al gemaakt zijn, houden hun formaat; een opnieuw gemaakte weergave komt in deze formaten. Een mislukte weergave, of een profiel dat de verkeerde kant op kijkt, bederft de gelijkenis in elke video. - Weergave opnieuw maken:
POST /characters/{id}/views/{role}/redo, 1 credit: een nieuwe generatie vanaf haar startpunt (de volledige weergave of de buste). De weergave die afkomstig is van de originele foto kan niet opnieuw worden gemaakt (photo_view), met of zonderoutfit. Een sheet die in de app als één afbeelding is geïmporteerd (een hele sheet, ongewijzigd bewaard) wordt niet per weergave opnieuw gemaakt (409 single_image_sheet). - Een opnieuw gemaakte weergave sturen: voeg
instruction(200 tekens, Engels) toe aan de redo-body, voor een personage aangemaakt via de API, of een sheet die via de API is toegevoegd (anders409 app_character). Het specificeert wat de weergave van het personage moet tonen, zoals de zijde van een prothese of de aanwezigheid van een detail, nooit een andere wijziging: outfit, haar, pose, omgeving en uitdrukking worden elders gewijzigd. Schrijf het in de gebiedende wijs (de engine negeert een beschreven toestand):"Put the robotic arm on her left side only, remove any second robotic arm."Op de rugweergave (5), benoem de zijde op beide manieren:"her left arm, which appears on the left side of the image when seen from behind". Zelfde prijs, 1 credit. - Je eigen afbeelding uploaden voor een weergave:
PUT /characters/{id}/views/{role}metimage_b64(dezelfde regels als de aanmaakfoto: minimaal 1024 px aan de lange zijde, 12 MB, JPEG, PNG of WebP), voor een personage aangemaakt via de API, of een sheet die via de API is toegevoegd (?sheet=). Gratis, er wordt niets gegenereerd. De afbeelding wordt ongewijzigd bewaard en telt als een echte foto: de weergaven die daarna opnieuw worden gemaakt, gaan er volgens de regel van het aanmaken van uit (de rug, het profiel en de close-ups van de outfit en de voeten van de volledige weergave, de close-up van het gezicht van de buste). - Lijst:
GET /charactersgeeft je personages terug, inclusief die van de app, en het maximummax. - Verwijderen:
DELETE /characters/{id}wist het personage en zijn weergaven.
In de app (versie 0.8.6 en later): een personage aangemaakt via de API of de MCP verschijnt in het
scherm Mijn personages van de app, op dezelfde licentie, met zijn naam en weergaven, net als de personages die in
de app zijn aangemaakt. Een weergave die opnieuw is gemaakt in de app vervangt de online weergave, de weergave die Multi-Ref Video leest. Het verwijderen in de app wist het hier ook, definitief (de app vraagt eerst om bevestiging): een pipeline die een
character_id bijhoudt, moet een 404 unknown_character verwachten zodra het personage in de app is verwijderd.
Personages uit de app
Een personage aangemaakt in het scherm Mijn personages van de app verschijnt in GET /characters met origin
app, en speelt in Multi-Ref Video zoals elk ander. In de app kan een personage meerdere
sheets hebben (outfits, stemmingen): sheet_id geeft aan welke wordt gebruikt (standaard de meest recente), sheets
geeft ze weer, en ?sheet=<id> vraagt er een andere op bij het lezen, bij het bestand van een weergave en bij een opnieuw gemaakte weergave.
In een Multi-Ref clip kiest characters[].sheet_id de sheet. Het draagt de name en kind van zijn profiel in de app zodra de app ze heeft verstuurd (app 0.9.1 en later; daarvoor zijn beide null). Om een weergave van een app-personage waarvan kind nog null is opnieuw te maken,
geef je kind mee in de body.
Stem. has_voice zegt of de stem uit het profiel van het personage online is: de app stuurt die mee met het personage, en Face swap en Multi-Ref Video gebruiken die standaard.
Een outfit aan een personage toevoegen
POST /characters/{id}/sheets geeft een bestaand personage een nieuwe sheet (een outfit, een look), of het nu via de API of in de app is gemaakt, de presets van de app inbegrepen. Het personage houdt zijn andere sheets. Het antwoord, 202, is het personage met de nieuwe sheet: zijn sheet_id (die begint met api-), sheet_name, sheet_outfit, sheet_origin: "api" en cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Veld | Type | Wat het doet |
|---|---|---|
name | string, 1 tot 40 tekens | De naam van de sheet |
outfit | Engelse tekst, maximaal 700 tekens | De outfit om aan te trekken; verplicht zonder views |
views | object, rol "1" of "4" tot "9": een afbeelding in base64 | Weergaven die al klaar zijn, met dezelfde regels als het uploaden van een weergave |
generate | true (standaard) of false | De ontbrekende rollen genereren, of geen |
from_sheet_id | string, optioneel | Zonder views: de sheet om van uit te gaan |
kind | string | Alleen voor een personage dat in de app is gemaakt en waarvan kind nog null is in GET /characters, zoals bij het aanmaken |
- Met
views: de weergaven die je stuurt worden opgeslagen zoals ze zijn, gratis. De ontbrekende rollen worden gegenereerd, 1 credit per weergave, volgens de regel van het aanmaken, vanuit de volledige weergave en de buste die je stuurt; staat geen van beide erbij, dan zoals zonderviews.generate: falsegenereert er geen. - Zonder
views: de outfit wordt op de volledige weergave van het personage gezet (op zijn buste als het er geen heeft;from_sheet_idgaat uit van een andere sheet). Het resultaat wordt de volledige weergave van de nieuwe sheet, en de zes andere weergaven gaan ervan uit: 7 gegenereerde weergaven, 7 credits.cost_estimategeeft de prijs. Is de bron-sheet (from_sheet_id, of de standaard) zo'n enkele afbeelding, stuur dan weergave 4 (ten voeten uit) of 1 (buste) inviews(409 single_image_sheet). - Gebruik de sheet zoals de andere, met
?sheet=<sheet_id>: bijGET /characters/{id}, bij het bestand van een weergave, bijredo(instructioninbegrepen) en bij dePUTvan een weergave. In een Multi-Ref-clip kiestcharacters[].sheet_idhem. - Geef bij een personage uit de app
sheet_idmee: standaard blijft de laatst gewijzigde sheet in gebruik, dus nu de sheet die je net hebt toegevoegd. - Een toegevoegde sheet verwijderen:
DELETE /characters/{id}/sheets/{sheet_id}verwijdert alleen zijn weergaven. Een sheet die in de app is gemaakt, verwijder je zo niet (404 unknown_sheet). - In de app: de app met dezelfde licentie haalt de nieuwe sheet in het profiel van het personage.
- Fouten:
400 outfit_or_views_required(geen outfit en geen weergaven),400 views_required(generate: falsezonder weergave),409 source_sheet_empty(geen volledige weergave en geen buste om van uit te gaan),409 character_busy.
Locaties, objecten, dieren, stijlen en outfits
Een onderwerp is een locatie (location), een object (object: een voertuig, een prop, een stuk
meubilair...), een dier (animal), een stijl (style: sfeerbeelden waarvan de video de look overneemt) of een outfit (outfit: een kledingstuk dat een personage draagt), opgeslagen van 1 tot 6 afbeeldingen die je aanlevert (meerdere hoeken
maken het getrouwer), zodat je het opnieuw kunt gebruiken in Multi-Ref Video
zonder het in elke opname opnieuw te beschrijven. Er wordt geen afbeelding gegenereerd, dus het is gratis.
Zonder afbeeldingen kan de server het ook genereren: zie Een onderwerp zonder afbeeldingen genereren.
POST /subjects (permissie images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Veld | Type | Wat het doet |
|---|---|---|
type | location, object, animal, style of outfit | Wat het onderwerp is |
name | één woord, 1 tot 40 letters, cijfers of _ | Het woord dat na @ in de prompt wordt geschreven |
description | Engelse tekst, maximaal 300 tekens, optioneel | a glossy white futuristic tram with round windows |
images_b64 | 1 tot 6 afbeeldingen in base64 | JPEG, PNG of WebP, minimaal 512 px aan de lange zijde, maximaal 12 MB elk (28 MB voor de hele body: voeg de volgende daarna één voor één toe) |
Het antwoord, 201, is het onderwerp: subject_id, type, name, description, origin, zijn images
(elk met een file_url), complete en expires_at.
- Een afbeelding toevoegen:
POST /subjects/{id}/imagesmetimage_b64(maximaal 6). - Lijst:
GET /subjects(?type=locationom te filteren) geeft je onderwerpen terug, inclusief die van de Bibliotheek van de app (originapp), en het maximummax. Een app-onderwerp waarvan nog niet alle afbeeldingen zijn gesynchroniseerd, heeftcomplete: false: het speelt met de al aanwezige afbeeldingen. - Aangeboden elementen: Tendre.AI biedt kant-en-klare elementen met een vaste id (bijvoorbeeld
officiel-red-beetle, een object). Elk wordt één keer aan je lijst toegevoegd wanneer je die voor het eerst leest (GET /subjects, MCPtendre_subject_list) en telt niet mee voor de grensmax. Daarna is het een subject zoals de andere: bruikbaar in Multi-Ref (subject_id), aanpasbaar, verwijderbaar; eenmaal verwijderd, komt het nooit terug. - Lezen:
GET /subjects/{id}; één afbeelding:GET /subjects/{id}/images/{n}/file. - Wijzigen:
PUT /subjects/{id}mettype,name,descriptionen/ofimages_b64(de volledige lijst, die de afbeeldingen vervangt). - Verwijderen:
DELETE /subjects/{id}, hier en in de app.
Een stijl geeft een clip zijn look: de description noemt de techniek, in het Engels (loose watercolor painting on textured paper), niet wat de afbeeldingen tonen. Een outfit is een kledingstuk dat een personage draagt. Stijlen en outfits werken alleen in Multi-Ref Video, in Ultra.
Om een onderwerp in een clip te gebruiken, zie Multi-Ref Video; in een afbeelding, zie Afbeelding maken.
Een onderwerp zonder afbeeldingen genereren
Geen afbeelding bij de hand? POST /subjects/generate (recht images) maakt het onderwerp zoals het venster ‘Genereren’ van de Elementen in de app: een startafbeelding op basis van je beschrijving (of geïmporteerd), en dan weergaven die ervan uitgaan (andere hoeken, een close-up, bij nacht...), elk bewerkt vanuit de startafbeelding om dezelfde vorm te houden. Het resultaat is een gewoon onderwerp: het speelt mee in Multi-Ref Video en in Afbeelding maken, en het verschijnt in de Bibliotheek van de app.
| Veld | Type | Wat het doet |
|---|---|---|
type | object, location, animal, style of outfit | Wat het onderwerp is (een beweging wordt niet gegenereerd) |
name | één woord, 1 tot 40 letters, cijfers of _ | Het woord na @ in de prompt |
description | Engelse tekst, maximaal 300 tekens | Het element alleen: vorm, materialen, kleuren, details, zonder achtergrond of personage (a glossy white futuristic tram with round windows). Verplicht, behalve met prompt of start_image_b64 |
prompt | Engelse tekst, maximaal 2000 tekens, optioneel | De volledige tekst van de startafbeelding, in plaats van de automatische tekst uit description |
start_image_b64 | afbeelding in base64, optioneel | Een geïmporteerde startafbeelding (minstens 512 px), ongewijzigd bewaard en gratis |
views | lijst van sleutels, optioneel | De weergaven die je wilt, in volgorde (tabel hieronder) |
count | 1 tot 6, optioneel | In plaats van views: het aantal afbeeldingen in totaal, start inbegrepen (de eerste weergaven van de tabel) |
seed | geheel getal, optioneel | Seed van de startafbeelding |
quote_only | true | Geeft alleen de prijs terug, er wordt niets aangemaakt |
Weergaven per type (vaste sleutels), in het uitvoerformaat van het type:
type | Formaat | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (close-up) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (close-up) |
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 (close-up) |
Prijs: elke gerenderde afbeelding (de start en elke weergave) kost de prijs van één afbeelding (1 credit); een geïmporteerde start is gratis, en een mislukte afbeelding wordt niet afgeschreven. Maximaal 6 afbeeldingen per onderwerp, start inbegrepen. Het antwoord, 202, is het onderwerp met cost_estimate en 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"]
}Volg het met GET /subjects/{id} tot generation.status niet meer pending is (ready, partial of failed); n is het nummer van de afbeelding in images. De afbeeldingen gaan één voor één: de start, dan de weergaven in volgorde. Een mislukking stopt de reeks: de volgende weergaven worden failed, zonder afschrijving.
- Weergaven toevoegen:
POST /subjects/{id}/viewsmetviews(sleutels die nog niet gemaakt zijn). Met één weergave vervangtinstructions(Engels, maximaal 1000 tekens) de opdracht: zeg wat de weergave moet tonen. - Een weergave opnieuw maken:
POST /subjects/{id}/views/{key}/redo, zo nodig metinstructions. De weergave gaat opnieuw uit van de startafbeelding en vervangt de vorige (zelfden). - De start opnieuw maken:
POST /subjects/{id}/views/start/redo, alleen zolang er geen weergave van uitgaat (andersviews_exist); een geïmporteerde start kan niet opnieuw. Weergaven die door een mislukte start gestopt zijn, gaan daarna opnieuw. quote_only: truegeeft de prijs op alle drie de routes. Eén reeks tegelijk per onderwerp (subject_busy).
Van begin tot eind, een object met twee weergaven:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Het antwoord, 202, geeft de subject_id met generation.status pending. Vraag GET /subjects/{id} om de paar seconden op tot ready, en gebruik dan @Tram met die subject_id. Drie afbeeldingen (de start en twee weergaven), dus drie keer de prijs van één afbeelding.
Opslag
De personageweergaven en de onderwerpsafbeeldingen zijn versleuteld (één sleutel per bestand) en gekoppeld aan je
licentie. Onderwerpsafbeeldingen worden bewaard zoals je ze hebt verstuurd en gedeeld met de Bibliotheek van de app. Maxima met de
Pro-licentie: 50 personages, inclusief die van de app, en 50 onderwerpen (locaties, objecten, dieren, stijlen en outfits samen), apart geteld (10 met een persoonlijke licentie, in de app). Een personage of een onderwerp dat een jaar lang ongebruikt blijft,
wordt gewist (expires_at): elke Multi-Ref render, elke Face swap en elk lezen van een weergave of afbeelding
verschuift de datum. De foto die je verstuurt om een personage aan te maken, wordt bewaard als de weergave van zijn rol, versleuteld, net als de
gegenereerde weergaven. Je kunt ze op elk moment verwijderen.
Via een agent (MCP)
Met de MCP-server vraag je gewoon: "maak een personage van deze foto". De agent
gebruikt tendre_character_create (de foto komt via een uploadlink, een bestand bijgevoegd in ChatGPT,
een afbeelding gerenderd in het gesprek of een openbaar adres), toont je de zeven weergaven, en maakt een
mislukte weergave opnieuw met tendre_character_redo_view, met een instruction wanneer de weergave sturing nodig heeft, of
vervangt hem door je eigen afbeelding via tendre_character_set_view. tendre_character_get,
tendre_character_list en tendre_character_delete dekken de rest, en tendre_quote geeft de
prijs vooraf.
Voor een locatie, een object of een dier geef je de agent je afbeeldingen en zeg je wat het is: het gebruikt
tendre_subject_create, dan tendre_subject_list, tendre_subject_get en tendre_subject_delete. Zonder afbeeldingen gebruikt het tendre_subject_generate, en dan tendre_subject_add_views en tendre_subject_redo_view om een weergave toe te voegen of opnieuw te maken.
Voeg daarna het personage toe aan een clip: zie Multi-Ref Video.