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 by name when the user names a character.
Permission: assets:read. Credits: free.
| Parameter | Type | Notes |
|---|---|---|
search | string | Part of the character's name, not case-sensitive, up to 100 characters. |
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.
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 short LLM run for the description.
| 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 short LLM run.
| 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 nano-banana. |
asset_type | string | For asset: expressions, poses, lighting, headAngles, bodyAngles or custom. angles is an older name for headAngles. |
variant | string | 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.
Frequently asked questions
Related
Character Studio
Consistent characters
Character Asset
Locations
Objects and creatures
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.