Pro API: skapa karaktärer för Multi-Ref Video
En karaktär är ett sheet med sju vyer av samma person (eller varelse), skapad från ett foto
och lagrad under ett character_id. Det är vad Multi-Ref Video använder för att
känna igen någon i ett klipp: vyerna bär likheten, utan träning.
Face swap använder dem också, för att placera karaktären i stället för personen i ditt
eget klipp.
Karaktärerna du skapade i appen finns redan där: samma licens, samma lista (se Karaktärer från appen). Platser, objekt och djur lagras på samma sätt, från bilder du tillhandahåller, och används i samma klipp (se Platser, objekt och djur).
De sju vyerna
| Roll | Vy |
|---|---|
| 1 | Byst, framifrån, neutralt uttryck |
| 4 | Helbild, framifrån |
| 5 | Helbild, bakifrån |
| 6 | Helbild i profil, karaktären tittar mot bildens vänstra sida |
| 7 | Närbild av ansiktet, framifrån |
| 8 | Närbild av outfiten, från bröstet till knäna |
| 9 | Närbild av fötterna, med skor eller barfota beroende på outfiten |
Varje vy genereras individuellt: ingen erhålls genom att spegla en annan. Rollerna 2 och 3 (byster i tre kvarts profil) skapas inte längre sedan den 21 oktober 2026: en karaktär som skapats tidigare behåller dem, och de kan fortfarande läsas (en vys fil, listan views) men inte göras om (400 invalid_role).
Skapa en karaktär
POST /characters (behörighet images). Arbetet är asynkront.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Fält | Typ | Vad det gör |
|---|---|---|
name | sträng, 1 till 40 tecken | Karaktärens förnamn |
kind | sträng | woman, man eller en varelse beskriven på engelska (baby dragon). Det styr pronomen i instruktionerna, aldrig "they". |
image_b64 | base64 | Fotot: skarpt, en person endast, minst 1024 px på den långa sidan, max 12 MB, JPEG, PNG eller WebP |
photo_role | bust (standard) eller full_body | Fotot är en byst (det blir vy 1) eller ett helbildsfoto (vy 4) |
outfit | Engelsktext, valfritt | Med ett bystfoto: outfiten för helbildsvyn (a red leather jacket and black jeans), alltså underkroppen som bysten inte visar. Med ett helbildsfoto gäller fotot och outfiten sätts inte på |
Svaret, 202, är karaktären med status pending och cost_estimate. Fotot blir vyn för sin roll, sparas som det är (klärs aldrig om), och servern genererar de andra sex, på 2 till 5 minuter, på samma sätt som appen: kroppen (rygg, profil, outfit, fötter) utgår från helbildsvyn, närbilden av ansiktet från bysten. Ett bystfoto förlängs till helbildsvyn (i outfit om den anges); ett helbildsfoto ger bysten genom en beskärning.
Pris: en kredit per genererad vy, alltså 6 krediter, med eller utan outfit. En vy som misslyckas debiteras inte. POST /characters/quote anger priset i förväg.
Skicka samma skapande igen. Om anslutningen bryts före svaret, eller om en agents väntan avbryts, fortsätter servern att skapa karaktären. Skicka samma förfrågan igen (samma foto, name, kind, photo_role och outfit): den returnerar den karaktär som redan skapats, med existing: true och en cost_estimate på 0, och inget debiteras två gånger. Den skapar bara en ny om alla genererade vyer av den första misslyckades; enstaka misslyckade vyer görs om en i taget (redo). Om två identiska förfrågningar kommer i samma ögonblick får den andra 409 character_busy: skicka den igen några sekunder senare.
Följ, kontrollera, gör om
GET /characters/{id} visar dess tillstånd:
status | Betydelse |
|---|---|
pending | Vyerna håller på att skapas |
ready | De sju vyerna finns |
partial | Vissa vyer saknas eller misslyckades |
failed, empty | Ingen användbar vy |
{
"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"
}- Kontrollera vyerna innan den första renderingen.
GET /characters/{id}/views/{role}/filereturnerar bilden. Helbildsvyerna (4, 5 och 6) genereras i 2K, 1024 x 2048, och bysten och närbilderna i 832 x 1216 (1216 x 832 för fötterna), som PNG, eller som JPEG över 2,9 MB. Vyn från ditt foto behåller sin storlek (högst 2048 px). Vyer som redan finns behåller sin storlek; en vy som görs om kommer i dessa storlekar. En misslyckad vy, eller en profil som tittar åt fel håll, förstör likheten i varje video. - Gör om en vy:
POST /characters/{id}/views/{role}/redo, 1 kredit: en ny generering från dess utgångspunkt (helbildsvyn eller bysten). Den vy som kom från originalfotot kan inte göras om (photo_view), med eller utanoutfit. Ett sheet som importerats i appen som en enda bild (ett helt sheet, sparat som det är) görs inte om vy för vy (409 single_image_sheet). - Vägled en omgjord vy: lägg till
instruction(200 tecken, engelska) i redo-kroppen, för en karaktär skapad via API:et, eller en character sheet som lagts till via API:et (annars409 app_character). Den specificerar vad vyn måste visa av karaktären, till exempel sidan av en protes eller närvaron av ett detalj, aldrig en annan förändring: plagg, hår, pose, miljö och uttryck ändras på annat håll. Skriv i imperativ (motorn ignorerar ett beskrivet tillstånd):"Put the robotic arm on her left side only, remove any second robotic arm."På bakvy (5), namnge sidan på båda sätten:"her left arm, which appears on the left side of the image when seen from behind". Samma pris, 1 kredit. - Ladda upp din egen bild för en vy:
PUT /characters/{id}/views/{role}medimage_b64(samma regler som skapandefotot: minst 1024 px på den långa sidan, 12 MB, JPEG, PNG eller WebP), för en karaktär skapad via API:et, eller en character sheet som lagts till via API:et (?sheet=). Kostnadsfritt, inget genereras. Bilden sparas som den är och räknas som ett riktigt foto: vyerna som görs om efteråt utgår från den enligt regeln vid skapandet (ryggen, profilen och närbilderna av outfiten och fötterna från helbildsvyn, närbilden av ansiktet från bysten). - Lista:
GET /charactersreturnerar dina karaktärer, inklusive appens, och gränsenmax. - Ta bort:
DELETE /characters/{id}raderar karaktären och dess vyer.
I appen (version 0.8.6 och senare): en karaktär skapad via API:et eller MCP visas på
appens My characters-skärm, på samma licens, med sitt namn och sina vyer, precis som de skapade i
appen. En vy som görs om i appen ersätter onlinevyn, den som Multi-Ref Video läser. Om du tar bort den
i appen raderas den här också, permanent (appen ber om bekräftelse först): en pipeline som behåller ett
character_id bör förvänta sig ett 404 unknown_character när karaktären tagits bort i appen.
Karaktärer från appen
En karaktär skapad på appens My characters-skärm visas i GET /characters med origin
app, och används i Multi-Ref Video precis som alla andra. I appen kan en karaktär ha flera
sheets (plagg, stämningar): sheet_id anger vilket som serveras (det senaste som standard), sheets
listar dem, och ?sheet=<id> begär ett annat vid läsning, på en vys fil och på en omgjord vy.
I ett Multi-Ref-klipp väljer characters[].sheet_id sheetet. Den har name och kind från sin profil i appen så snart appen har skickat dem (app 0.9.1 och senare; innan dess är båda null). För att göra om en vy för en appkaraktär vars kind fortfarande är null
anger du dess kind i kroppen.
Röst. has_voice anger om rösten i karaktärens profil finns online: appen skickar den med karaktären, och Face swap och Multi-Ref Video använder den som standard.
Lägg till en outfit på en karaktär
POST /characters/{id}/sheets ger en befintlig karaktär en ny character sheet (en outfit, en look), oavsett om den skapades via API:et eller i appen, appens förval inräknade. Karaktären behåller sina andra character sheets. Svaret, 202, är karaktären med den nya character sheet: dess sheet_id (den börjar med api-), sheet_name, sheet_outfit, sheet_origin: "api" och cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Fält | Typ | Vad det gör |
|---|---|---|
name | sträng, 1 till 40 tecken | Namnet på character sheet |
outfit | engelsk text, högst 700 tecken | Outfiten att sätta på; obligatorisk utan views |
views | objekt, roll "1" eller "4" till "9": en bild i base64 | Vyer som redan är klara, med samma regler som när du laddar upp en vy |
generate | true (standard) eller false | Generera de roller som saknas, eller inga |
from_sheet_id | sträng, valfritt | Utan views: den character sheet att utgå från |
kind | sträng | Bara för en karaktär skapad i appen vars kind fortfarande är null i GET /characters, som vid skapandet |
- Med
views: vyerna du skickar sparas som de är, gratis. Rollerna som saknas genereras, 1 kredit per vy, enligt regeln vid skapandet, utifrån helbildsvyn och bysten du skickar; utan någon av dem som utanviews.generate: falsegenererar inga. - Utan
views: outfiten sätts på karaktärens helbildsvy (på dess byst om den saknar en;from_sheet_idutgår från en annan character sheet). Resultatet blir helbildsvyn för den nya character sheeten, och de sex andra vyerna utgår från det: 7 genererade vyer, 7 krediter.cost_estimateanger priset. Om käll-sheetet (from_sheet_id, eller standardsheetet) är en sådan enda bild, skicka vy 4 (helfigur) eller 1 (byst) iviews(409 single_image_sheet). - Använd character sheet som de andra, med
?sheet=<sheet_id>: påGET /characters/{id}, på en vys fil, påredo(instructioninräknad) och påPUTav en vy. I ett Multi-Ref-klipp väljercharacters[].sheet_idden. - För en karaktär från appen, skicka med
sheet_id: som standard används fortfarande den senast ändrade character sheet, alltså den du just lade till. - Ta bort en tillagd character sheet:
DELETE /characters/{id}/sheets/{sheet_id}raderar bara dess vyer. En character sheet som gjorts i appen tas inte bort så (404 unknown_sheet). - I appen: appen med samma licens hämtar in den nya character sheet i karaktärens profil.
- Fel:
400 outfit_or_views_required(varken outfit eller vyer),400 views_required(generate: falseutan vy),409 source_sheet_empty(varken helbildsvy eller byst att utgå från),409 character_busy.
Platser, objekt, djur, stilar och outfits
Ett subjekt är en plats (location), ett objekt (object: ett fordon, en rekvisita, en möbel...),
ett djur (animal), en stil (style: stämningsbilder vars utseende videon tar över) eller en outfit (outfit: ett plagg som en karaktär bär), sparat från 1 till 6 bilder som du tillhandahåller (flera vinklar
gör det mer troget), så att du kan använda det igen i Multi-Ref Video
utan att beskriva det på nytt i varje tagning. Ingen bild genereras, så det är kostnadsfritt.
Utan bilder kan servern också generera det: se Generera ett subjekt utan bilder.
POST /subjects (behörighet images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Fält | Typ | Vad det gör |
|---|---|---|
type | location, object, animal, style eller outfit | Vad subjektet är |
name | ett ord, 1 till 40 bokstäver, siffror eller _ | Ordet som skrivs efter @ i prompten |
description | Engelsktext, max 300 tecken, valfritt | a glossy white futuristic tram with round windows |
images_b64 | 1 till 6 bilder i base64 | JPEG, PNG eller WebP, minst 512 px på den långa sidan, max 12 MB per styck (28 MB för hela kroppen: därutöver lägger du till nästa en i taget) |
Svaret, 201, är subjektet: subject_id, type, name, description, origin, dess images
(var och en med en file_url), complete och expires_at.
- Lägg till en bild:
POST /subjects/{id}/imagesmedimage_b64(max 6). - Lista:
GET /subjects(?type=locationför att filtrera) returnerar dina subjekt, inklusive appens Library (originapp), och gränsenmax. Ett appsubjekt vars bilder inte alla är synkade ännu harcomplete: false: det används med de bilder som redan finns. - Bjudna element: Tendre.AI bjuder på färdiga element med ett fast id (till exempel
officiel-red-beetle, ett föremål). Vart och ett läggs till en gång i din lista första gången du läser den (GET /subjects, MCPtendre_subject_list) och räknas inte in i gränsenmax. Sedan är det ett subjekt som de andra: användbart i Multi-Ref (subject_id), ändringsbart, raderbart; när det väl är raderat kommer det aldrig tillbaka. - Läs:
GET /subjects/{id}; en bild:GET /subjects/{id}/images/{n}/file. - Ändra:
PUT /subjects/{id}medtype,name,descriptionoch/ellerimages_b64(hela listan, som ersätter bilderna). - Ta bort:
DELETE /subjects/{id}, här och i appen.
En stil ger ett klipp dess utseende: dess description anger tekniken, på engelska (loose watercolor painting on textured paper), inte vad bilderna visar. En outfit är ett plagg som en karaktär bär. Stilar och outfits fungerar bara i Multi-Ref Video, i Ultra.
För att använda ett subjekt i ett klipp, se Multi-Ref Video; i en bild, se Create an image.
Generera ett subjekt utan bilder
Ingen bild till hands? POST /subjects/generate (behörighet images) skapar subjektet som fönstret "Generate" under Elements i appen: en startbild utifrån din beskrivning (eller importerad), sedan vyer som utgår från den (andra vinklar, en närbild, på natten...), var och en retuscherad från startbilden för att behålla samma form. Resultatet är ett vanligt subjekt: det fungerar i Multi-Ref Video och i Create an image, och det syns i appens bibliotek.
| Fält | Typ | Vad det gör |
|---|---|---|
type | object, location, animal, style eller outfit | Vad subjektet är (en rörelse genereras inte) |
name | ett ord, 1 till 40 bokstäver, siffror eller _ | Ordet efter @ i prompten |
description | text på engelska, högst 300 tecken | Elementet ensamt: form, material, färger, detaljer, utan bakgrund och utan karaktär (a glossy white futuristic tram with round windows). Krävs utom med prompt eller start_image_b64 |
prompt | text på engelska, högst 2 000 tecken, valfri | Hela texten för startbilden, i stället för den automatiska texten från description |
start_image_b64 | bild i base64, valfri | En importerad startbild (minst 512 px), sparad som den är och gratis |
views | lista med nycklar, valfri | De vyer du vill ha, i ordning (tabellen nedan) |
count | 1 till 6, valfri | I stället för views: antalet bilder totalt, start inräknad (de första vyerna i tabellen) |
seed | heltal, valfri | Seed för startbilden |
quote_only | true | Returnerar bara priset, inget skapas |
Vyer per typ (fasta nycklar), i typens utdataformat:
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (närbild) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (närbild) |
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 (närbild) |
Pris: varje renderad bild (starten och varje vy) kostar priset för en bild (1 kredit); en importerad start är gratis, och en misslyckad bild debiteras inte. Högst 6 bilder per subjekt, start inräknad. Svaret, 202, är subjektet med cost_estimate och 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"]
}Följ det med GET /subjects/{id} tills generation.status inte längre är pending (ready, partial eller failed); n är bildens nummer i images. Bilderna görs en i taget: starten, sedan vyerna i ordning. Ett fel stoppar serien: följande vyer blir failed, utan debitering.
- Lägg till vyer:
POST /subjects/{id}/viewsmedviews(nycklar som inte är gjorda än). Med en vy ersätterinstructions(engelska, högst 1 000 tecken) dess instruktion: säg vad vyn ska visa. - Gör om en vy:
POST /subjects/{id}/views/{key}/redo, medinstructionsvid behov. Vyn utgår igen från startbilden och ersätter den förra (samman). - Gör om starten:
POST /subjects/{id}/views/start/redo, bara så länge ingen vy utgår från den (annarsviews_exist); en importerad start kan inte göras om. Vyer som stoppats av en misslyckad start körs igen efter den. quote_only: trueger priset på alla tre rutterna. En serie åt gången per subjekt (subject_busy).
Från början till slut, ett objekt med två vyer:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Svaret, 202, ger subject_id med generation.status pending. Fråga GET /subjects/{id} med några sekunders mellanrum tills det är ready, och använd sedan @Tram med det subject_id. Tre bilder (starten och två vyer), alltså tre gånger priset för en bild.
Lagring
Karaktärsvyerna och subjektbilderna är krypterade (en nyckel per fil) och kopplade till din
licens. Subjektbilder sparas precis som du skickade dem och delas med appens Library. Gränser med
Pro-licensen: 50 karaktärer, inklusive appens, och 50 subjekt (platser, objekt, djur, stilar och outfits sammanlagt), räknade
separat (10 med en personlig licens, i appen). En karaktär eller ett subjekt som inte används på ett år
raderas (expires_at): varje Multi-Ref-rendering, varje Face swap och varje läsning av en vy eller bild
skjuter datumet framåt. Fotot du skickar för att skapa en karaktär sparas som vyn för sin roll, krypterat, precis som
de genererade vyerna. Du kan ta bort dem när som helst.
Via en agent (MCP)
Med MCP-servern räcker det att be: "make a character from this photo". Agenten
använder tendre_character_create (fotot kommer via en uppladdningslänk, en bifogad fil i ChatGPT,
en bild renderad i konversationen eller en offentlig adress), visar dig de sju vyerna och gör om en
misslyckad vy med tendre_character_redo_view, med en instruction när vyn behöver vägled ning, eller
ersätter den med din egen bild via tendre_character_set_view. tendre_character_get,
tendre_character_list och tendre_character_delete täcker resten, och tendre_quote anger priset först.
För en plats, ett objekt eller ett djur ger du agenten dina bilder och beskriver vad det är: agenten använder
tendre_subject_create, sedan tendre_subject_list, tendre_subject_get och tendre_subject_delete. Utan bilder använder agenten tendre_subject_generate, sedan tendre_subject_add_views och tendre_subject_redo_view för att lägga till eller göra om en vy.
Lägg sedan till karaktären i ett klipp: se Multi-Ref Video.