Pro API: luo hahmoja Multi-Ref Video -klippeihin
Hahmo on seitsemän näkymän kokoelma samasta henkilöstä (tai olennosta), luotu yhdestä valokuvasta
ja tallennettu character_id-tunnuksen alle. Sitä Multi-Ref Video käyttää
tunnistamaan henkilön klipissä: näkymät kantavat samankaltaisuuden ilman erillistä koulutusta.
Face swap käyttää niitä myös, asettaakseen hahmon oman videosi henkilön tilalle.
Hahmot, jotka olet luonut sovelluksessa, ovat jo siellä: sama lisenssi, sama lista (katso Sovelluksen hahmot). Sijainnit, esineet ja eläimet tallennetaan samalla tavalla omista kuvistasi ja ne toimivat samoissa klipeissä (katso Sijainnit, esineet ja eläimet).
Seitsemän näkymää
| Rooli | Näkymä |
|---|---|
| 1 | Rintakuva, edestä, neutraali ilme |
| 4 | Koko keho, edestä |
| 5 | Koko keho, takaa |
| 6 | Koko keho profiilista, hahmo katsoo kuvan vasemmalle puolelle |
| 7 | Kasvojen lähikuva, edestä |
| 8 | Asun lähikuva, rinnasta polviin |
| 9 | Jalkojen lähikuva, kengissä tai paljain jaloin asun mukaan |
Jokainen näkymä luodaan erikseen: yhtään niistä ei saada kääntämällä toista peilikuvaksi. Rooleja 2 ja 3 (puoliprofiilin rintakuvat) ei enää luoda 21. lokakuuta 2026 alkaen: aiemmin luodulla hahmolla ne säilyvät, ja niitä voi yhä lukea (näkymän tiedosto, views-lista), mutta ei enää tehdä uudelleen (400 invalid_role).
Luo hahmo
POST /characters (oikeus images). Työ on asynkroninen.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Kenttä | Tyyppi | Mitä se tekee |
|---|---|---|
name | merkkijono, 1-40 merkkiä | Hahmon etunimi |
kind | merkkijono | woman, man tai englanniksi kuvattu olento (baby dragon). Se määrittää ohjeiden pronominit, ei koskaan "they". |
image_b64 | base64 | Valokuva: terävä, vain yksi henkilö, vähintään 1024 px pitkällä sivulla, enintään 12 MB, JPEG, PNG tai WebP |
photo_role | bust (oletus) tai full_body | Valokuva on rintakuva (siitä tulee näkymä 1) tai koko kehon kuva (näkymä 4) |
outfit | englanniksi, valinnainen | Rintakuvana otetun valokuvan kanssa koko kehon näkymän asu (a red leather jacket and black jeans): alavartalo, jota rintakuva ei näytä. Koko kehon valokuvalla valokuva ratkaisee, eikä asua pueta |
Vastaus, 202, on hahmo, jonka status on pending ja sisältää cost_estimate. Valokuvasta tulee sen roolin näkymä sellaisenaan (sitä ei koskaan pueta uudelleen), ja palvelin luo muut kuusi 2-5 minuutissa samalla tavalla kuin sovellus: keho (selkä, profiili, asu, jalat) lähtee koko kehon näkymästä, kasvojen lähikuva rintakuvasta. Rintakuva jatketaan koko kehon näkymäksi (outfit-asussa, jos se on annettu); koko kehon valokuvasta saadaan rintakuva rajaamalla.
Hinta: yksi krediitti luotua näkymää kohti, eli 6 krediittiä, outfit-kentän kanssa tai ilman. Epäonnistuneesta näkymästä ei veloiteta. POST /characters/quote antaa hinnan etukäteen.
Saman luonnin lähettäminen uudelleen. Jos yhteys katkeaa ennen vastausta tai agentin odotus keskeytyy, palvelin jatkaa hahmon tekemistä. Lähetä sama pyyntö uudelleen (sama kuva, name, kind, photo_role ja outfit): se palauttaa jo luodun hahmon, jossa on existing: true ja cost_estimate 0, eikä mitään veloiteta kahdesti. Se luo uuden hahmon vain, jos kaikki ensimmäisen generoidut näkymät epäonnistuivat; muutama epäonnistunut näkymä tehdään uudelleen yksi kerrallaan (redo). Jos kaksi samanlaista pyyntöä saapuu samalla hetkellä, toinen saa vastauksen 409 character_busy: lähetä se uudelleen muutaman sekunnin kuluttua.
Seuraa, tarkista, tee uudelleen
GET /characters/{id} antaa sen tilan:
status | Merkitys |
|---|---|
pending | Näkymiä luodaan parhaillaan |
ready | Kaikki seitsemän näkymää ovat valmiina |
partial | Joitakin näkymiä puuttuu tai ne epäonnistuivat |
failed, empty | Ei käyttökelpoisia näkymiä |
{
"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"
}- Tarkista näkymät ennen ensimmäistä renderöintiä.
GET /characters/{id}/views/{role}/filepalauttaa kuvan. Koko kehon näkymät (4, 5 ja 6) luodaan 2K-kokoisina, 1024 x 2048, ja rintakuva ja lähikuvat kokoon 832 x 1216 (jalat 1216 x 832), PNG-muodossa, tai JPEG-muodossa, jos tiedosto on yli 2,9 Mt. Valokuvastasi tehty näkymä säilyttää kokonsa (enintään 2048 px). Jo tehdyt näkymät säilyttävät kokonsa; uudelleen tehty näkymä tulee näissä koissa. Epäonnistunut näkymä tai väärään suuntaan katsova profiili pilaa samankaltaisuuden jokaisessa videossa. - Tee näkymä uudelleen:
POST /characters/{id}/views/{role}/redo, 1 krediitti: uusi luonti sen lähtökohdasta (koko kehon näkymästä tai rintakuvasta). Alkuperäisestä valokuvasta peräisin olevaa näkymää ei voi tehdä uudelleen (photo_view),outfit-kentän kanssa tai ilman. Sovellukseen yhtenä kuvana tuotua sheetiä (koko sheet sellaisenaan) ei tehdä uudelleen näkymä kerrallaan (409 single_image_sheet). - Ohjaa uudelleen tehtyä näkymää: lisää
instruction(200 merkkiä, englanniksi) redo-runkoon API:n kautta luodulle hahmolle tai API:n kautta lisätylle character sheetille (muuten409 app_character). Se täsmentää mitä näkymän täytyy näyttää hahmosta, kuten proteesin puoli tai yksityiskohdan läsnäolo, ei koskaan muuta muutosta: vaate, hiukset, asento, ympäristö ja ilme muutetaan muualla. Kirjoita se imperatiivissa (moottori jättää huomiotta kuvaillun tilan):"Put the robotic arm on her left side only, remove any second robotic arm."Takaa kuvatussa näkymässä (5) nimeä puoli molemmilla tavoilla:"her left arm, which appears on the left side of the image when seen from behind". Sama hinta, 1 krediitti. - Lataa oma kuvasi näkymäksi:
PUT /characters/{id}/views/{role}yhdessäimage_b64:n kanssa (samat säännöt kuin luomisvalokuvalla: vähintään 1024 px pitkällä sivulla, 12 MB, JPEG, PNG tai WebP), API:n kautta luodulle hahmolle tai API:n kautta lisätylle character sheetille (?sheet=). Ilmainen, mitään ei luoda. Kuva säilytetään sellaisenaan ja lasketaan oikeaksi valokuvaksi: myöhemmin uudelleen tehtävät näkymät lähtevät siitä luomisen säännön mukaan (selkä, profiili sekä asun ja jalkojen lähikuvat koko kehon näkymästä, kasvojen lähikuva rintakuvasta). - Lista:
GET /characterspalauttaa hahmosi, sovelluksen hahmot mukaan lukien, sekä enimmäismääränmax. - Poista:
DELETE /characters/{id}poistaa hahmon ja sen näkymät.
Sovelluksessa (versio 0.8.6 ja uudemmat): API:n tai MCP:n kautta luotu hahmo näkyy sovelluksen
My characters -näytöllä samalla lisenssillä, nimellään ja näkymineen, aivan kuten sovelluksessa
luodut hahmot. Sovelluksessa uudelleen tehty näkymä korvaa verkkonäkymän, jonka Multi-Ref Video lukee.
Sen poistaminen sovelluksessa poistaa sen myös täältä pysyvästi (sovellus pyytää vahvistuksen ensin):
putkilinjan, joka säilyttää character_id-tunnuksen, kannattaa varautua 404 unknown_character
-vastaukseen sen jälkeen, kun hahmo on poistettu sovelluksessa.
Sovelluksen hahmot
Sovelluksen My characters -näytöllä luotu hahmo näkyy GET /characters -vastauksessa origin-arvolla
app ja toimii Multi-Ref Video -klipeissä kuten mikä tahansa muukin hahmo. Sovelluksessa hahmolla voi olla
useita character sheetejä (asuja, mielialoja): sheet_id kertoo, mikä niistä tarjotaan (oletuksena
viimeisin), sheets listaa ne, ja ?sheet=<id> pyytää toisen lukemiseen, näkymän tiedostoon ja
uudelleen tehtyyn näkymään. Multi-Ref -klipissä characters[].sheet_id valitsee character sheetin.
Hahmolla on sovelluksen profiilin name ja kind heti, kun sovellus on lähettänyt ne (sovellus 0.9.1 ja uudemmat; sitä ennen molemmat ovat null). Tehdäksesi uudelleen näkymän sovelluksen hahmolle, jonka kind on yhä null, anna sen kind rungossa.
Ääni. has_voice kertoo, onko hahmon profiilin ääni verkossa: sovellus lähettää sen hahmon mukana, ja Face swap ja Multi-Ref Video käyttävät sitä oletuksena.
Lisää hahmolle asu
POST /characters/{id}/sheets antaa olemassa olevalle hahmolle uuden character sheetin (asun, tyylin), oli hahmo luotu API:n kautta tai sovelluksessa, sovelluksen valmiit hahmot mukaan lukien. Hahmo säilyttää muut character sheettinsä. Vastaus, 202, on hahmo uuden character sheetin kanssa: sen sheet_id (alkaa api-), sheet_name, sheet_outfit, sheet_origin: "api" ja cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Kenttä | Tyyppi | Mitä se tekee |
|---|---|---|
name | merkkijono, 1-40 merkkiä | Character sheetin nimi |
outfit | englanniksi, enintään 700 merkkiä | Puettava asu; pakollinen ilman views-kenttää |
views | objekti, rooli "1" tai "4"-"9": kuva base64-muodossa | Valmiit näkymät, samoin säännöin kuin näkymän latauksessa |
generate | true (oletus) tai false | Luodaanko puuttuvat roolit vai ei yhtään |
from_sheet_id | merkkijono, valinnainen | Ilman views-kenttää: character sheet, josta lähdetään |
kind | merkkijono | Vain sovelluksessa luodulle hahmolle, jonka kind on yhä null reitissä GET /characters, kuten luonnissa |
views-kentän kanssa: lähettämäsi näkymät tallennetaan sellaisinaan, ilmaiseksi. Puuttuvat roolit luodaan, 1 krediitti näkymältä, luomisen säännön mukaan lähettämästäsi koko kehon näkymästä ja rintakuvasta; jos kumpaakaan ei ole, kuten ilmanviews-kenttää.generate: falseei luo yhtään.- Ilman
views-kenttää: asu puetaan hahmon koko kehon näkymään (rintakuvaan, jos sellaista ei ole;from_sheet_idlähtee toisesta character sheetistä). Tuloksesta tulee uuden character sheetin koko kehon näkymä, ja kuusi muuta näkymää lähtevät siitä: 7 luotua näkymää, 7 krediittiä.cost_estimatekertoo hinnan. Jos lähdesheet (from_sheet_idtai oletus) on tällainen yksittäinen kuva, lähetä näkymä 4 (koko vartalo) tai 1 (rintakuva) kentässäviews(409 single_image_sheet). - Käytä character sheetiä kuten muitakin,
?sheet=<sheet_id>-parametrilla:GET /characters/{id}-kutsussa, näkymän tiedostossa,redo-kutsussa (instructionmukaan lukien) ja näkymänPUT-kutsussa. Multi-Ref-klipissä sen valitseecharacters[].sheet_id. - Sovelluksen hahmolle anna
sheet_id: oletuksena tarjotaan edelleen viimeksi muokattu character sheet, eli juuri lisäämäsi. - Lisätyn character sheetin poisto:
DELETE /characters/{id}/sheets/{sheet_id}poistaa vain sen näkymät. Sovelluksessa tehtyä character sheetiä ei voi poistaa näin (404 unknown_sheet). - Sovelluksessa: saman lisenssin sovellus tuo uuden character sheetin hahmon profiiliin.
- Virheet:
400 outfit_or_views_required(ei asua eikä näkymiä),400 views_required(generate: falseilman näkymää),409 source_sheet_empty(ei koko kehon näkymää eikä rintakuvaa lähtökohdaksi),409 character_busy.
Sijainnit, esineet, eläimet, tyylit ja asut
Kohde on sijainti (location), esine (object: ajoneuvo, rekvisiitta, huonekalu...), eläin
(animal), tyyli (style: tunnelmakuvia, joiden ilmeen video omaksuu) tai asu (outfit: hahmon käyttämä vaate), tallennettu 1-6 omasta kuvastasi (useat kulmat tekevät siitä uskollisemman), jotta
voit käyttää sitä uudelleen Multi-Ref Video -klipeissä kuvailematta sitä
uudelleen jokaisessa otoksessa. Mitään kuvaa ei luoda, joten se on ilmainen.
Ilman kuvia palvelin voi myös luoda sen: katso Kohteen luominen ilman kuvia.
POST /subjects (oikeus images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Kenttä | Tyyppi | Mitä se tekee |
|---|---|---|
type | location, object, animal, style tai outfit | Mitä kohde on |
name | yksi sana, 1-40 kirjainta, numeroa tai _ | Sana, joka kirjoitetaan @-merkin jälkeen promptissa |
description | englanniksi, enintään 300 merkkiä, valinnainen | a glossy white futuristic tram with round windows |
images_b64 | 1-6 kuvaa base64-muodossa | JPEG, PNG tai WebP, vähintään 512 px pitkällä sivulla, enintään 12 MB kukin (28 MB koko rungolle: sen jälkeen lisää loput yksitellen) |
Vastaus, 201, on kohde: subject_id, type, name, description, origin, sen images
(jokainen file_url-osoitteen kera), complete ja expires_at.
- Lisää kuva:
POST /subjects/{id}/imagesyhdessäimage_b64:n kanssa (enintään 6). - Lista:
GET /subjects(?type=locationsuodattamiseen) palauttaa kohteesi, mukaan lukien sovelluksen Library-kohdat (originapp), sekä enimmäismääränmax. Sovelluksen kohde, jonka kaikkia kuvia ei vielä ole synkronoitu, näyttääcomplete: false: se toimii jo olemassa olevilla kuvilla. - Lahjoitetut elementit: Tendre.AI tarjoaa valmiita elementtejä, joilla on kiinteä id (esimerkiksi
officiel-red-beetle, esine). Kukin lisätään listaasi kerran, kun luet sen ensimmäisen kerran (GET /subjects, MCPtendre_subject_list), eikä se lasketa rajaanmax. Sen jälkeen se on kohde kuten muutkin: käytettävissä Multi-Refissä (subject_id), muokattavissa ja poistettavissa; poistettuna se ei koskaan palaa. - Lue:
GET /subjects/{id}; yksi kuva:GET /subjects/{id}/images/{n}/file. - Muuta:
PUT /subjects/{id}yhdessätype-,name-,description- ja/taiimages_b64-kentän kanssa (täydellinen lista, joka korvaa kuvat). - Poista:
DELETE /subjects/{id}, täältä ja sovelluksesta.
Tyyli antaa klipille sen ilmeen: sen description kertoo tekniikan englanniksi (loose watercolor painting on textured paper), ei sitä, mitä sen kuvat esittävät. Asu on vaate, jota hahmo käyttää. Tyylit ja asut toimivat vain Multi-Ref Video -klipeissä Ultra-tilassa.
Sijoittaaksesi kohteen klippiin, katso Multi-Ref Video; kuvaan, katso Create an image.
Kohteen luominen ilman kuvia
Eikö kuvaa ole käsillä? POST /subjects/generate (oikeus images) tekee kohteen samoin kuin sovelluksen Elements-osion "Generate"-ikkuna: aloituskuvan kuvauksesi pohjalta (tai tuotuna) ja sitten siitä lähteviä näkymiä (muita kulmia, lähikuva, yöllä...), joista jokainen muokataan aloituskuvasta, jotta muoto pysyy samana. Tulos on tavallinen kohde: se toimii Multi-Ref Videossa ja Create an imagessa, ja se näkyy sovelluksen kirjastossa.
| Kenttä | Tyyppi | Mitä se tekee |
|---|---|---|
type | object, location, animal, style tai outfit | Mikä kohde on (liikettä ei luoda) |
name | yksi sana, 1-40 kirjainta, numeroa tai _ | Sana, joka kirjoitetaan @-merkin jälkeen promptissa |
description | englanninkielinen teksti, enintään 300 merkkiä | Pelkkä elementti: muoto, materiaalit, värit, yksityiskohdat, ilman taustaa ja ilman hahmoa (a glossy white futuristic tram with round windows). Pakollinen, paitsi jos annetaan prompt tai start_image_b64 |
prompt | englanninkielinen teksti, enintään 2 000 merkkiä, valinnainen | Aloituskuvan koko teksti description-kentästä tehdyn automaattisen tekstin sijaan |
start_image_b64 | kuva base64-muodossa, valinnainen | Tuotu aloituskuva (vähintään 512 px), säilytetään sellaisenaan ja ilmainen |
views | avainten luettelo, valinnainen | Haluamasi näkymät järjestyksessä (taulukko alla) |
count | 1-6, valinnainen | views-kentän sijaan: kuvien määrä yhteensä aloitus mukaan lukien (taulukon ensimmäiset näkymät) |
seed | kokonaisluku, valinnainen | Aloituskuvan seed |
quote_only | true | Palauttaa vain hinnan, mitään ei luoda |
Näkymät tyypeittäin (pysyvät avaimet), tyypin tulostusmuodossa:
type | Muoto | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (lähikuva) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (lähikuva) |
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 (lähikuva) |
Hinta: jokainen renderöity kuva (aloitus ja jokainen näkymä) maksaa yhden kuvan hinnan (1 krediitti); tuotu aloitus on ilmainen, eikä epäonnistunutta kuvaa veloiteta. Enintään 6 kuvaa kohdetta kohden, aloitus mukaan lukien. Vastaus, 202, on kohde, jossa on cost_estimate ja 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"]
}Seuraa sitä GET /subjects/{id} -kutsulla, kunnes generation.status ei enää ole pending (ready, partial tai failed); n on kuvan numero images-luettelossa. Kuvat tehdään yksi kerrallaan: aloitus ja sitten näkymät järjestyksessä. Virhe pysäyttää sarjan: seuraavat näkymät muuttuvat tilaan failed, ilman veloitusta.
- Lisää näkymiä:
POST /subjects/{id}/viewsjaviews(avaimet, joita ei ole vielä tehty). Yhden näkymän kanssainstructions(englanniksi, enintään 1 000 merkkiä) korvaa sen ohjeen: kerro, mitä näkymän pitää näyttää. - Uusi näkymä:
POST /subjects/{id}/views/{key}/redo, tarvittaessainstructions-kentän kanssa. Näkymä lähtee taas aloituskuvasta ja korvaa edellisen (saman). - Uusi aloitus:
POST /subjects/{id}/views/start/redo, vain niin kauan kuin siitä ei ole lähtenyt yhtään näkymää (muutenviews_exist); tuotua aloitusta ei voi uusia. Aloituksen virheen pysäyttämät näkymät tehdään uudelleen sen jälkeen. quote_only: trueantaa hinnan kaikilla kolmella reitillä. Yksi sarja kerrallaan kohdetta kohden (subject_busy).
Alusta loppuun, esine kahdella näkymällä:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Vastaus, 202, antaa subject_id:n ja generation.status-arvon pending. Kysy GET /subjects/{id} muutaman sekunnin välein, kunnes se on ready, ja käytä sitten @Tram-viittausta tällä subject_id:llä. Kolme kuvaa (aloitus ja kaksi näkymää), eli kolme kertaa yhden kuvan hinta.
Tallennus
Hahmon näkymät ja kohteen kuvat ovat salattuja (yksi avain tiedostoa kohti) ja sidottu lisenssiisi.
Kohteen kuvat säilytetään sellaisina kuin ne lähetit, ja ne jaetaan sovelluksen Libraryn kanssa.
Pro-lisenssin enimmäismäärät: 50 hahmoa, sovelluksen hahmot mukaan lukien, ja 50 kohdetta
(sijainnit, esineet, eläimet, tyylit ja asut yhteensä) laskettuna erikseen (10 henkilökohtaisella lisenssillä sovelluksessa).
Vuoden käyttämättömänä ollut hahmo tai kohde poistetaan (expires_at): jokainen Multi-Ref -renderöinti,
jokainen Face swap ja jokainen näkymän tai kuvan luku siirtää päivämäärää eteenpäin. Hahmon luomiseen
lähettämäsi valokuva säilytetään sen roolin näkymänä, salattuna, kuten luodut näkymätkin. Voit poistaa
minkä tahansa niistä milloin tahansa.
Agentin kautta (MCP)
MCP-palvelimen avulla pyydät vain: "tee hahmo tästä valokuvasta". Agentti käyttää
tendre_character_create-toimintoa (valokuva tulee latauslinkin, ChatGPT:hen liitetyn tiedoston,
keskustelussa renderöidyn kuvan tai julkisen osoitteen kautta), näyttää sinulle seitsemän näkymää ja
tekee epäonnistuneen uudelleen tendre_character_redo_view-toiminnolla, tarvittaessa instruction-kentän
kanssa, tai korvaa sen omalla kuvillasi tendre_character_set_view-toiminnon kautta. tendre_character_get,
tendre_character_list ja tendre_character_delete kattavat loput, ja tendre_quote antaa hinnan ensin.
Sijaintia, esinettä tai eläintä varten anna agentille kuvasi ja kerro mitä se on: se käyttää
tendre_subject_create-toimintoa, sitten tendre_subject_list-, tendre_subject_get- ja
tendre_subject_delete-toimintoja. Ilman kuvia se käyttää tendre_subject_generate-toimintoa ja sitten tendre_subject_add_views- ja tendre_subject_redo_view-toimintoja näkymän lisäämiseen tai uusimiseen.
Sijoita sitten hahmo klippiin: katso Multi-Ref Video.