Pro API: lag karakterer for Multi-Ref Video
En karakter er et ark med sju visninger av samme person (eller skapning), laget fra ett foto
og lagret under en character_id. Det er det Multi-Ref Video bruker for å
gjenkjenne noen i en klipp: visningene bærer likheten, uten trening.
Face swap bruker dem også, for å sette karakteren i stedet for personen i
din egen video.
Karakterene du laget i appen er allerede der: samme lisens, samme liste (se Karakterer fra appen). Steder, objekter og dyr lagres på samme måte, fra bilder du leverer, og spiller i de samme klippene (se Steder, objekter og dyr).
De sju visningene
| Rolle | Visning |
|---|---|
| 1 | Byste, front, nøytralt uttrykk |
| 4 | Helfigur, front |
| 5 | Helfigur, bakfra |
| 6 | Helfigur i profil, karakteren ser mot venstre i bildet |
| 7 | Nærbilde av ansiktet, forfra |
| 8 | Nærbilde av antrekket, fra brystet til knærne |
| 9 | Nærbilde av føttene, med sko eller barbeint avhengig av antrekket |
Hver visning genereres for seg selv: ingen er laget ved å speilvende en annen. Rollene 2 og 3 (byster i trekvartprofil) lages ikke lenger siden 21. oktober 2026: en karakter laget før beholder dem, og de kan fortsatt leses (filen til en visning, listen views), men ikke gjøres om (400 invalid_role).
Lag en karakter
POST /characters (tillatelse images). Arbeidet er asynkront.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Felt | Type | Hva det gjør |
|---|---|---|
name | streng, 1 til 40 tegn | Karakterens fornavn |
kind | streng | woman, man, eller en skapning beskrevet på engelsk (baby dragon). Det setter pronomenene i instruksjonene, aldri "they". |
image_b64 | base64 | Fotoet: skarpt, kun én person, minst 1024 px på langsiden, maks 12 MB, JPEG, PNG eller WebP |
photo_role | bust (standard) eller full_body | Fotoet er en byste (det blir visning 1) eller et helfigursbilde (visning 4) |
outfit | Engelsk tekst, valgfritt | Med et bystefoto: antrekket i helfigursvisningen (a red leather jacket and black jeans), altså underkroppen som bysten ikke viser. Med et helfigursfoto gjelder fotoet, og antrekket tas ikke på |
Svaret, 202, er karakteren med status pending og cost_estimate. Fotoet blir visningen for sin rolle, beholdes som det er (kles aldri om), og serveren genererer de andre seks på 2 til 5 minutter, på samme måte som appen: kroppen (rygg, profil, antrekk, føtter) starter fra helfigursvisningen, nærbildet av ansiktet fra bysten. Et bystefoto forlenges til helfigursvisningen (i outfit hvis det er oppgitt); et helfigursfoto gir bysten ved beskjæring.
Pris: ett kreditt per generert visning, altså 6 kreditter, med eller uten outfit. En visning som mislykkes belastes ikke. POST /characters/quote gir prisen på forhånd.
Send den samme opprettelsen på nytt. Hvis tilkoblingen brytes før svaret, eller en agents venting avbrytes, fortsetter serveren å lage karakteren. Send den samme forespørselen på nytt (samme foto, name, kind, photo_role og outfit): den returnerer karakteren som allerede er opprettet, med existing: true og en cost_estimate på 0, og ingenting belastes to ganger. Den oppretter bare en ny hvis alle genererte visninger av den første mislyktes; noen få mislykkede visninger lages på nytt én etter én (redo). Hvis to identiske forespørsler kommer i samme øyeblikk, får den andre 409 character_busy: send den på nytt noen sekunder senere.
Følg med, sjekk, gjør om
GET /characters/{id} gir tilstanden:
status | Betydning |
|---|---|
pending | Visningene lages |
ready | De sju visningene er klare |
partial | Noen visninger mangler eller mislyktes |
failed, empty | Ingen brukbar visning |
{
"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"
}- Sjekk visningene før første render.
GET /characters/{id}/views/{role}/filereturnerer bildet. Helfigursvisningene (4, 5 og 6) genereres i 2K, 1024 x 2048, og bysten og nærbildene i 832 x 1216 (1216 x 832 for føttene), som PNG, eller som JPEG over 2,9 MB. Visningen fra fotoet ditt beholder størrelsen sin (maks 2048 px). Visninger som allerede er laget, beholder størrelsen sin; en visning som gjøres om, kommer i disse størrelsene. En mislykket visning, eller en profil som ser feil vei, ødelegger likheten i alle videoer. - Gjør om en visning:
POST /characters/{id}/views/{role}/redo, 1 kreditt: en ny generering fra utgangspunktet sitt (helfigursvisningen eller bysten). Visningen som kom fra originalfotoet kan ikke gjøres om (photo_view), med eller utenoutfit. Et sheet som er importert i appen som ett enkelt bilde (et helt sheet, beholdt som det er) lages ikke på nytt visning for visning (409 single_image_sheet). - Veilede en gjentatt visning: legg til
instruction(200 tegn, engelsk) i redo-kroppen, for en karakter opprettet via API, eller en character sheet lagt til via API (ellers409 app_character). Den spesifiserer hva visningen må vise av karakteren, som siden av en protese eller tilstedeværelsen av et detalj, aldri en annen endring: antrekk, hår, positur, omgivelser og uttrykk endres andre steder. Skriv det i imperativ (motoren ignorerer en beskrevet tilstand):"Put the robotic arm on her left side only, remove any second robotic arm."På bakvisningen (5), navngi siden på begge måter:"her left arm, which appears on the left side of the image when seen from behind". Samme pris, 1 kreditt. - Last opp ditt eget bilde for en visning:
PUT /characters/{id}/views/{role}medimage_b64(de samme reglene som for opprettingsfotoet: minst 1024 px på langsiden, 12 MB, JPEG, PNG eller WebP), for en karakter opprettet via API, eller en character sheet lagt til via API (?sheet=). Gratis, ingenting genereres. Bildet beholdes som det er og teller som et ekte foto: visningene som gjøres om etterpå, starter fra det etter regelen ved opprettingen (ryggen, profilen og nærbildene av antrekket og føttene fra helfigursvisningen, nærbildet av ansiktet fra bysten). - Liste:
GET /charactersreturnerer dine karakterer, inkludert appens, og grensenmax. - Slett:
DELETE /characters/{id}sletter karakteren og dens visninger.
I appen (versjon 0.8.6 og senere): en karakter opprettet via API eller MCP vises i appens
My characters-skjerm, på samme lisens, med navn og visninger, akkurat som de som er opprettet i
appen. En visning som gjøres om i appen erstatter nettvisningen, den som Multi-Ref Video leser.
Sletter du den i appen, slettes den her også, for godt (appen ber om bekreftelse først): en
pipeline som beholder en character_id bør forvente en 404 unknown_character når karakteren er
slettet i appen.
Karakterer fra appen
En karakter opprettet i appens My characters-skjerm vises i GET /characters med origin
app, og spiller i Multi-Ref Video som alle andre. I appen kan en karakter ha flere
character sheets (antrekk, stemninger): sheet_id sier hvilken som serveres (den nyeste som standard),
sheets lister dem opp, og ?sheet=<id> ber om en annen ved lesing, på en visnings fil og på en
gjentatt visning. I en Multi-Ref-klipp velger characters[].sheet_id character sheet. Den har name og kind fra profilen sin i appen så snart appen har sendt dem (app 0.9.1 og nyere; før det er begge null). For å gjøre om
en visning av en app-karakter der kind fortsatt er null, oppgi dens kind i kroppen.
Stemme. has_voice sier om stemmen i karakterens profil er på nett: appen sender den med karakteren, og Face swap og Multi-Ref Video bruker den som standard.
Legg til et antrekk på en karakter
POST /characters/{id}/sheets gir en eksisterende karakter en ny character sheet (et antrekk, en look), uansett om den ble opprettet via API eller i appen, appens forhåndsvalg medregnet. Karakteren beholder sine andre character sheets. Svaret, 202, er karakteren med den nye character sheet: dens sheet_id (den begynner 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 | Hva det gjør |
|---|---|---|
name | streng, 1 til 40 tegn | Navnet på character sheet |
outfit | engelsk tekst, maks 700 tegn | Antrekket som skal på; påkrevd uten views |
views | objekt, rolle "1" eller "4" til "9": et bilde i base64 | Visninger som er ferdige, med de samme reglene som når du laster opp en visning |
generate | true (standard) eller false | Generer rollene som mangler, eller ingen |
from_sheet_id | streng, valgfritt | Uten views: character sheet å ta utgangspunkt i |
kind | streng | Bare for en karakter opprettet i appen der kind fortsatt er null i GET /characters, som ved opprettingen |
- Med
views: visningene du sender lagres som de er, gratis. Rollene som mangler genereres, 1 kreditt per visning, etter regelen ved opprettingen, fra helfigursvisningen og bysten du sender; uten noen av dem som utenviews.generate: falsegenererer ingen. - Uten
views: antrekket settes på karakterens helfigursvisning (på bysten hvis den ikke har en;from_sheet_idtar utgangspunkt i en annen character sheet). Resultatet blir helfigursvisningen til den nye character sheeten, og de seks andre visningene starter fra det: 7 genererte visninger, 7 kreditter.cost_estimateoppgir prisen. Hvis kilde-sheetet (from_sheet_id, eller standardsheetet) er et slikt enkeltbilde, send visning 4 (helfigur) eller 1 (byste) iviews(409 single_image_sheet). - Bruk character sheet som de andre, med
?sheet=<sheet_id>: påGET /characters/{id}, på filen til en visning, påredo(instructionmedregnet) og påPUTav en visning. I et Multi-Ref-klipp velgercharacters[].sheet_idden. - For en karakter fra appen, send med
sheet_id: som standard brukes fortsatt den sist endrede character sheet, altså den du nettopp la til. - Slett en tillagt character sheet:
DELETE /characters/{id}/sheets/{sheet_id}sletter bare visningene dens. En character sheet laget i appen slettes ikke slik (404 unknown_sheet). - I appen: appen med samme lisens henter den nye character sheet inn i karakterens profil.
- Feil:
400 outfit_or_views_required(verken antrekk eller visninger),400 views_required(generate: falseuten visning),409 source_sheet_empty(verken helfigursvisning eller byste å starte fra),409 character_busy.
Steder, objekter, dyr, stiler og antrekk
Et subjekt er et sted (location), et objekt (object: et kjøretøy, en rekvisitt, et møbel...),
et dyr (animal), en stil (style: stemningsbilder som videoen tar uttrykket fra) eller et antrekk (outfit: et plagg som en karakter har på seg), lagret fra 1 til 6 bilder du leverer (flere vinkler gjør det mer trofast),
slik at du kan bruke det igjen i Multi-Ref Video uten å beskrive det på
nytt i hvert bilde. Ingen bilder genereres, så det er gratis.
Uten bilder kan serveren også generere det: se Generere et subjekt uten bilder.
POST /subjects (tillatelse images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Felt | Type | Hva det gjør |
|---|---|---|
type | location, object, animal, style eller outfit | Hva subjektet er |
name | ett ord, 1 til 40 bokstaver, sifre eller _ | Ordet som skrives etter @ i prompten |
description | Engelsk tekst, maks 300 tegn, valgfritt | a glossy white futuristic tram with round windows |
images_b64 | 1 til 6 bilder i base64 | JPEG, PNG eller WebP, minst 512 px på langsiden, maks 12 MB hver (28 MB for hele kroppen: utover det legger du til de neste ett om gangen) |
Svaret, 201, er subjektet: subject_id, type, name, description, origin, dets images
(hver med en file_url), complete og expires_at.
- Legg til et bilde:
POST /subjects/{id}/imagesmedimage_b64(maks 6). - Liste:
GET /subjects(?type=locationfor å filtrere) returnerer dine subjekter, inkludert de fra appens Library (originapp), og grensenmax. Et app-subjekt hvis bilder ikke alle er synkronisert ennå harcomplete: false: det spiller med bildene som allerede er der. - Gitte elementer: Tendre.AI gir ferdige elementer med en fast id (for eksempel
officiel-red-beetle, et objekt). Hvert av dem legges til én gang i listen din første gang du leser den (GET /subjects, MCPtendre_subject_list) og teller ikke med i grensenmax. Deretter er det et subjekt som de andre: brukbart i Multi-Ref (subject_id), redigerbart, slettbart; når det er slettet, kommer det aldri tilbake. - Les:
GET /subjects/{id}; ett bilde:GET /subjects/{id}/images/{n}/file. - Endre:
PUT /subjects/{id}medtype,name,descriptionog/ellerimages_b64(den fulle listen, som erstatter bildene). - Slett:
DELETE /subjects/{id}, her og i appen.
En stil gir et klipp uttrykket sitt: description angir teknikken, på engelsk (loose watercolor painting on textured paper), ikke hva bildene viser. Et antrekk er et plagg som en karakter har på seg. Stiler og antrekk virker bare i Multi-Ref Video, i Ultra.
For å sette et subjekt i et klipp, se Multi-Ref Video; i et bilde, se Create an image.
Generere et subjekt uten bilder
Ingen bilde for hånden? POST /subjects/generate (tillatelse images) lager subjektet slik vinduet "Generate" under Elements i appen gjør: et startbilde ut fra beskrivelsen din (eller importert), deretter visninger som går ut fra det (andre vinkler, et nærbilde, om natten...), hver retusjert fra startbildet for å beholde samme form. Resultatet er et vanlig subjekt: det fungerer i Multi-Ref Video og i Create an image, og det vises i appens bibliotek.
| Felt | Type | Hva det gjør |
|---|---|---|
type | object, location, animal, style eller outfit | Hva subjektet er (en bevegelse genereres ikke) |
name | ett ord, 1 til 40 bokstaver, sifre eller _ | Ordet etter @ i prompten |
description | tekst på engelsk, høyst 300 tegn | Elementet alene: form, materialer, farger, detaljer, uten bakgrunn og uten karakter (a glossy white futuristic tram with round windows). Påkrevd, unntatt med prompt eller start_image_b64 |
prompt | tekst på engelsk, høyst 2 000 tegn, valgfri | Hele teksten til startbildet, i stedet for den automatiske teksten fra description |
start_image_b64 | bilde i base64, valgfritt | Et importert startbilde (minst 512 px), beholdt som det er og gratis |
views | liste med nøkler, valgfri | Visningene du vil ha, i rekkefølge (tabellen nedenfor) |
count | 1 til 6, valgfri | I stedet for views: antall bilder totalt, start inkludert (de første visningene i tabellen) |
seed | heltall, valgfri | Seed for startbildet |
quote_only | true | Returnerer bare prisen, ingenting opprettes |
Visninger per type (faste nøkler), i typens utdataformat:
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (nærbilde) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (nærbilde) |
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ærbilde) |
Pris: hvert rendret bilde (starten og hver visning) koster prisen for ett bilde (1 kreditt); en importert start er gratis, og et mislykket bilde belastes ikke. Høyst 6 bilder per subjekt, start inkludert. Svaret, 202, er subjektet 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} til generation.status ikke lenger er pending (ready, partial eller failed); n er bildets nummer i images. Bildene lages ett om gangen: starten, deretter visningene i rekkefølge. En feil stopper serien: de neste visningene blir failed, uten belastning.
- Legg til visninger:
POST /subjects/{id}/viewsmedviews(nøkler som ikke er laget ennå). Med én visning erstatterinstructions(engelsk, høyst 1 000 tegn) instruksen dens: si hva visningen skal vise. - Lag en visning på nytt:
POST /subjects/{id}/views/{key}/redo, medinstructionsved behov. Visningen går igjen ut fra startbildet og erstatter den forrige (sammen). - Lag starten på nytt:
POST /subjects/{id}/views/start/redo, bare så lenge ingen visning går ut fra den (ellersviews_exist); en importert start kan ikke lages på nytt. Visninger som ble stoppet av en mislykket start, kjøres igjen etter den. quote_only: truegir prisen på alle tre rutene. Én serie om gangen per subjekt (subject_busy).
Fra start til slutt, 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, gir subject_id med generation.status pending. Spør GET /subjects/{id} med noen sekunders mellomrom til det er ready, og bruk deretter @Tram med denne subject_id. Tre bilder (starten og to visninger), altså tre ganger prisen for ett bilde.
Lagring
Karaktervisningene og subjektbildene er krypterte (én nøkkel per fil) og knyttet til lisensen din.
Subjektbilder lagres slik du sendte dem, og deles med appens Library. Grenser med Pro-lisens:
50 karakterer, inkludert appens, og 50 subjekter (steder, objekter, dyr, stiler og antrekk til sammen), talt separat (10 med en
personlig lisens, i appen). En karakter eller et subjekt som ikke er brukt på ett år slettes
(expires_at): hvert Multi-Ref-render, hver Face swap og hver lesing av en visning eller et bilde
skyver datoen frem. Fotoet du sender for å opprette en karakter lagres som visningen for sin rolle,
kryptert, akkurat som de genererte visningene. Du kan slette alle av dem når som helst.
Via en agent (MCP)
Med MCP-serveren trenger du bare å spørre: "lag en karakter fra dette fotoet". Agenten
bruker tendre_character_create (fotoet kommer via en opplastingslenke, en fil vedlagt i ChatGPT,
et bilde rendret i samtalen eller en offentlig adresse), viser deg de sju visningene, og gjør om en
mislykket en med tendre_character_redo_view, med en instruction når visningen trenger veiledning,
eller erstatter den med ditt eget bilde via tendre_character_set_view. tendre_character_get,
tendre_character_list og tendre_character_delete dekker resten, og tendre_quote gir prisen på
forhånd.
For et sted, et objekt eller et dyr, gi agenten bildene dine og si hva det er: den bruker
tendre_subject_create, deretter tendre_subject_list, tendre_subject_get og tendre_subject_delete. Uten bilder bruker den tendre_subject_generate, deretter tendre_subject_add_views og tendre_subject_redo_view for å legge til eller lage en visning på nytt.
Sett deretter karakteren i en klipp: se Multi-Ref Video.