# Characters

> Create characters from an AI assistant, generate and approve their portraits, add expressions, poses, angles and motion clips, and reuse them as references.

Source: https://nodaro.ai/docs/mcp/tools/characters

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](https://nodaro.ai/docs/guides/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`](https://nodaro.ai/docs/mcp/tools/image#generate_image) or [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#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

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