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

RoleView
1Bust, front, neutral expression
4Full body, front
5Full body, back
6Full body, side profile, the character looks towards the left of the image
7Close-up of the face, front
8Close-up of the outfit, from the chest to the knees
9Close-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.

json
{ "name": "Lea", "kind": "woman", "image_b64": "<the photo>", "photo_role": "bust" }
FieldTypeWhat it does
namestring, 1 to 40 charactersThe character's first name
kindstringwoman, man, or a creature described in English (baby dragon). It sets the pronouns of the instructions, never "they".
image_b64base64The photo: sharp, one person only, at least 1024 px on the long side, 12 MB at most, JPEG, PNG or WebP
photo_rolebust (default) or full_bodyThe photo is a bust (it becomes view 1) or a full-body shot (view 4)
outfitEnglish text, optionalWith 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:

statusMeaning
pendingThe views are being made
readyThe seven views are there
partialSome views are missing or failed
failed, emptyNo usable view
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"
}
  • Check the views before the first render. GET /characters/{id}/views/{role}/file returns 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 without outfit. 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 (otherwise 409 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} with image_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 /characters returns your characters, the app's included, and the cap max.
  • 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.

json
{ "name": "steampunk", "outfit": "brass aviator goggles, long black leather coat", "kind": "woman",
  "views": { "1": "<base64>", "4": "<base64>" } }
FieldTypeWhat it does
namestring, 1 to 40 charactersThe sheet's name
outfitEnglish text, 700 characters at mostThe outfit to put on; required without views
viewsobject, role "1" or "4" to "9": an image in base64Views that are ready, with the same rules as uploading a view
generatetrue (default) or falseGenerate the missing roles, or none
from_sheet_idstring, optionalWithout views: the sheet to start from
kindstringOnly 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 without views. generate: false generates none.
  • Without views: the outfit is put on the character's full-body view (on its bust if it has none; from_sheet_id starts 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_estimate gives 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) in views (409 single_image_sheet).
  • Use the sheet like the others, with ?sheet=<sheet_id>: on GET /characters/{id}, on a view's file, on redo (instruction included) and on PUT of a view. In a Multi-Ref clip, characters[].sheet_id picks 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: false without 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):

json
{ "type": "animal", "name": "Rex", "description": "a small brown dog with a red collar", "images_b64": ["<image 1>", "<image 2>"] }
FieldTypeWhat it does
typelocation, object, animal, style or outfitWhat the subject is
nameone word, 1 to 40 letters, digits or _The word written after @ in the prompt
descriptionEnglish text, 300 characters at most, optionala glossy white futuristic tram with round windows
images_b641 to 6 images in base64JPEG, 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}/images with image_b64 (6 at most).
  • List: GET /subjects (?type=location to filter) returns your subjects, those of the app's Library included (origin app), and the cap max. An app subject whose images are not all synced yet has complete: 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, MCP tendre_subject_list) and does not count in the cap max. 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} with type, name, description and/or images_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.

FieldTypeWhat it does
typeobject, location, animal, style or outfitWhat the subject is (a motion is not generated)
nameone word, 1 to 40 letters, digits or _The word written after @ in the prompt
descriptionEnglish text, 300 characters at mostThe 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
promptEnglish text, 2,000 characters at most, optionalThe full text of the start image, instead of the automatic text drawn from description
start_image_b64base64 image, optionalAn imported start image (at least 512 px), kept as it is and free
viewslist of keys, optionalThe views you want, in order (table below)
count1 to 6, optionalInstead of views: the number of images in all, start included (the first views of the table)
seedinteger, optionalSeed of the start image
quote_onlytrueOnly returns the price, nothing is created

Views by type (stable keys), in the output format of the type:

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

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"]
}

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}/views with views (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, with instructions if needed. The view starts again from the start image and replaces the previous one (same n).
  • Redo the start: POST /subjects/{id}/views/start/redo, only while no view starts from it (views_exist otherwise); an imported start cannot be redone. Views stopped by a failed start go again after it.
  • quote_only: true gives the price on all three routes. One series at a time per subject (subject_busy).

From start to finish, an object with two views:

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

Windows · Mac · Cloud or local

Generate privately. Tonight.

Download tendre.AI for free and generate without limits, privately, on your own GPU.

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

Mac with Apple chip (M1 or later): macOS 13 or later. Intel Mac: macOS 12 or later, everything runs online.

Local image generation on Mac needs an M4 with 24 GB of memory, or an M2 or M3 Pro, Max or Ultra with 24 GB. Below that, everything runs online with credits. Retouching and video run online on Mac for now.

Everything about tendre.AI for Mac

No NVIDIA GPU? Start 100% in the cloud: 5 free images and 1 free video every day. An NVIDIA card (8GB+) unlocks unlimited local generation.