Pro API: Charaktere für Multi-Ref Video erstellen
Ein Charakter ist ein Sheet mit sieben Ansichten derselben Person (oder Kreatur), erstellt aus einem Foto
und gespeichert unter einer character_id. Das ist es, was Multi-Ref Video verwendet, um
jemanden in einem Clip zu erkennen: Seine Ansichten tragen die Ähnlichkeit, ganz ohne Training.
Face swap nutzt sie ebenfalls, um den Charakter anstelle der Person in deinem
eigenen Video einzusetzen.
Die Charaktere, die du in der App erstellt hast, sind bereits vorhanden: gleiche Lizenz, gleiche Liste (siehe Charaktere aus der App). Orte, Objekte und Tiere werden auf dieselbe Weise gespeichert, aus Bildern, die du bereitstellst, und kommen in denselben Clips zum Einsatz (siehe Orte, Objekte und Tiere).
Die sieben Ansichten
| Rolle | Ansicht |
|---|---|
| 1 | Büste frontal, neutraler Ausdruck |
| 4 | Ganzkörper frontal |
| 5 | Ganzkörper, Rücken |
| 6 | Ganzkörper im Profil, der Charakter schaut zur linken Seite des Bildes |
| 7 | Nahaufnahme des Gesichts, frontal |
| 8 | Nahaufnahme des Outfits, von der Brust bis zu den Knien |
| 9 | Nahaufnahme der Füße, mit Schuhen oder barfuß je nach Outfit |
Jede Ansicht wird einzeln generiert: keine wird durch Spiegeln einer anderen erstellt. Die Rollen 2 und 3 (Büsten im Dreiviertelprofil) werden seit dem 21. Oktober 2026 nicht mehr erstellt: Ein Charakter, der vorher erstellt wurde, behält sie, sie lassen sich weiter lesen (Datei einer Ansicht, Liste views), aber nicht mehr wiederholen (400 invalid_role).
Einen Charakter erstellen
POST /characters (Berechtigung images). Die Verarbeitung erfolgt asynchron.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Feld | Typ | Funktion |
|---|---|---|
name | String, 1 bis 40 Zeichen | Der Vorname des Charakters |
kind | String | woman, man oder eine auf Englisch beschriebene Kreatur (baby dragon). Legt die Pronomen der Anweisungen fest, nie "they". |
image_b64 | base64 | Das Foto: scharf, nur eine Person, mindestens 1024 px auf der langen Seite, maximal 12 MB, JPEG, PNG oder WebP |
photo_role | bust (Standard) oder full_body | Das Foto ist eine Büste (wird zu Ansicht 1) oder eine Ganzkörperaufnahme (Ansicht 4) |
outfit | Englischer Text, optional | Bei einem Büstenfoto das Outfit der Ganzkörperansicht (a red leather jacket and black jeans): der Unterkörper, den die Büste nicht zeigt. Bei einem Ganzkörperfoto ist das Foto maßgeblich, und das Outfit wird nicht angelegt |
Die Antwort, 202, ist der Charakter mit status pending und cost_estimate. Das Foto wird zur Ansicht seiner Rolle, unverändert übernommen (nie umgekleidet), und der Server generiert die anderen sechs in 2 bis 5 Minuten, genauso wie die App: Der Körper (Rücken, Profil, Outfit, Füße) geht von der Ganzkörperansicht aus, die Nahaufnahme des Gesichts von der Büste. Ein Büstenfoto wird zur Ganzkörperansicht erweitert (mit outfit, wenn angegeben); ein Ganzkörperfoto ergibt die Büste durch einen Ausschnitt.
Preis: ein Credit pro generierter Ansicht, also 6 Credits, mit oder ohne outfit. Eine fehlgeschlagene Ansicht wird nicht berechnet. POST /characters/quote gibt den Preis vorab.
Dieselbe Erstellung erneut senden. Bricht die Verbindung vor der Antwort ab oder wird das Warten eines Agenten unterbrochen, erstellt der Server den Charakter weiter. Dieselbe Anfrage erneut senden (dasselbe Foto, name, kind, photo_role und outfit): Sie liefert den bereits erstellten Charakter zurück, mit existing: true und einem cost_estimate von 0, und nichts wird doppelt berechnet. Ein neuer Charakter entsteht nur, wenn alle generierten Ansichten des ersten fehlgeschlagen sind; einzelne fehlgeschlagene Ansichten werden eine nach der anderen wiederholt (redo). Kommen zwei identische Anfragen im selben Moment an, erhält die zweite 409 character_busy: sie einige Sekunden später erneut senden.
Verfolgen, prüfen, wiederholen
GET /characters/{id} gibt den aktuellen Status zurück:
status | Bedeutung |
|---|---|
pending | Die Ansichten werden gerade erstellt |
ready | Alle sieben Ansichten sind vorhanden |
partial | Einige Ansichten fehlen oder sind fehlgeschlagen |
failed, empty | Keine verwendbare Ansicht |
{
"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"
}- Prüfe die Ansichten vor dem ersten Render.
GET /characters/{id}/views/{role}/filegibt das Bild zurück. Die Ganzkörperansichten (4, 5 und 6) werden in 2K erzeugt, 1024 x 2048, die Büste und die Nahaufnahmen in 832 x 1216 (1216 x 832 für die Füße), als PNG, oder als JPEG über 2,9 MB. Die Ansicht aus deinem Foto behält ihre Größe (höchstens 2048 px). Bereits erstellte Ansichten behalten ihre Größe; eine wiederholte Ansicht kommt in diesen Größen. Eine fehlgeschlagene Ansicht oder ein Profil, das in die falsche Richtung schaut, beeinträchtigt die Ähnlichkeit in jedem Video. - Eine Ansicht wiederholen:
POST /characters/{id}/views/{role}/redo, 1 Credit: eine neue Generierung ab ihrem Ausgangspunkt (der Ganzkörperansicht oder der Büste). Die Ansicht, die aus dem Originalfoto stammt, kann nicht wiederholt werden (photo_view), mit oder ohneoutfit. Ein in der App als einzelnes Bild importiertes Sheet (ein ganzes Sheet, unverändert übernommen) wird nicht Ansicht für Ansicht neu erstellt (409 single_image_sheet). - Eine wiederholte Ansicht steuern: Füge
instruction(200 Zeichen, Englisch) zum Redo-Body hinzu, für einen Charakter, der über die API erstellt wurde, oder ein über die API hinzugefügtes Sheet (andernfalls409 app_character). Es gibt vor, was die Ansicht vom Charakter zeigen soll, z. B. die Seite einer Prothese oder das Vorhandensein eines Details, nie eine andere Änderung: Outfit, Haare, Pose, Setting und Ausdruck werden anderswo geändert. Schreib es im Imperativ (der Engine ignoriert beschriebene Zustände):"Put the robotic arm on her left side only, remove any second robotic arm."Bei der Rückenansicht (5) benenne die Seite auf beide Arten:"her left arm, which appears on the left side of the image when seen from behind". Gleicher Preis, 1 Credit. - Eigenes Bild für eine Ansicht hochladen:
PUT /characters/{id}/views/{role}mitimage_b64(dieselben Regeln wie beim Erstellungsfoto: mindestens 1024 px auf der langen Seite, 12 MB, JPEG, PNG oder WebP), für einen über die API erstellten Charakter oder ein über die API hinzugefügtes Sheet (?sheet=). Kostenlos, es wird nichts generiert. Das Bild wird unverändert übernommen und gilt als echtes Foto: Die danach wiederholten Ansichten gehen nach der Regel der Erstellung von ihm aus (Rücken, Profil und die Nahaufnahmen von Outfit und Füßen von der Ganzkörperansicht, die Nahaufnahme des Gesichts von der Büste). - Liste:
GET /charactersgibt deine Charaktere zurück, einschließlich derer aus der App, sowie das Limitmax. - Löschen:
DELETE /characters/{id}löscht den Charakter und seine Ansichten.
In der App (Version 0.8.6 und höher): Ein über die API oder den MCP erstellter Charakter erscheint im
Meine Charaktere-Bereich der App, auf derselben Lizenz, mit seinem Namen und seinen Ansichten, wie die in der App erstellten. Eine in der App wiederholte Ansicht ersetzt die Online-Ansicht, also die, die Multi-Ref Video liest. Das Löschen in der App löscht ihn auch hier endgültig (die App fragt zuerst nach Bestätigung): Eine Pipeline, die eine
character_id beibehält, sollte mit einem 404 unknown_character rechnen, sobald der Charakter in der App gelöscht wurde.
Charaktere aus der App
Ein in der Meine Charaktere-Ansicht der App erstellter Charakter erscheint in GET /characters mit origin
app und spielt in Multi-Ref Video wie jeder andere. In der App kann ein Charakter mehrere
Sheets haben (Outfits, Stimmungen): sheet_id gibt an, welches verwendet wird (standardmäßig das neueste), sheets
listet sie auf, und ?sheet=<id> fragt bei der Leseoperation, bei einer Ansichtsdatei und bei einer wiederholten Ansicht nach einem anderen. In einem Multi-Ref-Clip wählt characters[].sheet_id das Sheet aus. Er trägt name und kind seines Profils aus der App, sobald die App sie gesendet hat (App 0.9.1 und neuer; davor sind beide null). Um eine Ansicht eines App-Charakters zu wiederholen, dessen kind noch null ist,
gib dessen kind im Body an.
Stimme. has_voice gibt an, ob die Stimme aus dem Profil des Charakters online ist: Die App sendet sie mit dem Charakter, und Face swap und Multi-Ref Video verwenden sie standardmäßig.
Einem Charakter ein Outfit hinzufügen
POST /characters/{id}/sheets gibt einem bestehenden Charakter ein neues Sheet (ein Outfit, einen Look), egal ob er über die API oder in der App erstellt wurde, die Presets der App eingeschlossen. Der Charakter behält seine anderen Sheets. Die Antwort, 202, ist der Charakter mit dem neuen Sheet: seine sheet_id (sie beginnt mit api-), sheet_name, sheet_outfit, sheet_origin: "api" und cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Feld | Typ | Funktion |
|---|---|---|
name | String, 1 bis 40 Zeichen | Der Name des Sheets |
outfit | Englischer Text, höchstens 700 Zeichen | Das anzulegende Outfit; ohne views Pflicht |
views | Objekt, Rolle "1" oder "4" bis "9": ein Bild in Base64 | Fertige Ansichten, mit denselben Regeln wie beim Hochladen einer Ansicht |
generate | true (Standard) oder false | Die fehlenden Rollen generieren, oder keine |
from_sheet_id | String, optional | Ohne views: das Sheet, von dem ausgegangen wird |
kind | String | Nur für einen in der App erstellten Charakter, dessen kind in GET /characters noch null ist, wie bei der Erstellung |
- Mit
views: Die gesendeten Ansichten werden unverändert abgelegt, kostenlos. Die fehlenden Rollen werden generiert, 1 Credit pro Ansicht, nach der Regel der Erstellung, aus der gesendeten Ganzkörperansicht und Büste; ohne beide wie ohneviews.generate: falsegeneriert keine. - Ohne
views: Das Outfit wird auf die Ganzkörperansicht des Charakters gelegt (auf seine Büste, wenn er keine hat;from_sheet_idgeht von einem anderen Sheet aus). Das Ergebnis wird zur Ganzkörperansicht des neuen Sheets, und die sechs anderen Ansichten gehen von ihm aus: 7 generierte Ansichten, 7 Credits.cost_estimatenennt den Preis. Ist das Ausgangs-Sheet (from_sheet_idoder das standardmäßige) ein solches Einzelbild, senden Sie Ansicht 4 (Ganzkörper) oder 1 (Büste) inviews(409 single_image_sheet). - Nutze das Sheet wie die anderen, mit
?sheet=<sheet_id>: beiGET /characters/{id}, bei der Datei einer Ansicht, beiredo(instructioneingeschlossen) und beimPUTeiner Ansicht. In einem Multi-Ref-Clip wähltcharacters[].sheet_ides aus. - Bei einem Charakter aus der App
sheet_idangeben: Standardmäßig wird weiterhin das zuletzt geänderte Sheet verwendet, also jetzt das gerade hinzugefügte. - Ein hinzugefügtes Sheet löschen:
DELETE /characters/{id}/sheets/{sheet_id}löscht nur seine Ansichten. Ein in der App erstelltes Sheet lässt sich so nicht löschen (404 unknown_sheet). - In der App: Die App mit derselben Lizenz holt das neue Sheet in das Profil des Charakters.
- Fehler:
400 outfit_or_views_required(weder Outfit noch Ansichten),400 views_required(generate: falseohne Ansicht),409 source_sheet_empty(weder Ganzkörperansicht noch Büste als Ausgangspunkt),409 character_busy.
Orte, Objekte, Tiere, Stile und Outfits
Ein Motiv ist ein Ort (location), ein Objekt (object: ein Fahrzeug, ein Requisit, ein Möbelstück ...), ein Tier (animal), ein Stil (style: Stimmungsbilder, deren Look das Video übernimmt) oder ein Outfit (outfit: ein Kleidungsstück, das ein Charakter trägt), gespeichert aus 1 bis 6 Bildern, die du bereitstellst (mehrere Winkel machen es treuer), damit du es in Multi-Ref Video wiederverwenden kannst,
ohne es in jedem Shot erneut beschreiben zu müssen. Es wird kein Bild generiert, daher ist es kostenlos.
Ohne Bilder kann der Server es auch generieren: siehe Ein Motiv ohne Bilder generieren.
POST /subjects (Berechtigung images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Feld | Typ | Funktion |
|---|---|---|
type | location, object, animal, style oder outfit | Was das Motiv ist |
name | ein Wort, 1 bis 40 Buchstaben, Ziffern oder _ | Das Wort, das nach @ im Prompt steht |
description | Englischer Text, maximal 300 Zeichen, optional | a glossy white futuristic tram with round windows |
images_b64 | 1 bis 6 Bilder in base64 | JPEG, PNG oder WebP, mindestens 512 px auf der langen Seite, maximal 12 MB pro Bild (28 MB für den gesamten Body: darüber hinaus die nächsten einzeln hinzufügen) |
Die Antwort, 201, ist das Motiv: subject_id, type, name, description, origin, seine images
(jeweils mit einer file_url), complete und expires_at.
- Ein Bild hinzufügen:
POST /subjects/{id}/imagesmitimage_b64(maximal 6). - Liste:
GET /subjects(?type=locationzum Filtern) gibt deine Motive zurück, einschließlich derer aus der Bibliothek der App (originapp), sowie das Limitmax. Ein App-Motiv, dessen Bilder noch nicht vollständig synchronisiert sind, hatcomplete: false: Es spielt mit den bereits vorhandenen Bildern. - Geschenkte Elemente: Tendre.AI stellt sofort nutzbare Elemente mit fester id bereit (zum Beispiel
officiel-red-beetle, ein Objekt). Jedes wird beim ersten Abruf deiner Liste einmal hinzugefügt (GET /subjects, MCPtendre_subject_list) und zählt nicht zum Limitmax. Danach ist es ein Subjekt wie die anderen: in Multi-Ref nutzbar (subject_id), änderbar, löschbar; einmal gelöscht, kommt es nie zurück. - Lesen:
GET /subjects/{id}; ein Bild:GET /subjects/{id}/images/{n}/file. - Ändern:
PUT /subjects/{id}mittype,name,descriptionund/oderimages_b64(die vollständige Liste, die die Bilder ersetzt). - Löschen:
DELETE /subjects/{id}, hier und in der App.
Ein Stil gibt einem Clip seinen Look: Seine description nennt die Technik, auf Englisch (loose watercolor painting on textured paper), nicht das, was seine Bilder zeigen. Ein Outfit ist ein Kleidungsstück, das ein Charakter trägt. Stile und Outfits wirken nur in Multi-Ref Video, in Ultra.
Um ein Motiv in einem Clip zu besetzen, siehe Multi-Ref Video; in einem Bild, siehe Bild erstellen.
Ein Motiv ohne Bilder generieren
Kein Bild zur Hand? POST /subjects/generate (Berechtigung images) erstellt das Motiv wie das Fenster „Generieren“ der Elemente in der App: ein Startbild aus deiner Beschreibung (oder importiert), dann Ansichten, die davon ausgehen (andere Winkel, eine Nahaufnahme, bei Nacht ...), jede aus dem Startbild retuschiert, damit die Form gleich bleibt. Das Ergebnis ist ein gewöhnliches Motiv: Es spielt in Multi-Ref Video und in Bild erstellen und erscheint in der Bibliothek der App.
| Feld | Typ | Was es macht |
|---|---|---|
type | object, location, animal, style oder outfit | Was das Motiv ist (eine Bewegung wird nicht generiert) |
name | ein Wort, 1 bis 40 Buchstaben, Ziffern oder _ | Das Wort nach @ im Prompt |
description | Englischer Text, höchstens 300 Zeichen | Das Element allein: Form, Materialien, Farben, Details, ohne Hintergrund und ohne Charakter (a glossy white futuristic tram with round windows). Pflicht, außer mit prompt oder start_image_b64 |
prompt | Englischer Text, höchstens 2.000 Zeichen, optional | Der vollständige Text des Startbilds, anstelle des automatischen Texts aus description |
start_image_b64 | Bild in Base64, optional | Ein importiertes Startbild (mindestens 512 px), unverändert übernommen und kostenlos |
views | Liste von Schlüsseln, optional | Die gewünschten Ansichten, in Reihenfolge (Tabelle unten) |
count | 1 bis 6, optional | Anstelle von views: die Anzahl der Bilder insgesamt, Start inklusive (die ersten Ansichten der Tabelle) |
seed | Ganzzahl, optional | Seed des Startbilds |
quote_only | true | Gibt nur den Preis zurück, nichts wird erstellt |
Ansichten pro Typ (feste Schlüssel), im Ausgabeformat des Typs:
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (Nahaufnahme) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (Nahaufnahme) |
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 (Nahaufnahme) |
Preis: Jedes gerenderte Bild (der Start und jede Ansicht) kostet den Preis eines Bildes (1 Credit); ein importierter Start ist kostenlos, und ein fehlgeschlagenes Bild wird nicht abgebucht. Höchstens 6 Bilder pro Motiv, Start inklusive. Die Antwort, 202, ist das Motiv mit cost_estimate und 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"]
}Verfolge es mit GET /subjects/{id}, bis generation.status nicht mehr pending ist (ready, partial oder failed); n ist die Nummer des Bildes in images. Die Bilder laufen eines nach dem anderen: der Start, dann die Ansichten in Reihenfolge. Ein Fehler stoppt die Serie: Die folgenden Ansichten werden failed, ohne Abbuchung.
- Ansichten hinzufügen:
POST /subjects/{id}/viewsmitviews(noch nicht erstellte Schlüssel). Mit einer Ansicht ersetztinstructions(Englisch, höchstens 1.000 Zeichen) ihre Vorgabe: Sag, was die Ansicht zeigen soll. - Eine Ansicht neu machen:
POST /subjects/{id}/views/{key}/redo, bei Bedarf mitinstructions. Die Ansicht geht erneut vom Startbild aus und ersetzt die vorherige (gleichesn). - Den Start neu machen:
POST /subjects/{id}/views/start/redo, nur solange keine Ansicht davon ausgeht (sonstviews_exist); ein importierter Start lässt sich nicht neu machen. Durch einen fehlgeschlagenen Start gestoppte Ansichten laufen danach erneut. quote_only: truegibt den Preis auf allen drei Routen zurück. Eine Serie pro Motiv auf einmal (subject_busy).
Von Anfang bis Ende, ein Objekt mit zwei Ansichten:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }Die Antwort, 202, liefert die subject_id mit generation.status pending. Frage GET /subjects/{id} alle paar Sekunden ab, bis es ready ist, dann besetze @Tram mit dieser subject_id. Drei Bilder (der Start und zwei Ansichten), also dreimal der Preis eines Bildes.
Speicherung
Die Charakteransichten und die Motivbilder sind verschlüsselt (ein Schlüssel pro Datei) und an deine
Lizenz gebunden. Motivbilder werden so gespeichert, wie du sie geschickt hast, und mit der Bibliothek der App geteilt. Limits mit der
Pro-Lizenz: 50 Charaktere, einschließlich derer aus der App, und 50 Motive (Orte, Objekte, Tiere, Stile und Outfits zusammen), separat gezählt (10 mit einer persönlichen Lizenz, in der App). Ein Charakter oder ein Motiv, das ein Jahr lang nicht verwendet wird, wird gelöscht (expires_at): Jeder Multi-Ref-Render, jeder Face swap und jedes Lesen einer Ansicht oder eines Bildes verschiebt das Datum nach hinten. Das Foto, das du zum Erstellen eines Charakters schickst, wird als Ansicht seiner Rolle gespeichert, verschlüsselt, wie die
generierten Ansichten. Du kannst sie jederzeit löschen.
Über einen Agenten (MCP)
Mit dem MCP-Server sagst du einfach: "Erstell einen Charakter aus diesem Foto". Der Agent
nutzt tendre_character_create (das Foto kommt über einen Upload-Link, eine in ChatGPT angehängte Datei,
ein im Gespräch gerendertes Bild oder eine öffentliche Adresse), zeigt dir die sieben Ansichten und wiederholt eine
fehlgeschlagene mit tendre_character_redo_view, mit einer instruction, wenn die Ansicht geführt werden muss, oder
ersetzt sie durch dein eigenes Bild über tendre_character_set_view. tendre_character_get,
tendre_character_list und tendre_character_delete decken den Rest ab, und tendre_quote gibt den
Preis vorab.
Für einen Ort, ein Objekt oder ein Tier gibst du dem Agenten deine Bilder und sagst, was es ist: Er verwendet
tendre_subject_create, dann tendre_subject_list, tendre_subject_get und tendre_subject_delete. Ohne Bilder verwendet er tendre_subject_generate, dann tendre_subject_add_views und tendre_subject_redo_view, um eine Ansicht hinzuzufügen oder neu zu machen.
Dann besetz den Charakter: siehe Multi-Ref Video.