# Characters
> Create characters, generate portrait candidates, approve one, and add expressions, poses and motion clips from TypeScript with client.characters.
Source: https://nodaro.ai/docs/developers/sdk/characters
**`client.characters`** scripts everything Character Studio does: it creates and edits characters, generates portrait candidates, approves one as the character's face, and adds expressions, poses, lighting, angles and motion clips. A character keeps its portrait, its asset collections, its reference photos and a caption that describes it, so every later image and video can show the same person. The methods call the [Characters REST API](https://nodaro.ai/docs/developers/api/characters). See [Character Studio](https://nodaro.ai/docs/guides/character-studio) for the editor view.
## Methods
| Method | What it does |
| --- | --- |
| [`list(params?)`](#listparams) | List your characters, a page at a time |
| [`get(id)`](#getid) | Read one character, with its jobs in progress |
| [`create(input)`, `update(id, input)` and `upsert(input)`](#upsertinput-createinput-and-updateid-input) | Create or change a character |
| [`delete(id)`](#deleteid) | Archive a character |
| [`restore(id)`](#restoreid) | Bring an archived character back |
| [`duplicate(id, input?)`](#duplicateid-input) | Copy a character |
| [`usage(id)`](#usageid) | Count the workflows that use a character |
| [`generate(input)`](#generateinput) | Generate portrait candidates |
| [`generateAsset(input)`](#generateassetinput) | Generate an expression, pose, lighting or angle variant |
| [`generateMotion(input)`](#generatemotioninput) | Animate the portrait into a motion clip |
| [`approvePortrait(id, candidateJobId)`](#approveportraitid-candidatejobid) | Make a candidate the character's portrait |
| [`recaption(id)`](#recaptionid) | Write the character's description again |
## Create a character from start to finish
The usual order: create the character, generate portrait candidates, approve one, then add variants on top.
```ts
const client = createClient({
baseUrl: "https://app.nodaro.ai",
auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})
async function waitForJob(jobId: string) {
for (;;) {
const { data } = await client.jobs.getStatus(jobId)
if (data.status === "completed" || data.status === "failed" || data.status === "cancelled") return data
await new Promise((resolve) => setTimeout(resolve, 3_000))
}
}
// 1. Create the character
const { id: characterId } = await client.characters.create({
nodeId: "scripted",
name: "Kira",
description: "Young protagonist with auburn hair",
style: "realistic",
seedPrompt: "Kira portrait, warm natural lighting",
})
// 2. Generate 4 portrait candidates
const { jobIds } = await client.characters.generate({
name: "Kira",
seedPrompt: "Kira portrait, warm natural lighting",
count: 4,
attachToCharacterId: characterId,
})
const results = await Promise.all(jobIds.map(waitForJob))
const firstDone = jobIds[results.findIndex((r) => r.status === "completed")]
// 3. Approve one candidate as the portrait
const { portraitUrl, canonicalDescription } = await client.characters.approvePortrait(characterId, firstDone)
// 4. Add a smile
await client.characters.generateAsset({
name: "Kira",
assetType: "expressions",
variant: "smile",
attachToCharacterId: characterId,
attachToColumn: "expressions",
attachName: "smile",
})
// 5. Animate the portrait
await client.characters.generateMotion({
name: "Kira",
motionPrompt: "Slow head turn to the left, soft smile",
provider: "kling",
attachToCharacterId: characterId,
attachName: "head turn",
})
```
Read the character again with `get()` when the jobs finish. It then has a portrait, a smile expression and a motion clip. Wire it into generations with the [Character Asset](https://nodaro.ai/docs/nodes/assets/character) node, or mention it with `@` in a prompt. See [Consistent characters](https://nodaro.ai/docs/guides/consistent-characters).
## client.characters
### list(params?)
Lists your characters, newest first. By default it returns active characters only.
```ts
list(params?: { projectId?: string; archived?: boolean; limit?: number; cursor?: string }): Promise<{
characters: Character[]
nextCursor: string | null
}>
```
One call returns at most `limit` characters, so a single call is not the full list for everyone. Page until `nextCursor` is `null`:
```ts
const all: Character[] = []
let cursor: string | undefined
do {
const page = await client.characters.list({ projectId, cursor })
all.push(...page.characters)
cursor = page.nextCursor ?? undefined
} while (cursor)
```
Pass `nextCursor` back as it is, and do not store or parse it. A malformed cursor fails with `validation_error` instead of starting again from the first page.
### get(id)
Reads one character, with three extra lists the studio uses after a reload: `pendingJobs` (variants still generating), `portraitCandidates` (candidates of the current portrait run, with their progress) and `previousCandidates` (earlier candidates).
```ts
get(id: string): Promise
```
```ts
const character = await client.characters.get(characterId)
console.log(character.sourceImageUrl, character.expressions, character.motions)
```
An archived character is still returned by id, so workflow nodes that point at it keep loading. A `Character` has its portrait in `sourceImageUrl`, six asset collections (`expressions`, `poses`, `motions`, `angles`, `bodyAngles` and `lightingVariations`, each a list of `{ name, url }`), `boards`, `voice`, `personality`, `canonicalDescription` and `identityLock`.
### upsert(input), create(input) and update(id, input)
`upsert()` creates a character when `input.id` is absent and updates it when `id` is set. `create()` and `update()` are shortcuts that set `id` for you. An update writes only the fields you send; the others, `name` included, stay as they are.
```ts
upsert(input: UpsertCharacterInput): Promise<{ id: string; name?: string }>
create(input: Omit & { name: string }): Promise<{ id: string; name?: string }>
update(id: string, input: Omit): Promise<{ id: string; name?: string }>
```
', description: "The asset collections, each replaced as a whole." },
boards: { type: 'Array<{ name, url, type?, sourceImages? }>', description: "Reference boards of the character." },
selectedAssetByVariant: { type: 'Record', description: "The chosen take of each variant." },
}}
/>
```ts
const { id } = await client.characters.create({
nodeId: "scripted",
name: "Kira",
description: "Young protagonist with auburn hair",
style: "realistic",
identityLock: "strict",
})
await client.characters.update(id, { baseOutfit: "Green raincoat and boots" })
```
A name that is already in use fails with `409 name_taken`.
### delete(id)
Archives a character. It disappears from `list()` but still loads with `get(id)`. Use `restore()` to bring it back.
```ts
delete(id: string): Promise<{ success: true; archived: true }>
```
```ts
await client.characters.delete(characterId)
```
### restore(id)
Brings an archived character back. When its name is now used by another active character, the server adds `(restored)` to the name and returns the name it used.
```ts
restore(id: string): Promise<{ id: string; name: string }>
```
```ts
const { name } = await client.characters.restore(characterId)
```
### duplicate(id, input?)
Copies a character to a new one whose name ends in `(copy)`. The copy shares the asset URLs of the original until you generate new ones.
```ts
duplicate(id: string, input?: { nodeId?: string; projectId?: string }): Promise<{ id: string; name: string }>
```
```ts
const { id: copyId, name } = await client.characters.duplicate(characterId)
```
### usage(id)
Returns how many workflows use a character, and which ones. The editor shows it before archiving.
```ts
usage(id: string): Promise<{ workflowCount: number; workflows: Array<{ id: string; name: string }> }>
```
```ts
const { workflowCount } = await client.characters.usage(characterId)
```
### generate(input)
Generates portrait candidates (`POST /v1/generate-character`). With `count` above 1, every job is reserved before any starts, so a failure part way through rolls the whole batch back.
```ts
generate(input: GenerateCharacterInput): Promise<{ jobId: string; jobIds: string[] }>
```
```ts
const { jobIds } = await client.characters.generate({
name: "Kira",
seedPrompt: "Kira portrait, warm natural lighting",
count: 4,
attachToCharacterId: characterId,
provider: "gpt-image",
quality: "high", // priced as gpt-image:high
})
```
With `attachToCharacterId` and one candidate, the result becomes the portrait when the job completes. With several candidates, pick one with `approvePortrait()`. `quality` and `resolution` are priced exactly as in [Generate Image](https://nodaro.ai/docs/nodes/image/generate-image), so a 4K or high-quality run reserves more credits. A value the model does not support is ignored, not refused.
### generateAsset(input)
Generates one variant from the character's portrait: an expression, a pose, a lighting setup or an angle. With `attachToCharacterId`, `attachToColumn` and `attachName`, the result is added to that collection of the character when the job completes.
```ts
generateAsset(input: GenerateAssetInput): Promise<{ jobId: string }>
```
```ts
await client.characters.generateAsset({
name: "Kira",
assetType: "expressions",
variant: "smile",
attachToCharacterId: characterId,
attachToColumn: "expressions",
attachName: "smile",
})
```
### generateMotion(input)
Animates the character's portrait into a motion clip, with [Generate Video](https://nodaro.ai/docs/nodes/video/generate-video) in image-to-video mode. With `attachToCharacterId`, the clip is added to the character's `motions`. Without `sourceImageUrl`, the character's portrait is used.
```ts
generateMotion(input: GenerateMotionInput): Promise<{ jobId: string }>
```
```ts
await client.characters.generateMotion({
name: "Kira",
motionPrompt: "Slow head turn to the left, soft smile",
provider: "kling",
attachToCharacterId: characterId,
attachName: "head turn",
})
```
### approvePortrait(id, candidateJobId)
Makes a completed candidate from `generate()` the character's portrait. A vision model then writes the character's description, and the method returns both.
```ts
approvePortrait(id: string, candidateJobId: string): Promise<{ portraitUrl: string; canonicalDescription: string | null }>
```
```ts
const { portraitUrl, canonicalDescription } = await client.characters.approvePortrait(characterId, jobIds[0])
```
`canonicalDescription` is `null` when the description could not be written. The portrait is still set; call `recaption()` to try again.
### recaption(id)
Writes the character's description again from its current portrait.
```ts
recaption(id: string): Promise<{ canonicalDescription: string }>
```
```ts
const { canonicalDescription } = await client.characters.recaption(characterId)
```
Fails with `400 no_portrait` when the character has no portrait, and with a 502 when the vision model fails.
## Frequently asked questions
### How do I create a character with the Nodaro SDK?
Call client.characters.create with a nodeId and a name, then client.characters.generate for portrait candidates, and client.characters.approvePortrait to pick one. The character can then be used in any image or video generation.
### Does generating a character portrait cost credits?
Yes. A portrait costs the same as a Generate Image run on the chosen model. quality and resolution change the price, for example a 4K or high-quality run costs more.
### What happens when I delete a character?
delete archives the character. It disappears from list() but still loads by id, so workflows that use it keep working. restore brings it back.
### What does identityLock do?
It sets how strongly the face is preserved when Nodaro generates the character's expressions, poses and other variants: off, soft or strict. The default is strict.