Skip to main content
POST
/
v1
/
characters
Create a character
curl --request POST \
  --url https://api.alakazam.gg/v1/characters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "world": {},
  "name": "<string>",
  "authored": true,
  "premise": "<string>",
  "frame_b64": "<string>",
  "frame_url": "<string>",
  "cover": "<string>",
  "subject": "<string>",
  "style": "<string>",
  "persona": "<string>",
  "scene": "<string>",
  "greeting": "<string>",
  "lore": "<string>",
  "examples": "<string>",
  "stances": [
    {
      "id": "<string>",
      "label": "<string>",
      "mood": "<string>",
      "expression": "<string>"
    }
  ],
  "voiceId": "<string>",
  "modelId": "<string>",
  "free": true,
  "intro": {
    "kicker": "<string>",
    "title": "<string>",
    "hint": "<string>"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "slug": "<string>",
  "kind": "character",
  "cover": "<string>",
  "schemaVersion": "1.0"
}

Authorizations

Authorization
string
header
required

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

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.

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"