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

RolaWidok
1Popiersie z przodu, neutralny wyraz twarzy
4Cała sylwetka z przodu
5Cała sylwetka, tył
6Cała sylwetka z profilu, postać patrzy w lewą stronę obrazu
7Zbliżenie twarzy, z przodu
8Zbliżenie stroju, od klatki piersiowej do kolan
9Zbliż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.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
PoleTypCo robi
namestring, 1 do 40 znakówImię postaci
kindstringwoman, man lub stworzenie opisane po angielsku (baby dragon). Określa zaimki w instrukcjach, nigdy "they".
image_b64base64Zdjęcie: wyraźne, tylko jedna osoba, co najmniej 1024 px po dłuższej stronie, maksymalnie 12 MB, JPEG, PNG lub WebP
photo_rolebust (domyślnie) lub full_bodyZdjęcie to popiersie (staje się widokiem 1) lub ujęcie całej sylwetki (widok 4)
outfittekst po angielsku, opcjonalniePrzy 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:

statusZnaczenie
pendingWidoki są w trakcie tworzenia
readyWszystkie siedem widoków jest gotowych
partialNiektóre widoki są brakujące lub nieudane
failed, emptyBrak użytecznego widoku
json
{
  "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}/file zwraca 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), z outfit lub 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 razie 409 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} z image_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 /characters zwraca Twoje postacie, w tym te z aplikacji, oraz limit max.
  • 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.

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
PoleTypCo robi
namestring, 1 do 40 znakówNazwa character sheet
outfittekst po angielsku, maksymalnie 700 znakówStrój do nałożenia; wymagany bez views
viewsobiekt, rola "1" lub "4" do "9": obraz w base64Gotowe widoki, z tymi samymi zasadami co przesyłanie widoku
generatetrue (domyślnie) lub falseWygenerować brakujące role, czy żadnej
from_sheet_idstring, opcjonalnieBez views: character sheet, od której zacząć
kindstringTylko 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 bez views. generate: false nie 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_id zaczyna 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_estimate podaje cenę. Jeśli sheet źródłowy (from_sheet_id lub domyślny) jest takim pojedynczym obrazem, prześlij widok 4 (cała postać) lub 1 (popiersie) w views (409 single_image_sheet).
  • Używaj character sheet jak pozostałych, z ?sheet=<sheet_id>: w GET /characters/{id}, przy pliku widoku, w redo (łącznie z instruction) i w PUT widoku. 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: false bez 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):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
PoleTypCo robi
typelocation, object, animal, style lub outfitCzym jest obiekt
namejedno słowo, 1 do 40 liter, cyfr lub _Słowo pisane po @ w prompcie
descriptiontekst po angielsku, maksymalnie 300 znaków, opcjonalniea glossy white futuristic tram with round windows
images_b641 do 6 obrazów w base64JPEG, 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}/images z image_b64 (maksymalnie 6).
  • Lista: GET /subjects (?type=location do filtrowania) zwraca Twoje obiekty, w tym te z Biblioteki aplikacji (origin app), oraz limit max. Obiekt z aplikacji, którego obrazy nie są jeszcze wszystkie zsynchronizowane, ma complete: 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, MCP tendre_subject_list) i nie wlicza się do limitu max. 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} z type, name, description i/lub images_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.

PoleTypCo robi
typeobject, location, animal, style lub outfitCzym jest obiekt (ruchu się nie generuje)
namejedno słowo, od 1 do 40 liter, cyfr lub _Słowo pisane po @ w prompcie
descriptiontekst po angielsku, najwyżej 300 znakówSam 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
prompttekst po angielsku, najwyżej 2000 znaków, opcjonalnyPełny tekst obrazu startowego, zamiast tekstu automatycznego z description
start_image_b64obraz w base64, opcjonalnyZaimportowany obraz startowy (co najmniej 512 px), zachowany bez zmian i bezpłatny
viewslista kluczy, opcjonalnaWidoki, których chcesz, w kolejności (tabela poniżej)
countod 1 do 6, opcjonalnyZamiast views: liczba obrazów łącznie, ze startem (pierwsze widoki z tabeli)
seedliczba całkowita, opcjonalnaSeed obrazu startowego
quote_onlytrueZwraca tylko cenę, nic nie jest tworzone

Widoki według typu (stałe klucze), w formacie wyjściowym typu:

typeFormatviews
object1024 × 1024three_quarter, side, back, top, detail (zbliżenie)
location1216 × 832reverse_shot, side, high_angle, night, detail (zbliżenie)
animal1216 × 832front, three_quarter, back, sitting, lying
style1024 × 1024portrait, landscape, interior, object, animal
outfit832 × 1216three_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:

json
"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}/views z views (klucze jeszcze niewykonane). Przy jednym widoku instructions (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 z instructions. Widok wychodzi znów z obrazu startowego i zastępuje poprzedni (to samo n).
  • Ponów start: POST /subjects/{id}/views/start/redo, tylko dopóki żaden widok z niego nie wyszedł (inaczej views_exist); zaimportowanego startu nie można ponowić. Widoki zatrzymane przez błąd startu ruszają ponownie po nim.
  • quote_only: true zwraca cenę na wszystkich trzech trasach. Jedna seria naraz na obiekt (subject_busy).

Od początku do końca, przedmiot z dwoma widokami:

http
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.

Windows · Mac · Chmura lub lokalnie

Generuj prywatnie. Już dziś wieczorem.

Pobierz tendre.AI za darmo i generuj bez limitów, prywatnie, na własnym GPU.

OS Windows 10/11GPU NVIDIA 8GB+VRAM 12GB zalecaneDysk 20GB

Mac z chipem Apple (M1 lub nowszy): macOS 13 lub nowszy. Intel Mac: macOS 12 lub nowszy, wszystko działa online.

Lokalne generowanie obrazów na Macu wymaga M4 z 24 GB pamięci albo M2 lub M3 Pro, Max lub Ultra z 24 GB. Poniżej tego progu wszystko działa online, na kredytach. Retusz i wideo na Macu na razie też działają online.

Wszystko o tendre.AI na Maca

Nie masz karty NVIDIA? Zacznij w 100% w chmurze: 5 darmowych zdjęć i 1 darmowe wideo każdego dnia. Karta NVIDIA (8GB+) odblokowuje nielimitowane generowanie lokalne.