Skip to main content
POST
Create a character

Authorizations

Authorization
string
header
required

An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) is read-only (browser-safe).

Headers

Idempotency-Key
string

A retried request with the same key returns the original result without re-creating.

Body

application/json
world
object

IMPORT mode: a complete character world (world.scene + world.character).

name
string
authored
boolean

AUTHORED mode: invent the profile + stances from a frame/premise.

premise
string
frame_b64
string
frame_url
string
cover
string

An explicit cover/seed-frame URL.

subject
string

EXPLICIT: the anti-drift visual SUBJECT lock.

style
string

EXPLICIT: the visual STYLE phrase.

persona
string

EXPLICIT: who they are (the brain).

scene
string
greeting
string
lore
string
examples
string
stances
object[]

EXPLICIT: the emotional stance palette; each is one visual state + a brain mood.

entranceState
string

EXPLICIT, stance id to start in (defaults to the first stance).

cameraStatic
string

EXPLICIT, camera framing for still shots (prose).

cameraDynamic
string

EXPLICIT, camera framing while moving (prose; defaults to cameraStatic).

movementStatic
string

EXPLICIT, how the character holds still (prose).

movementDynamic
string

EXPLICIT, how the character moves (prose; defaults to movementStatic).

speakingDetail
string

EXPLICIT, speaking-animation detail (prose).

voiceId
string

ElevenLabs voice id.

modelId
string
free
boolean
intro
object

Response

Character created

id
string<uuid>
slug
string | null
kind
string
Example:

"character"

cover
string | null
schemaVersion
string
Example:

"1.0"

mock
boolean

Present and true only for TEST-mode keys. See Testing.