Characters

Personas that bind a voice to tone instructions — every speech generation goes through one

Overview

A character is a persona: one voice plus a written definition of who is speaking and how. When ToneBoard generates speech for a character, it can first rewrite the input text in that persona's tone, then add performance markup the voice engine understands. The same character behaves the same everywhere — the TTS form, live endpoints, the REST API, and MCP tools.

Field	Meaning
`name`	Display name ("Narrator", "Grumpy Shopkeeper")
`projectId`	The project the character belongs to
`voiceId`	The voice it speaks with — internal (Voice Studio) or external (project voice)
`external`	Which kind of voice `voiceId` references: `true` = project voice from a provider, otherwise internal
`characterDefinition`	The persona: personality, speaking style, quirks — used for tone enhancement

Writing a Character Definition

The definition is instructions to the text enhancer, not decoration. When tone enhancement is enabled for a generation, ToneBoard rewrites the input line as this persona would deliver it — word choice, rhythm, interjections — before any audio is made.

Example definition:

Greta, a grumpy dwarven shopkeeper in a fantasy market.
- Blunt, impatient, secretly kind-hearted.
- Short sentences. Frequent sighs. Calls everyone "kid".
- Haggles reflexively; complains about "adventurer prices".
- Never breaks character, never mentions being an AI.

•Write it as instructions about the speaker, not a biography — "short sentences, frequent sighs" changes output; a life story doesn't.
•Name the register: formal, folksy, clipped, theatrical.
•Include don'ts ("never uses slang") — they prevent drift.
•Keep it focused; a paragraph of sharp traits beats a page of lore.

Tone Enhancement and Expression

Two switches control how much processing a line gets before audio generation (configured per live endpoint, and applied in the TTS flows):

Switch	What it does
`changeTone`	Rewrites the input text in the character's voice using the definition. The rewritten text is what appears on screen.
`useSSML`	Adds performance markup for expressive delivery — pauses, emphasis, emotion.

Internal vs. external expression

The markup differs by voice kind, and ToneBoard picks automatically:

•External voices (ElevenLabs, Google) get standard SSML where the provider supports it.
•Internal voices get bracketed expression cues like [sighs], [whispering], [laughs], which the internal engine performs natively. When tone enhancement already ran, the cues are added in the same pass so lines don't get over-tagged.

Creating and Managing Characters

1Go to Characters → New Character; pick the project and a voice, write the definition.
2Test it in the TTS form: generate the same line with tone enhancement on and off to hear the definition working.
3Edit any time — changes apply to future generations immediately.

Deleting is guarded

A character can't be deleted while live endpoints reference it (you'll get the list of blockers), and a voice can't be deleted while characters use it.

API Access

GET/api/v1/characters?projectId={'{id}'}characters:read

GET/api/v1/characters/{'{id}'}characters:read

POST/api/v1/characterscharacters:write

DELETE/api/v1/characters/{'{id}'}characters:write

Create an internal-voice character, then make it speak:

# Create (voiceId is an internal voice; add "external": true for a project voice)
curl -s https://<host>/api/v1/characters \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Greta",
    "projectId": "<projectId>",
    "voiceId": "<internal voice id>",
    "characterDefinition": "Grumpy dwarven shopkeeper. Blunt, impatient, secretly kind."
  }'

# Generate speech as the character (tts:generate scope)
curl -s https://<host>/api/v1/tts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"characterId": "<id from above>", "text": "We are closed. Come back never."}'

MCP tools: list_characters, get_character, create_character, delete_character, and generate_speech — see MCP Server.