Pro API: opret karakterer til Multi-Ref Video
En karakter er et sheet med syv vinkler af den samme person (eller et væsen), lavet ud fra ét foto
og gemt under et character_id. Det er det, Multi-Ref Video bruger til
at genkende nogen i et klip: vinklerne bærer ligheden uden nogen træning.
Face swap bruger dem også til at sætte karakteren ind i stedet for personen i din
egen video.
De karakterer du har lavet i appen er allerede der: samme licens, samme liste (se Karakterer fra appen). Lokationer, objekter og dyr gemmes på samme måde ud fra billeder du leverer, og optræder i de samme klip (se Lokationer, objekter og dyr).
De syv vinkler
| Rolle | Vinkel |
|---|---|
| 1 | Bust, forfra, neutralt udtryk |
| 4 | Hel krop, forfra |
| 5 | Hel krop, bagfra |
| 6 | Hel krop i profil, karakteren kigger mod venstre i billedet |
| 7 | Nærbillede af ansigtet, forfra |
| 8 | Nærbillede af outfittet, fra brystet til knæene |
| 9 | Nærbillede af fødderne, med sko eller bare fødder afhængigt af outfittet |
Hver vinkel genereres for sig: ingen opnås ved at spejle en anden. Rollerne 2 og 3 (buster i trekvartprofil) laves ikke længere siden 21. oktober 2026: en karakter, der er lavet før, beholder dem, og de kan stadig læses (en vinkels fil, listen views), men ikke laves om (400 invalid_role).
Opret en karakter
POST /characters (tilladelse images). Arbejdet er asynkront.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Felt | Type | Hvad det gør |
|---|---|---|
name | streng, 1 til 40 tegn | Karakterens fornavn |
kind | streng | woman, man eller et væsen beskrevet på engelsk (baby dragon). Det sætter pronominerne i instruktionerne, aldrig "they". |
image_b64 | base64 | Fotoet: skarpt, kun én person, mindst 1024 px på den lange side, højst 12 MB, JPEG, PNG eller WebP |
photo_role | bust (standard) eller full_body | Fotoet er et bust (det bliver vinkel 1) eller et helkropsshot (vinkel 4) |
outfit | Engelsk tekst, valgfri | Med et bustefoto: outfittet i helkropsvinklen (a red leather jacket and black jeans), altså underkroppen, som busten ikke viser. Med et helkropsfoto gælder fotoet, og outfittet sættes ikke på |
Svaret, 202, er karakteren med status pending og cost_estimate. Fotoet bliver vinklen for dens rolle, bevares, som det er (klædes aldrig om), og serveren genererer de andre seks i løbet af 2 til 5 minutter, på samme måde som appen: kroppen (ryg, profil, outfit, fødder) tager udgangspunkt i helkropsvinklen, nærbilledet af ansigtet i busten. Et bustefoto forlænges til helkropsvinklen (i outfit, hvis det er angivet); et helkropsfoto giver busten ved beskæring.
Pris: ét kredit pr. genereret vinkel, altså 6 kreditter, med eller uden outfit. En vinkel der mislykkes, opkræves ikke. POST /characters/quote giver prisen på forhånd.
Send den samme oprettelse igen. Hvis forbindelsen afbrydes før svaret, eller en agents ventetid afbrydes, fortsætter serveren med at lave karakteren. Send den samme anmodning igen (samme foto, name, kind, photo_role og outfit): den returnerer den allerede oprettede karakter, med existing: true og en cost_estimate på 0, og der opkræves intet to gange. Den opretter kun en ny, hvis alle genererede visninger af den første mislykkedes; nogle få mislykkede visninger laves om én ad gangen (redo). Hvis to identiske anmodninger ankommer i samme øjeblik, får den anden 409 character_busy: send den igen nogle sekunder senere.
Følg, tjek, lav om
GET /characters/{id} giver karakterens tilstand:
status | Betydning |
|---|---|
pending | Vinklerne er ved at blive lavet |
ready | De syv vinkler er klar |
partial | Nogle vinkler mangler eller mislykkedes |
failed, empty | Ingen brugbar vinkel |
{
"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"
}- Tjek vinklerne inden den første render.
GET /characters/{id}/views/{role}/filereturnerer billedet. Helkropsvinklerne (4, 5 og 6) genereres i 2K, 1024 x 2048, og busten og nærbillederne i 832 x 1216 (1216 x 832 for fødderne), som PNG, eller som JPEG over 2,9 MB. Vinklen fra dit foto beholder sin størrelse (højst 2048 px). Vinkler, der allerede er lavet, beholder deres størrelse; en vinkel, der laves om, kommer i disse størrelser. En mislykket vinkel, eller en profil, der vender den forkerte vej, ødelægger ligheden i enhver video. - Lav en vinkel om:
POST /characters/{id}/views/{role}/redo, 1 kredit: en ny generering fra dens udgangspunkt (helkropsvinklen eller busten). Den vinkel der stammer fra det originale foto kan ikke laves om (photo_view), med eller udenoutfit. Et sheet, der er importeret i appen som ét billede (et helt sheet, bevaret som det er), laves ikke om visning for visning (409 single_image_sheet). - Guider en omlavet vinkel: tilføj
instruction(200 tegn, engelsk) til redo-kroppen for en karakter oprettet via API'et, eller en character sheet tilføjet via API'et (ellers409 app_character). Det specificerer hvad vinklen skal vise af karakteren, f.eks. siden af en protese eller tilstedeværelsen af en detalje, aldrig en anden ændring: outfit, hår, pose, omgivelser og udtryk ændres andre steder. Skriv det i bydemåde (motoren ignorerer en beskrevet tilstand):"Put the robotic arm on her left side only, remove any second robotic arm."På bagsiden (5) skal du nævne siden på begge måder:"her left arm, which appears on the left side of the image when seen from behind". Samme pris, 1 kredit. - Upload dit eget billede til en vinkel:
PUT /characters/{id}/views/{role}medimage_b64(samme regler som oprettelsesfotoet: mindst 1024 px på den lange side, 12 MB, JPEG, PNG eller WebP) for en karakter oprettet via API'et, eller en character sheet tilføjet via API'et (?sheet=). Gratis, intet genereres. Billedet bevares, som det er, og tæller som et rigtigt foto: de vinkler, der laves om bagefter, tager udgangspunkt i det efter reglen ved oprettelsen (ryggen, profilen og nærbillederne af outfittet og fødderne i helkropsvinklen, nærbilledet af ansigtet i busten). - Liste:
GET /charactersreturnerer dine karakterer inkl. appens og grænsenmax. - Slet:
DELETE /characters/{id}sletter karakteren og dens vinkler.
I appen (version 0.8.6 og nyere): en karakter oprettet via API'et eller MCP vises på appens
My characters-skærm under samme licens med navn og vinkler, ligesom dem der er oprettet i appen. En
vinkel der laves om i appen erstatter den online-vinkel som Multi-Ref Video læser. Sletter du den i
appen, slettes den også her for altid (appen beder om bekræftelse først): en pipeline der gemmer et
character_id, bør forvente en 404 unknown_character når karakteren er slettet i appen.
Karakterer fra appen
En karakter oprettet på appens My characters-skærm vises i GET /characters med origin
app og optræder i Multi-Ref Video som alle andre. I appen kan en karakter have flere
sheets (outfits, stemninger): sheet_id angiver hvilken der leveres (den nyeste som standard), sheets
lister dem, og ?sheet=<id> beder om en anden ved læsning, ved en vinkelsfil og ved en omlavet vinkel.
I et Multi-Ref-klip vælger characters[].sheet_id sheedet. Den har name og kind fra sin profil i appen, så snart appen har sendt dem (app 0.9.1 og nyere; før da er begge null). Angiv karakterens kind i kroppen for at
lave en vinkel om for en app-karakter, hvis kind stadig er null.
Stemme. has_voice angiver, om stemmen i karakterens profil er online: appen sender den med karakteren, og Face swap og Multi-Ref Video bruger den som standard.
Tilføj et outfit til en karakter
POST /characters/{id}/sheets giver en eksisterende karakter en ny character sheet (et outfit, et look), uanset om den blev oprettet via API'et eller i appen, appens forudindstillinger medregnet. Karakteren beholder sine andre character sheets. Svaret, 202, er karakteren med den nye character sheet: dens sheet_id (den begynder med api-), sheet_name, sheet_outfit, sheet_origin: "api" og cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Felt | Type | Hvad det gør |
|---|---|---|
name | streng, 1 til 40 tegn | Navnet på character sheet |
outfit | engelsk tekst, højst 700 tegn | Det outfit, der skal på; påkrævet uden views |
views | objekt, rolle "1" eller "4" til "9": et billede i base64 | Vinkler, der allerede er klar, med de samme regler som når du uploader en vinkel |
generate | true (standard) eller false | Generér de manglende roller, eller ingen |
from_sheet_id | streng, valgfri | Uden views: den character sheet, der tages udgangspunkt i |
kind | streng | Kun for en karakter oprettet i appen, hvis kind stadig er null i GET /characters, som ved oprettelsen |
- Med
views: de vinkler, du sender, gemmes, som de er, gratis. De manglende roller genereres, 1 kredit pr. vinkel, efter reglen ved oprettelsen, ud fra den helkropsvinkel og buste, du sender; uden nogen af dem som udenviews.generate: falsegenererer ingen. - Uden
views: outfittet sættes på karakterens helkropsvinkel (på busten, hvis den ikke har en;from_sheet_idtager udgangspunkt i en anden character sheet). Resultatet bliver helkropsvinklen i den nye character sheet, og de seks andre vinkler tager udgangspunkt i det: 7 genererede vinkler, 7 kreditter.cost_estimateoplyser prisen. Hvis kilde-sheetet (from_sheet_id, eller standardsheetet) er sådan et enkelt billede, så send visning 4 (helfigur) eller 1 (buste) iviews(409 single_image_sheet). - Brug character sheet som de andre, med
?sheet=<sheet_id>: påGET /characters/{id}, på en vinkels fil, påredo(instructionmedregnet) og påPUTaf en vinkel. I et Multi-Ref-klip vælgercharacters[].sheet_idden. - For en karakter fra appen, send
sheet_idmed: som standard bruges stadig den senest ændrede character sheet, altså den, du lige har tilføjet. - Slet en tilføjet character sheet:
DELETE /characters/{id}/sheets/{sheet_id}sletter kun dens vinkler. En character sheet lavet i appen slettes ikke på den måde (404 unknown_sheet). - I appen: appen med samme licens henter den nye character sheet ind i karakterens profil.
- Fejl:
400 outfit_or_views_required(hverken outfit eller vinkler),400 views_required(generate: falseuden vinkel),409 source_sheet_empty(hverken helkropsvinkel eller buste at tage udgangspunkt i),409 character_busy.
Lokationer, objekter, dyr, stilarter og outfits
Et subject er en lokation (location), et objekt (object: et køretøj, en rekvisit, et møbel...),
et dyr (animal), en stil (style: stemningsbilleder, hvis udtryk videoen overtager) eller et outfit (outfit: et stykke tøj, som en karakter bærer), gemt ud fra 1 til 6 billeder du leverer (flere vinkler gør det mere trofast),
så du kan bruge det igen i Multi-Ref Video uden at beskrive det igen i hvert
shot. Der genereres intet billede, så det er gratis.
Uden billeder kan serveren også generere det: se Generér et subject uden billeder.
POST /subjects (tilladelse images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Felt | Type | Hvad det gør |
|---|---|---|
type | location, object, animal, style eller outfit | Hvad subjectet er |
name | ét ord, 1 til 40 bogstaver, cifre eller _ | Ordet der skrives efter @ i prompten |
description | Engelsk tekst, højst 300 tegn, valgfri | a glossy white futuristic tram with round windows |
images_b64 | 1 til 6 billeder i base64 | JPEG, PNG eller WebP, mindst 512 px på den lange side, højst 12 MB pr. styk (28 MB for hele kroppen: udover det tilføjes de næste ét ad gangen) |
Svaret, 201, er subjectet: subject_id, type, name, description, origin, dets images
(hver med en file_url), complete og expires_at.
- Tilføj et billede:
POST /subjects/{id}/imagesmedimage_b64(højst 6). - Liste:
GET /subjects(?type=locationfor at filtrere) returnerer dine subjects, inkl. dem fra appens Library (originapp) og grænsenmax. Et app-subject hvis billeder ikke alle er synkroniseret endnu, harcomplete: false: det optræder med de billeder der allerede er der. - Gratis elementer: Tendre.AI giver færdige elementer med et fast id (for eksempel
officiel-red-beetle, et objekt). Hvert af dem tilføjes én gang til din liste, første gang du læser den (GET /subjects, MCPtendre_subject_list), og tæller ikke med i grænsenmax. Derefter er det et subject som de andre: brugbart i Multi-Ref (subject_id), redigerbart, slettebart; når det er slettet, kommer det aldrig tilbage. - Læs:
GET /subjects/{id}; ét billede:GET /subjects/{id}/images/{n}/file. - Rediger:
PUT /subjects/{id}medtype,name,descriptionog/ellerimages_b64(den fulde liste, som erstatter billederne). - Slet:
DELETE /subjects/{id}, her og i appen.
En stil giver et klip dets udtryk: dens description angiver teknikken, på engelsk (loose watercolor painting on textured paper), ikke hvad billederne viser. Et outfit er et stykke tøj, som en karakter bærer. Stilarter og outfits virker kun i Multi-Ref Video, i Ultra.
For at besætte et subject i et klip, se Multi-Ref Video; i et billede, se Create an image.
Generér et subject uden billeder
Intet billede ved hånden? POST /subjects/generate (tilladelse images) laver subjectet, som vinduet "Generate" under Elements i appen gør: et startbillede ud fra din beskrivelse (eller importeret), derefter visninger, der tager udgangspunkt i det (andre vinkler, et nærbillede, om natten...), hver retoucheret fra startbilledet for at bevare den samme form. Resultatet er et almindeligt subject: det virker i Multi-Ref Video og i Create an image, og det vises i appens bibliotek.
| Felt | Type | Hvad det gør |
|---|---|---|
type | object, location, animal, style eller outfit | Hvad subjectet er (en bevægelse genereres ikke) |
name | ét ord, 1 til 40 bogstaver, cifre eller _ | Ordet efter @ i promptet |
description | tekst på engelsk, højst 300 tegn | Elementet alene: form, materialer, farver, detaljer, uden baggrund og uden karakter (a glossy white futuristic tram with round windows). Påkrævet, undtagen med prompt eller start_image_b64 |
prompt | tekst på engelsk, højst 2.000 tegn, valgfri | Hele teksten til startbilledet, i stedet for den automatiske tekst fra description |
start_image_b64 | billede i base64, valgfrit | Et importeret startbillede (mindst 512 px), bevaret som det er og gratis |
views | liste med nøgler, valgfri | De visninger, du vil have, i rækkefølge (tabellen nedenfor) |
count | 1 til 6, valgfri | I stedet for views: antallet af billeder i alt, start medregnet (de første visninger i tabellen) |
seed | heltal, valgfri | Seed for startbilledet |
quote_only | true | Returnerer kun prisen, intet oprettes |
Visninger pr. type (faste nøgler), i typens outputformat:
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (nærbillede) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (nærbillede) |
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ærbillede) |
Pris: hvert renderet billede (starten og hver visning) koster prisen for ét billede (1 kredit); en importeret start er gratis, og et mislykket billede trækkes ikke. Højst 6 billeder pr. subject, start medregnet. Svaret, 202, er subjectet med cost_estimate og 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ølg det med GET /subjects/{id}, indtil generation.status ikke længere er pending (ready, partial eller failed); n er billedets nummer i images. Billederne laves ét ad gangen: starten, derefter visningerne i rækkefølge. En fejl stopper serien: de næste visninger bliver failed, uden træk.
- Tilføj visninger:
POST /subjects/{id}/viewsmedviews(nøgler, der ikke er lavet endnu). Med én visning erstatterinstructions(engelsk, højst 1.000 tegn) dens instruks: sig, hvad visningen skal vise. - Lav en visning om:
POST /subjects/{id}/views/{key}/redo, medinstructionsefter behov. Visningen tager igen udgangspunkt i startbilledet og erstatter den forrige (sammen). - Lav starten om:
POST /subjects/{id}/views/start/redo, kun så længe ingen visning tager udgangspunkt i den (ellersviews_exist); en importeret start kan ikke laves om. Visninger, der blev stoppet af en mislykket start, kører igen efter den. quote_only: truegiver prisen på alle tre ruter. Én serie ad gangen pr. subject (subject_busy).
Fra start til slut, et objekt med to visninger:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Svaret, 202, giver subject_id med generation.status pending. Spørg GET /subjects/{id} med få sekunders mellemrum, indtil det er ready, og besæt derefter @Tram med dette subject_id. Tre billeder (starten og to visninger), altså tre gange prisen for ét billede.
Opbevaring
Karaktervinklerne og subject-billederne er krypterede (én nøgle pr. fil) og knyttet til din
licens. Subject-billeder gemmes som du sendte dem og deles med appens Library. Grænser med Pro-licensen:
50 karakterer inkl. appens og 50 subjects (lokationer, objekter, dyr, stilarter og outfits tilsammen) talt separat (10 med en personlig
licens i appen). En karakter eller et subject der ikke har været brugt i et år, slettes
(expires_at): enhver Multi-Ref-render, ethvert Face swap og enhver læsning af en vinkel eller et
billede skubber datoen frem. Det foto du sender for at oprette en karakter, gemmes som vinklen for dens
rolle, krypteret ligesom de genererede vinkler. Du kan slette dem alle til enhver tid.
Via en agent (MCP)
Med MCP-serveren spørger du blot: "lav en karakter ud fra dette foto". Agenten
bruger tendre_character_create (fotoet kommer via et upload-link, en fil vedhæftet i ChatGPT,
et billede renderet i samtalen eller en offentlig adresse), viser dig de syv vinkler og laver en
mislykket om igen med tendre_character_redo_view med en instruction når vinklen skal guides, eller
erstatter den med dit eget billede via tendre_character_set_view. tendre_character_get,
tendre_character_list og tendre_character_delete dækker resten, og tendre_quote giver prisen
på forhånd.
For en lokation, et objekt eller et dyr giver du agenten dine billeder og fortæller hvad det er: den
bruger tendre_subject_create, derefter tendre_subject_list, tendre_subject_get og
tendre_subject_delete. Uden billeder bruger den tendre_subject_generate, derefter tendre_subject_add_views og tendre_subject_redo_view til at tilføje eller lave en visning om.
Besæt derefter karakteren: se Multi-Ref Video.