Pro API: tworzenie postaci do Multi-Ref Wideo
Postać to sheet z siedmioma widokami tej samej osoby (lub stworzenia), stworzona z jednego zdjęcia
i przechowywana pod character_id. To właśnie tego używa Multi-Ref Wideo, aby
rozpoznać kogoś w klipie: jej widoki przenoszą podobieństwo bez żadnego trenowania.
Face swap też z nich korzysta, umieszczając postać w miejsce osoby na
Twoim własnym wideo.
Postacie utworzone w aplikacji są już dostępne: ta sama licencja, ta sama lista (zob. Postacie z aplikacji). Miejsca, obiekty i zwierzęta są przechowywane w ten sam sposób, na podstawie dostarczonych przez Ciebie zdjęć, i pojawiają się w tych samych klipach (zob. Miejsca, obiekty i zwierzęta).
Siedem widoków
| Rola | Widok |
|---|---|
| 1 | Popiersie z przodu, neutralny wyraz twarzy |
| 4 | Cała sylwetka z przodu |
| 5 | Cała sylwetka, tył |
| 6 | Cała sylwetka z profilu, postać patrzy w lewą stronę obrazu |
| 7 | Zbliżenie twarzy, z przodu |
| 8 | Zbliżenie stroju, od klatki piersiowej do kolan |
| 9 | Zbliżenie stóp, w butach lub bosych, zależnie od stroju |
Każdy widok jest generowany osobno: żaden nie powstaje przez odbicie lustrzane innego. Role 2 i 3 (popiersia w trzech czwartych) nie są tworzone od 21 października 2026: postać utworzona wcześniej je zachowuje, można je nadal odczytać (plik widoku, lista views), ale nie można ich ponowić (400 invalid_role).
Tworzenie postaci
POST /characters (uprawnienie images). Praca jest asynchroniczna.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Pole | Typ | Co robi |
|---|---|---|
name | string, 1 do 40 znaków | Imię postaci |
kind | string | woman, man lub stworzenie opisane po angielsku (baby dragon). Określa zaimki w instrukcjach, nigdy "they". |
image_b64 | base64 | Zdjęcie: wyraźne, tylko jedna osoba, co najmniej 1024 px po dłuższej stronie, maksymalnie 12 MB, JPEG, PNG lub WebP |
photo_role | bust (domyślnie) lub full_body | Zdjęcie to popiersie (staje się widokiem 1) lub ujęcie całej sylwetki (widok 4) |
outfit | tekst po angielsku, opcjonalnie | Przy zdjęciu popiersia strój widoku całej sylwetki (a red leather jacket and black jeans): dolna część ciała, której popiersie nie pokazuje. Przy zdjęciu całej sylwetki decyduje zdjęcie i strój nie jest nakładany |
Odpowiedź, 202, to postać z status pending i cost_estimate. Zdjęcie staje się widokiem swojej roli, zachowanym bez zmian (nigdy nieprzebieranym), a serwer generuje pozostałe sześć w ciągu 2 do 5 minut, tak samo jak aplikacja: ciało (tył, profil, strój, stopy) wychodzi od widoku całej sylwetki, zbliżenie twarzy od popiersia. Zdjęcie popiersia jest przedłużane do widoku całej sylwetki (w outfit, jeśli podano); zdjęcie całej sylwetki daje popiersie przez kadrowanie.
Cena: jeden kredyt za każdy wygenerowany widok, czyli 6 kredytów, z outfit lub bez. Za nieudany widok nie pobiera się opłat. POST /characters/quote podaje cenę z wyprzedzeniem.
Ponowne wysłanie tego samego tworzenia. Jeśli połączenie zostanie zerwane przed odpowiedzią albo oczekiwanie agenta zostanie przerwane, serwer nadal tworzy postać. Wyślij to samo żądanie ponownie (to samo zdjęcie, name, kind, photo_role i outfit): zwraca ono już utworzoną postać, z existing: true i cost_estimate równym 0, i nic nie jest naliczane dwa razy. Nowa postać powstaje tylko wtedy, gdy wszystkie wygenerowane widoki pierwszej się nie udały; pojedyncze nieudane widoki ponawia się jeden po drugim (redo). Jeśli dwa identyczne żądania dotrą w tej samej chwili, drugie otrzyma 409 character_busy: wyślij je ponownie kilka sekund później.
Śledzenie, sprawdzanie, ponawianie
GET /characters/{id} zwraca stan postaci:
status | Znaczenie |
|---|---|
pending | Widoki są w trakcie tworzenia |
ready | Wszystkie siedem widoków jest gotowych |
partial | Niektóre widoki są brakujące lub nieudane |
failed, empty | Brak użytecznego widoku |
{
"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"
}- Sprawdź widoki przed pierwszym renderem.
GET /characters/{id}/views/{role}/filezwraca obraz. Widoki całej sylwetki (4, 5 i 6) są generowane w 2K, 1024 x 2048, a popiersie i zbliżenia w 832 x 1216 (1216 x 832 dla stóp), w PNG lub w JPEG powyżej 2,9 MB. Widok z twojego zdjęcia zachowuje swój rozmiar (maksymalnie 2048 px). Widoki już utworzone zachowują swój rozmiar; ponowiony widok powstaje w tych rozmiarach. Nieudany widok lub profil, który patrzy w złą stronę, psuje podobieństwo w każdym wideo. - Ponów widok:
POST /characters/{id}/views/{role}/redo, 1 kredyt: nowe generowanie od jego punktu wyjścia (widoku całej sylwetki lub popiersia). Widoku, który pochodzi z oryginalnego zdjęcia, nie można ponawiać (photo_view), zoutfitlub bez. Sheet zaimportowany w aplikacji jako jeden obraz (cała plansza, zachowana bez zmian) nie jest odtwarzany widok po widoku (409 single_image_sheet). - Prowadź ponowiony widok: dodaj
instruction(200 znaków, po angielsku) do treści redo, dla postaci utworzonej przez API lub character sheet dodanej przez API (w przeciwnym razie409 app_character). Precyzuje ona, co widok musi pokazywać z postaci, np. stronę protezy lub obecność szczegółu, a nie żadną inną zmianę: strój, włosy, pozę, scenografię i wyraz twarzy zmienia się gdzie indziej. Pisz w trybie rozkazującym (silnik ignoruje opisany stan):"Put the robotic arm on her left side only, remove any second robotic arm.". W widoku od tyłu (5) nazwij stronę na dwa sposoby:"her left arm, which appears on the left side of the image when seen from behind". Ta sama cena, 1 kredyt. - Prześlij własny obraz dla widoku:
PUT /characters/{id}/views/{role}zimage_b64(te same zasady co przy zdjęciu do tworzenia: co najmniej 1024 px po dłuższej stronie, 12 MB, JPEG, PNG lub WebP), dla postaci utworzonej przez API lub character sheet dodanej przez API (?sheet=). Bezpłatnie, nic nie jest generowane. Obraz jest zachowywany bez zmian i traktowany jak prawdziwe zdjęcie: widoki ponawiane później wychodzą od niego według zasady tworzenia (tył, profil i zbliżenia stroju oraz stóp od widoku całej sylwetki, zbliżenie twarzy od popiersia). - Lista:
GET /characterszwraca Twoje postacie, w tym te z aplikacji, oraz limitmax. - Usuń:
DELETE /characters/{id}kasuje postać i jej widoki.
W aplikacji (wersja 0.8.6 i nowsze): postać utworzona przez API lub MCP pojawia się na ekranie
Moje postacie w aplikacji, w ramach tej samej licencji, z nazwą i widokami, tak samo jak te
utworzone w aplikacji. Widok ponowiony w aplikacji zastępuje widok online, ten który czyta Multi-Ref Wideo.
Usunięcie jej w aplikacji kasuje ją tutaj też, bezpowrotnie (aplikacja prosi najpierw o potwierdzenie):
pipeline przechowujący character_id powinien spodziewać się 404 unknown_character po usunięciu postaci
w aplikacji.
Postacie z aplikacji
Postać utworzona na ekranie Moje postacie w aplikacji pojawia się w GET /characters z origin
app i gra w Multi-Ref Wideo jak każda inna. W aplikacji postać może mieć kilka
sheetów (stroje, nastroje): sheet_id wskazuje, który jest serwowany (domyślnie najnowszy), sheets
je wyświetla, a ?sheet=<id> pozwala wybrać inny przy odczycie, przy pliku widoku i przy ponawianym widoku.
W klipie Multi-Ref, characters[].sheet_id wybiera sheet. Ma name i kind ze swojego profilu w aplikacji, gdy tylko aplikacja je wyśle (aplikacja 0.9.1 i nowsze; wcześniej oba mają wartość null). Aby ponowić widok postaci z aplikacji, której kind wciąż ma wartość null,
podaj jej kind w treści żądania.
Głos. has_voice mówi, czy głos z profilu postaci jest online: aplikacja wysyła go razem z postacią, a Face swap i Multi-Ref Wideo używają go domyślnie.
Dodawanie stroju do postaci
POST /characters/{id}/sheets daje istniejącej postaci nową character sheet (strój, wygląd), niezależnie od tego, czy postać utworzono przez API, czy w aplikacji, łącznie z presetami aplikacji. Postać zachowuje swoje pozostałe character sheets. Odpowiedź, 202, to postać z nową character sheet: jej sheet_id (zaczyna się od api-), sheet_name, sheet_outfit, sheet_origin: "api" i cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Pole | Typ | Co robi |
|---|---|---|
name | string, 1 do 40 znaków | Nazwa character sheet |
outfit | tekst po angielsku, maksymalnie 700 znaków | Strój do nałożenia; wymagany bez views |
views | obiekt, rola "1" lub "4" do "9": obraz w base64 | Gotowe widoki, z tymi samymi zasadami co przesyłanie widoku |
generate | true (domyślnie) lub false | Wygenerować brakujące role, czy żadnej |
from_sheet_id | string, opcjonalnie | Bez views: character sheet, od której zacząć |
kind | string | Tylko dla postaci utworzonej w aplikacji, której kind wciąż ma wartość null w GET /characters, jak przy tworzeniu |
- Z
views: wysłane widoki są zapisywane bez zmian, bezpłatnie. Brakujące role są generowane, 1 kredyt za widok, według zasady tworzenia, z wysłanego widoku całej sylwetki i popiersia; bez żadnego z nich tak jak bezviews.generate: falsenie generuje żadnego. - Bez
views: strój jest nakładany na widok całej sylwetki postaci (na jej popiersie, jeśli go nie ma;from_sheet_idzaczyna od innej character sheet). Wynik staje się widokiem całej sylwetki nowej character sheet, a sześć pozostałych widoków wychodzi od niego: 7 wygenerowanych widoków, 7 kredytów.cost_estimatepodaje cenę. Jeśli sheet źródłowy (from_sheet_idlub domyślny) jest takim pojedynczym obrazem, prześlij widok 4 (cała postać) lub 1 (popiersie) wviews(409 single_image_sheet). - Używaj character sheet jak pozostałych, z
?sheet=<sheet_id>: wGET /characters/{id}, przy pliku widoku, wredo(łącznie zinstruction) i wPUTwidoku. W klipie Multi-Ref wybiera jącharacters[].sheet_id. - Dla postaci z aplikacji podawaj
sheet_id: domyślnie nadal używana jest ostatnio zmieniona character sheet, czyli ta, którą właśnie dodano. - Usuwanie dodanej character sheet:
DELETE /characters/{id}/sheets/{sheet_id}usuwa tylko jej widoki. Character sheet utworzonej w aplikacji nie da się tak usunąć (404 unknown_sheet). - W aplikacji: aplikacja z tą samą licencją przenosi nową character sheet do profilu postaci.
- Błędy:
400 outfit_or_views_required(ani stroju, ani widoków),400 views_required(generate: falsebez widoku),409 source_sheet_empty(ani widoku całej sylwetki, ani popiersia, od którego można wyjść),409 character_busy.
Miejsca, obiekty, zwierzęta, style i stroje
Obiekt to miejsce (location), przedmiot (object: pojazd, rekwizyt, mebel...), zwierzę (animal), styl (style: obrazy nastroju, których wygląd przejmuje wideo) lub strój (outfit: ubranie noszone przez postać),
zapisane z 1 do 6 dostarczonych przez Ciebie zdjęć (kilka kątów czyni go bardziej wiernym), aby
można było go używać ponownie w Multi-Ref Wideo
bez opisywania go od nowa w każdym ujęciu. Żaden obraz nie jest generowany, więc jest to bezpłatne.
Bez zdjęć serwer może go też wygenerować: zob. Generowanie obiektu bez zdjęć.
POST /subjects (uprawnienie images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Pole | Typ | Co robi |
|---|---|---|
type | location, object, animal, style lub outfit | Czym jest obiekt |
name | jedno słowo, 1 do 40 liter, cyfr lub _ | Słowo pisane po @ w prompcie |
description | tekst po angielsku, maksymalnie 300 znaków, opcjonalnie | a glossy white futuristic tram with round windows |
images_b64 | 1 do 6 obrazów w base64 | JPEG, PNG lub WebP, co najmniej 512 px po dłuższej stronie, maksymalnie 12 MB każdy (28 MB dla całego body: jeśli przekraczasz, dodawaj kolejne po jednym) |
Odpowiedź, 201, to obiekt: subject_id, type, name, description, origin, jego images
(każdy z file_url), complete i expires_at.
- Dodaj obraz:
POST /subjects/{id}/imageszimage_b64(maksymalnie 6). - Lista:
GET /subjects(?type=locationdo filtrowania) zwraca Twoje obiekty, w tym te z Biblioteki aplikacji (originapp), oraz limitmax. Obiekt z aplikacji, którego obrazy nie są jeszcze wszystkie zsynchronizowane, macomplete: false: gra z obrazami już dostępnymi. - Elementy w prezencie: Tendre.AI udostępnia gotowe elementy ze stałym id (na przykład
officiel-red-beetle, obiekt). Każdy jest dodawany raz do twojej listy przy jej pierwszym odczycie (GET /subjects, MCPtendre_subject_list) i nie wlicza się do limitumax. Potem jest obiektem jak pozostałe: można go użyć w Multi-Ref (subject_id), zmienić i usunąć; po usunięciu nigdy nie wraca. - Odczyt:
GET /subjects/{id}; jeden obraz:GET /subjects/{id}/images/{n}/file. - Zmień:
PUT /subjects/{id}ztype,name,descriptioni/lubimages_b64(pełna lista, która zastępuje obrazy). - Usuń:
DELETE /subjects/{id}, tutaj i w aplikacji.
Styl nadaje klipowi wygląd: jego description podaje technikę, po angielsku (loose watercolor painting on textured paper), a nie to, co pokazują jego obrazy. Strój to ubranie noszone przez postać. Style i stroje działają tylko w Multi-Ref Wideo, w Ultra.
Aby obsadzić obiekt w klipie, zob. Multi-Ref Wideo; na obrazie, zob. Utwórz obraz.
Generowanie obiektu bez zdjęć
Nie masz pod ręką żadnego zdjęcia? POST /subjects/generate (uprawnienie images) tworzy obiekt tak jak okno „Generować” w Elementach aplikacji: obraz startowy na podstawie Twojego opisu (lub zaimportowany), a potem widoki, które z niego wychodzą (inne kąty, zbliżenie, nocą...), każdy retuszowany z obrazu startowego, aby zachować ten sam kształt. Wynik to zwykły obiekt: działa w Multi-Ref Wideo i w Utwórz obraz, i pojawia się w Bibliotece aplikacji.
| Pole | Typ | Co robi |
|---|---|---|
type | object, location, animal, style lub outfit | Czym jest obiekt (ruchu się nie generuje) |
name | jedno słowo, od 1 do 40 liter, cyfr lub _ | Słowo pisane po @ w prompcie |
description | tekst po angielsku, najwyżej 300 znaków | Sam element: kształt, materiały, kolory, szczegóły, bez tła i bez postaci (a glossy white futuristic tram with round windows). Wymagany, chyba że podano prompt lub start_image_b64 |
prompt | tekst po angielsku, najwyżej 2000 znaków, opcjonalny | Pełny tekst obrazu startowego, zamiast tekstu automatycznego z description |
start_image_b64 | obraz w base64, opcjonalny | Zaimportowany obraz startowy (co najmniej 512 px), zachowany bez zmian i bezpłatny |
views | lista kluczy, opcjonalna | Widoki, których chcesz, w kolejności (tabela poniżej) |
count | od 1 do 6, opcjonalny | Zamiast views: liczba obrazów łącznie, ze startem (pierwsze widoki z tabeli) |
seed | liczba całkowita, opcjonalna | Seed obrazu startowego |
quote_only | true | Zwraca tylko cenę, nic nie jest tworzone |
Widoki według typu (stałe klucze), w formacie wyjściowym typu:
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (zbliżenie) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (zbliżenie) |
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 (zbliżenie) |
Cena: każdy wyrenderowany obraz (start i każdy widok) kosztuje tyle co jeden obraz (1 kredyt); zaimportowany start jest bezpłatny, a nieudany obraz nie jest naliczany. Najwyżej 6 obrazów na obiekt, ze startem. Odpowiedź, 202, to obiekt z cost_estimate i 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"]
}Śledź go przez GET /subjects/{id}, aż generation.status przestanie być pending (ready, partial lub failed); n to numer obrazu w images. Obrazy powstają po jednym: start, potem widoki w kolejności. Błąd zatrzymuje serię: kolejne widoki przechodzą w failed, bez naliczenia.
- Dodaj widoki:
POST /subjects/{id}/viewszviews(klucze jeszcze niewykonane). Przy jednym widokuinstructions(po angielsku, najwyżej 1000 znaków) zastępuje jego polecenie: powiedz, co widok ma pokazać. - Ponów widok:
POST /subjects/{id}/views/{key}/redo, w razie potrzeby zinstructions. Widok wychodzi znów z obrazu startowego i zastępuje poprzedni (to samon). - Ponów start:
POST /subjects/{id}/views/start/redo, tylko dopóki żaden widok z niego nie wyszedł (inaczejviews_exist); zaimportowanego startu nie można ponowić. Widoki zatrzymane przez błąd startu ruszają ponownie po nim. quote_only: truezwraca cenę na wszystkich trzech trasach. Jedna seria naraz na obiekt (subject_busy).
Od początku do końca, przedmiot z dwoma widokami:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Odpowiedź, 202, podaje subject_id z generation.status pending. Odpytuj GET /subjects/{id} co kilka sekund aż do ready, a potem obsadź @Tram z tym subject_id. Trzy obrazy (start i dwa widoki), czyli trzy razy cena jednego obrazu.
Przechowywanie
Widoki postaci i obrazy obiektów są szyfrowane (jeden klucz na plik) i powiązane z Twoją licencją.
Obrazy obiektów są przechowywane dokładnie tak, jak je przesłałeś, i udostępniane Bibliotece aplikacji.
Limity przy licencji Pro: 50 postaci, wliczając te z aplikacji, i 50 obiektów (miejsca, przedmioty, zwierzęta, style i stroje łącznie),
liczone osobno (10 przy licencji osobistej, w aplikacji). Postać lub obiekt nieużywany przez rok
zostaje usunięty (expires_at): każdy render Multi-Ref, każdy Face swap i każdy odczyt widoku lub
obrazu przesuwa datę. Zdjęcie przesłane do stworzenia postaci jest przechowywane jako widok jej roli,
zaszyfrowane, tak jak wygenerowane widoki. Możesz usunąć każdy z nich w dowolnym momencie.
Przez agenta (MCP)
Dzięki serwerowi MCP wystarczy poprosić: "stwórz postać z tego zdjęcia". Agent
używa tendre_character_create (zdjęcie trafia przez link do przesyłania, plik dołączony w ChatGPT,
obraz wyrenderowany w rozmowie lub publiczny adres), pokazuje siedem widoków i ponawia nieudany
za pomocą tendre_character_redo_view, dodając instruction, gdy widok wymaga pokierowania, lub
zastępuje go Twoim własnym obrazem przez tendre_character_set_view. tendre_character_get,
tendre_character_list i tendre_character_delete obejmują resztę, a tendre_quote podaje cenę z wyprzedzeniem.
Dla miejsca, obiektu lub zwierzęcia podaj agentowi swoje zdjęcia i powiedz, czym jest: używa
tendre_subject_create, a następnie tendre_subject_list, tendre_subject_get i tendre_subject_delete. Bez zdjęć używa tendre_subject_generate, a następnie tendre_subject_add_views i tendre_subject_redo_view, aby dodać lub ponowić widok.
Następnie obsadź postać: zob. Multi-Ref Wideo.