Nodaro DocsCharacters
Create characters from an AI assistant, generate and approve their portraits, add expressions, poses, angles and motion clips, and reuse them as references.
The character tools let an assistant build and use the characters in your Character Studio library: people or figures with a locked look that stay the same in every image and video. The assistant creates a character, generates and approves its portrait, adds variants such as expressions, poses, angles and lighting, animates it into motion clips, and passes its pictures as references to other generations. Read Character Studio for the same work in the app.
The character lifecycle
Create the character
create_character saves the name and the identity: description, gender, style, outfit. The character has no portrait yet.
Generate and approve a portrait
generate_character with kind: "main" makes a portrait. Run it until you like one, then pass that job to approve_portrait. The approved portrait anchors the character, and a vision model writes its canonical description.
Add variants
generate_character with kind: "asset" and attach_to_character_id makes expressions, poses, head and body angles and lighting variants from the approved portrait, and saves each one on the character.
Animate and reuse
generate_character_motion turns the character into motion clips. get_character returns every picture and clip, ready to pass as references to generate_image or generate_video.
list_characters
Lists your characters, most recently updated first, with their name, description, portrait, the number of variants of each kind, and their identity text. Archived characters are left out. Without search, it returns only the first page, so search when the user names a character.
Permission: assets:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
search | string | Up to 5 words, up to 200 characters. Every word must appear in the character's name or description, in any case. A blank value means no search. |
limit | integer | From 1 to 100. Default 50. |
Returns: the characters. Call get_character for the picture URLs.
get_character
Returns one character in full: every expression, pose, motion, head angle, body angle and lighting variant with its name and URL, the reference photos, and real-life reference URLs where a variant has them.
Permission: assets:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
id | string | Required. The character id from list_characters. |
Returns: the character, including updatedAt for update_character. An error when the character does not exist or is not yours.
On Nodaro Cloud, the character also carries training: the state of its high-fidelity training, as { status, error, trainedAt, imageCount }. status is one of untrained, queued, training, succeeded, failed or cancelled. Read it to follow a train_character run.
create_character
Creates a character with its identity. It has no portrait yet: generate one with generate_character next.
Permission: assets:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
name | string | Required. The display name, such as Kira, up to 200 characters. It must be unique among your active characters; a duplicate returns name_taken. |
description | string | Who the character is, up to 2,000 characters. |
gender | string | Up to 50 characters. |
style | string | The visual style, such as realistic, anime, 3d-pixar or illustration. |
base_outfit | string | The default clothes, up to 1,000 characters. |
seed_prompt | string | A short prompt that shapes the first portrait, up to 4,000 characters. |
identity_lock | string | How strictly Character Studio keeps the face in generated variants: off (default), soft or strict. |
Returns: the new character's id.
update_character
Changes a character's identity. Only the fields you pass are written.
Permission: assets:write. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
id | string | Required. The character id. |
name, description, gender, style, base_outfit, seed_prompt, identity_lock | As on create_character. | |
expected_updated_at | string | The updatedAt from get_character. The change is refused when the character changed since you read it. |
Returns: a confirmation, or a conflict error when expected_updated_at is out of date.
approve_portrait
Makes a finished generate_character result the character's portrait, and has a vision model describe it to fill the character's canonical description.
Permission: assets:write. Credits: one Claude Sonnet 4.6 vision call for the description, charged for the tokens it used (how LLM calls are charged). The approval is never refused for credits. When your balance is too low for the description, the image is still approved and the description is skipped. Run recaption_character later to write it.
| Parameter | Type | Notes |
|---|---|---|
character_id | string | Required. The character. |
candidate_job_id | string | Required. A completed generate_character job of yours. |
Returns: the portrait URL and the description. When the description fails, the portrait is still set and the description is empty; run recaption_character.
recaption_character
Has the vision model describe the current portrait again, and saves the new canonical description. Use it after a portrait change, or when the description is not right.
Permission: assets:write. Credits: one Claude Sonnet 4.6 vision call, charged for the tokens it used, like the approval's description.
| Parameter | Type | Notes |
|---|---|---|
id | string | Required. The character. |
Returns: the new description. 400 no_portrait when the character has no portrait.
generate_character
Generates a character portrait (kind: "main") or a variant of the character (kind: "asset").
Permission: workflows:execute. Credits: the price of the image model.
| Parameter | Type | Notes |
|---|---|---|
name | string | Required. The character's name. |
kind | string | main (default) for a portrait, or asset for a variant. |
description, gender, style, base_outfit | string | The identity, for a portrait. |
model | string | The image model. Default gpt-image-2. |
asset_type | string | Required for asset: expressions, poses, lighting, headAngles, bodyAngles or custom. angles is an older name for headAngles. |
variant | string | Required for asset: the variant, such as smile or angry for expressions, front, 3/4 left, left profile, right profile, 3/4 right or back for angles, standing or walking for poses, and daylight, night or dramatic for lighting. |
attach_to_character_id | string | Saves the result on this character and uses its approved portrait as the source. Without an approved portrait, the call returns portrait_required. |
attach_to_column | string | Required with attach_to_character_id for a custom variant: where to save it, such as expressions, poses, angles, body_angles, lighting_variations, sheets, detail_closeups, outfit_variations or boards. |
attach_name | string | The name of the saved variant. Default: the variant. |
source_image_url | string | A source picture, when you do not attach to a character. |
Returns: a job id. For a portrait, pass the job to approve_portrait when you like the result.
generate_character_motion
Animates a character into a short motion clip, from one of its pictures.
Permission: workflows:execute. Credits: the price of the video model.
| Parameter | Type | Notes |
|---|---|---|
motion_prompt | string | Required. What moves and how, up to 2,000 characters, for example "slow head turn left, eyes track the camera, soft smile". |
name | string | Required. The character's name. |
attach_to_character_id | string | Picks the source picture from the character and saves the clip in its motions. |
source_image_url | string | A source picture of your choice. Required without attach_to_character_id. |
provider | string | kling (default), kling-turbo, kling-3.0, wan-i2v or wan-2.7-i2v. |
attach_name | string | The name of the saved motion, such as walking. |
description, motion_description, gender, style, base_outfit | string | Optional identity and motion details. |
With attach_to_character_id, the source picture is chosen in this order: your source_image_url, the character's front body angle, any other body angle, then the portrait. A full-body picture moves much better than a head portrait, so generate body angles first.
Returns: a job id. The card plays the clip when it is ready.
train_character
Trains a high-fidelity model of a saved character on the character's own images. A Generate Image node whose prompt @-mentions that one character then keeps the character's identity closely. Read Character training for the same feature in the app.
Permission: workflows:execute and assets:write. Credits: 1,650 per training. Nodaro Cloud only.
| Parameter | Type | Notes |
|---|---|---|
id | string | Required. The character id from list_characters. |
selected_image_urls | array | Train on these images of the character only, at least 4 distinct ones. Default: every eligible image. |
The character needs at least 4 distinct images: its portrait, reference photos, expressions, poses, angles and lighting variations count.
Returns: at once, with jobId, trainingId and triggerWord. The training takes about 15 minutes. Follow it with get_character, in the training field.
- Refusals. The tool answers
already_training_or_not_foundwhile a training of the character is in progress, andinsufficient_training_imageswith fewer than 4 images. - Credits. The credits are refunded when the training fails or is cancelled. Training a trained character again costs the same again.
- Removing a trained model. No MCP tool removes it, because removal destroys a paid training and cannot be undone. Use
DELETE /v1/characters/:id/lora,client.characters.deleteLora(id)in the SDK, ornodaro characters delete-lora <id>in the CLI. See Character training.
Frequently asked questions
How does an assistant create a consistent character in Nodaro?
It calls create_character with a name and a description, generates a portrait with generate_character, and approves the best one with approve_portrait. The approved portrait then anchors every variant and motion clip of the character.
How do I use a saved character in an image or a video?
Find it with list_characters, read its pictures with get_character, and pass the right portrait, expression or pose URL in reference_image_urls of generate_image, image_to_image or generate_video.
Why does a variant fail with portrait_required?
Variants reuse the approved portrait as their source. Generate a portrait with kind main and approve it with approve_portrait first.
Which picture should a motion clip start from?
A full-body picture moves much better than a head portrait. Generate the character's body angles first; generate_character_motion then uses the front body angle automatically.
Can an assistant train a character model through MCP?
Yes, on Nodaro Cloud. train_character trains a high-fidelity model of a saved character with at least 4 distinct images. It costs 1,650 credits, refunded if the training fails or is cancelled.
Related
Character Studio
Character training
Consistent characters
Character Asset
Locations
Last updated on
Music
Create songs and instrumentals with Suno and other music models, then extend, cover, mash up, edit, split and convert them with Nodaro's MCP music tools.
Locations
Create locations from an AI assistant, generate and approve their establishing shots, add time of day, weather and angle variants, and animate atmosphere clips.