Pro API: create characters for Multi-Ref Video
A character is a sheet of seven views of the same person (or creature), made from one photo
and stored under a character_id. It is what Multi-Ref Video uses to
recognise someone in a clip: its views carry the likeness, with no training.
Face swap uses them too, to put the character in place of the person in your
own video.
The characters you made in the app are already there: same licence, same list (see Characters from the app). Locations, objects and animals are stored the same way, from images you supply, and play in the same clips (see Locations, objects and animals).
The seven views
| Role | View |
|---|---|
| 1 | Bust, front, neutral expression |
| 4 | Full body, front |
| 5 | Full body, back |
| 6 | Full body, side profile, the character looks towards the left of the image |
| 7 | Close-up of the face, front |
| 8 | Close-up of the outfit, from the chest to the knees |
| 9 | Close-up of the feet, in shoes or bare depending on the outfit |
Every view is generated on its own: none is obtained by flipping another. Roles 2 and 3 (three-quarter busts) are no longer created since 21 October 2026: a character made before keeps them, and they can still be read (a view's file, the views list) but not redone (400 invalid_role).
Create a character
POST /characters (permission images). The work is asynchronous.
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }| Field | Type | What it does |
|---|---|---|
name | string, 1 to 40 characters | The character's first name |
kind | string | woman, man, or a creature described in English (baby dragon). It sets the pronouns of the instructions, never "they". |
image_b64 | base64 | The photo: sharp, one person only, at least 1024 px on the long side, 12 MB at most, JPEG, PNG or WebP |
photo_role | bust (default) or full_body | The photo is a bust (it becomes view 1) or a full-body shot (view 4) |
outfit | English text, optional | With a bust photo, the outfit of the full-body view (a red leather jacket and black jeans): the lower body, which the bust does not show. With a full-body photo, the photo prevails and the outfit is not applied |
The answer, 202, is the character with status pending and cost_estimate. The photo becomes the view of its role, kept as it is (never re-dressed), and the server generates the other six, in 2 to 5 minutes, the same way as the app: the body (back, profile, outfit, feet) starts from the full-body view, the close-up of the face from the bust. A bust photo is extended into the full-body view (wearing outfit if given); a full-body photo gives the bust by cropping.
Price: one credit per generated view, so 6 credits, with or without outfit. A view that fails is not charged. POST /characters/quote gives the price beforehand.
Sending the same creation again. If the connection drops before the answer, or an agent's wait is interrupted, the server goes on making the character. Send the same request again (same photo, name, kind, photo_role and outfit): it returns the character already created, with existing: true and a cost_estimate of 0, and nothing is charged twice. It only creates a new one if every generated view of the first one failed; a few failed views are redone one by one (redo). If two identical requests arrive at the same moment, the second gets 409 character_busy: send it again a few seconds later.
Follow, check, redo
GET /characters/{id} gives its state:
status | Meaning |
|---|---|
pending | The views are being made |
ready | The seven views are there |
partial | Some views are missing or failed |
failed, empty | No usable view |
{
"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"
}- Check the views before the first render.
GET /characters/{id}/views/{role}/filereturns the image. The full-body views (4, 5 and 6) are generated in 2K, 1024 x 2048, and the bust and the close-ups in 832 x 1216 (1216 x 832 for the feet), as PNG, or JPEG above 2.9 MB. The view made from your photo keeps its size (2048 px at most). Views already made keep their size; a redone view comes out at these sizes. A failed view, or a profile that looks the wrong way, spoils the likeness in every video. - Redo a view:
POST /characters/{id}/views/{role}/redo, 1 credit: a fresh render from its starting point (the full-body view or the bust). The view that came from the original photo cannot be redone (photo_view), with or withoutoutfit. A sheet imported in the app as a single image (a whole sheet, kept as is) is not redone view by view (409 single_image_sheet). - Guide a redone view: add
instruction(200 characters, English) to the redo body, for a character created through the API, or a sheet added through the API (otherwise409 app_character). It specifies what the view must show of the character, such as the side of a prosthesis or the presence of a detail, never another change: outfit, hair, pose, setting and expression are changed elsewhere. Write it in the imperative (the engine ignores a described state):"Put the robotic arm on her left side only, remove any second robotic arm."On the back view (5), name the side both ways:"her left arm, which appears on the left side of the image when seen from behind". Same price, 1 credit. - Upload your own image for a view:
PUT /characters/{id}/views/{role}withimage_b64(the same rules as the creation photo: at least 1024 px on the long side, 12 MB, JPEG, PNG or WebP), for a character created through the API, or a sheet added through the API (?sheet=). Free, nothing is generated. The image is kept as it is and counts as a real photo: the views redone afterwards start from it by the rule of creation (the back, the profile and the close-ups of the outfit and feet from the full-body view, the close-up of the face from the bust). - List:
GET /charactersreturns your characters, the app's included, and the capmax. - Delete:
DELETE /characters/{id}erases the character and its views.
In the app (version 0.8.6 and later): a character created through the API or the MCP appears in the
app's My characters screen, on the same licence, with its name and views, like the ones created in
the app. A view redone in the app replaces the online view, the one Multi-Ref Video reads. Deleting it
in the app erases it here too, for good (the app asks for confirmation first): a pipeline that keeps a
character_id should expect a 404 unknown_character once the character was deleted in the app.
Characters from the app
A character created in the app's My characters screen appears in GET /characters with origin
app, and plays in Multi-Ref Video like any other. In the app, a character can have several
sheets (outfits, moods): sheet_id says which one is served (the most recent by default), sheets
lists them, and ?sheet=<id> asks for another on the read, on a view's file and on a redone view.
In a Multi-Ref clip, characters[].sheet_id picks the sheet. It carries the name and kind of its profile in the app once the app has sent them (app 0.9.1 and later; before that, both are null). To redo a view of an app character whose kind is still null,
give its kind in the body.
Voice. has_voice says whether the voice of the character's profile is online: the app sends it with the character, and Face swap and Multi-Ref Video use it by default.
Add an outfit to a character
POST /characters/{id}/sheets gives an existing character a new sheet (an outfit, a look), whether it was created through the API or in the app, the app's presets included. The character keeps its other sheets. The answer, 202, is the character with the new sheet: its sheet_id (it starts with api-), sheet_name, sheet_outfit, sheet_origin: "api" and cost_estimate.
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
"views": { "1": "<base64>", "4": "<base64>" } }| Field | Type | What it does |
|---|---|---|
name | string, 1 to 40 characters | The sheet's name |
outfit | English text, 700 characters at most | The outfit to put on; required without views |
views | object, role "1" or "4" to "9": an image in base64 | Views that are ready, with the same rules as uploading a view |
generate | true (default) or false | Generate the missing roles, or none |
from_sheet_id | string, optional | Without views: the sheet to start from |
kind | string | Only for a character created in the app whose kind is still null in GET /characters, as at creation |
- With
views: the views you send are stored as they are, free. The missing roles are generated, 1 credit per view, by the rule of creation, from the full-body view and the bust you send; with neither of them, as withoutviews.generate: falsegenerates none. - Without
views: the outfit is put on the character's full-body view (on its bust if it has none;from_sheet_idstarts from another sheet). The result becomes the full-body view of the new sheet, and the other six views start from it: 7 generated views, 7 credits.cost_estimategives the price. If the source sheet (from_sheet_id, or the default one) is a sheet imported in the app as a single image, send view 4 (full body) or 1 (bust) inviews(409 single_image_sheet). - Use the sheet like the others, with
?sheet=<sheet_id>: onGET /characters/{id}, on a view's file, onredo(instructionincluded) and onPUTof a view. In a Multi-Ref clip,characters[].sheet_idpicks it. - For a character from the app, pass
sheet_id: the sheet served by default stays the most recently changed one, which is now the sheet you added. - Delete an added sheet:
DELETE /characters/{id}/sheets/{sheet_id}erases its views only. A sheet made in the app cannot be deleted this way (404 unknown_sheet). - In the app: the app on the same licence brings the new sheet into the character's profile.
- Errors:
400 outfit_or_views_required(neither an outfit nor views),400 views_required(generate: falsewithout a view),409 source_sheet_empty(neither a full-body view nor a bust to start from),409 character_busy.
Locations, objects, animals, styles and outfits
A subject is a location (location), an object (object: a vehicle, a prop, a piece of
furniture...), an animal (animal), a style (style: mood images whose look the video takes) or an outfit (outfit: a garment worn by a character), saved from 1 to 6 images that you supply (several angles
make it more faithful), so that you can use it again in Multi-Ref Video
without describing it again in every shot. No image is generated, so it is free.
Without images, the server can also generate one: see Generate a subject without images.
POST /subjects (permission images):
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }| Field | Type | What it does |
|---|---|---|
type | location, object, animal, style or outfit | What the subject is |
name | one word, 1 to 40 letters, digits or _ | The word written after @ in the prompt |
description | English text, 300 characters at most, optional | a glossy white futuristic tram with round windows |
images_b64 | 1 to 6 images in base64 | JPEG, PNG or WebP, at least 512 px on the long side, 12 MB each at most (28 MB for the whole body: beyond that, add the next ones one at a time) |
The answer, 201, is the subject: subject_id, type, name, description, origin, its images
(each with a file_url), complete and expires_at.
- Add an image:
POST /subjects/{id}/imageswithimage_b64(6 at most). - List:
GET /subjects(?type=locationto filter) returns your subjects, those of the app's Library included (originapp), and the capmax. An app subject whose images are not all synced yet hascomplete: false: it plays with the images already there. - Offered elements: Tendre.AI offers ready-to-use elements with a fixed id (for example
officiel-red-beetle, an object). Each one is added once to your list the first time you read it (GET /subjects, MCPtendre_subject_list) and does not count in the capmax. It is then a subject like the others: usable in Multi-Ref (subject_id), editable, deletable; once deleted, it never comes back. - Read:
GET /subjects/{id}; one image:GET /subjects/{id}/images/{n}/file. - Change:
PUT /subjects/{id}withtype,name,descriptionand/orimages_b64(the full list, which replaces the images). - Delete:
DELETE /subjects/{id}, here and in the app.
A style gives a clip its look: its description says the technique, in English (loose watercolor painting on textured paper), not what its images show. An outfit is a garment worn by a character. Styles and outfits only play in Multi-Ref Video, in Ultra.
To cast a subject in a clip, see Multi-Ref Video; in an image, see Create an image.
Generate a subject without images
No image at hand? POST /subjects/generate (permission images) makes the subject the way the "Generate" window of the app's Elements does: a start image drawn from your description (or imported), then views that start from it (other angles, a close-up, at night...), each retouched from the start image to keep the same shape. The result is an ordinary subject: it plays in Multi-Ref Video and in Create an image, and it shows in the app's Library.
| Field | Type | What it does |
|---|---|---|
type | object, location, animal, style or outfit | What the subject is (a motion is not generated) |
name | one word, 1 to 40 letters, digits or _ | The word written after @ in the prompt |
description | English text, 300 characters at most | The element alone: shape, materials, colours, details, with no background or character (a glossy white futuristic tram with round windows). Required unless prompt or start_image_b64 is given |
prompt | English text, 2,000 characters at most, optional | The full text of the start image, instead of the automatic text drawn from description |
start_image_b64 | base64 image, optional | An imported start image (at least 512 px), kept as it is and free |
views | list of keys, optional | The views you want, in order (table below) |
count | 1 to 6, optional | Instead of views: the number of images in all, start included (the first views of the table) |
seed | integer, optional | Seed of the start image |
quote_only | true | Only returns the price, nothing is created |
Views by type (stable keys), in the output format of the type:
type | Format | views |
|---|---|---|
object | 1024 × 1024 | three_quarter, side, back, top, detail (close-up) |
location | 1216 × 832 | reverse_shot, side, high_angle, night, detail (close-up) |
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 (close-up) |
Price: each rendered image (the start and each view) costs the price of one image (1 credit); an imported start is free, and a failed image is not charged. 6 images at most per subject, start included. The answer, 202, is the subject with cost_estimate and 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"]
}Follow it with GET /subjects/{id} until generation.status is no longer pending (ready, partial or failed); n is the number of the image in images. The images go one at a time: the start, then the views in order. A failure stops the series: the next views turn failed, with no charge.
- Add views:
POST /subjects/{id}/viewswithviews(keys not done yet). With one view,instructions(English, 1,000 characters at most) replaces its brief: say what the view must show. - Redo a view:
POST /subjects/{id}/views/{key}/redo, withinstructionsif needed. The view starts again from the start image and replaces the previous one (samen). - Redo the start:
POST /subjects/{id}/views/start/redo, only while no view starts from it (views_existotherwise); an imported start cannot be redone. Views stopped by a failed start go again after it. quote_only: truegives the price on all three routes. One series at a time per subject (subject_busy).
From start to finish, an object with two views:
POST /pro/v1/subjects/generate
{ "type": "object", "name": "Tram", "description": "a glossy white futuristic tram with round windows", "views": ["three_quarter", "detail"] }The answer, 202, gives the subject_id with generation.status pending. Poll GET /subjects/{id} every few seconds until it is ready, then cast @Tram with that subject_id. Three images (the start and two views), so three times the price of one image.
Storage
The character views and the subject images are encrypted (one key per file) and tied to your
licence. Subject images are kept as you sent them, and shared with the app's Library. Caps with the
Pro licence: 50 characters, the app's included, and 50 subjects (locations, objects, animals, styles and outfits together), counted
separately (10 with a personal licence, in the app). A character or a subject left unused for one year
is erased (expires_at): every Multi-Ref render, every Face swap and every read of a view or an image
pushes the date back. The photo you send to create a character is kept as the view of its role, encrypted, like the
generated views. You can delete any of them at any time.
Through an agent (MCP)
With the MCP server, you just ask: "make a character from this photo". The agent
uses tendre_character_create (the photo comes through an upload link, a file attached in ChatGPT,
an image rendered in the conversation or a public address), shows you the seven views, and redoes a
failed one with tendre_character_redo_view, with an instruction when the view needs guiding, or
replaces it with your own image through tendre_character_set_view. tendre_character_get,
tendre_character_list and tendre_character_delete cover the rest, and tendre_quote gives the
price first.
For a location, an object or an animal, give the agent your images and say what it is: it uses
tendre_subject_create, then tendre_subject_list, tendre_subject_get and tendre_subject_delete. With no images, it uses tendre_subject_generate, then tendre_subject_add_views and tendre_subject_redo_view to add or redo a view.
Then cast the character: see Multi-Ref Video.