Skip to main content
POST
/
v1
/
worlds
Create a world
curl --request POST \
  --url https://api.alakazam.gg/v1/worlds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "premise": "<string>",
  "frame_b64": "<string>",
  "frame_url": "<string>",
  "name": "<string>",
  "pov": "third_person_shoulder",
  "async": false
}
'
{
  "worldId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "slug": "<string>",
  "ok": true,
  "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-generating.

Body

application/json
premise
string

A "what if…" pitch. Required if no frame is given.

frame_b64
string

Base64 seed frame (data-URL or raw).

frame_url
string

URL of a seed frame.

name
string
pov
string
default:third_person_shoulder
async
boolean
default:false

Queue a durable job and return 202 with a jobId instead of generating inline. Poll GET /v1/jobs/{jobId}.

Response

World created (sync)

worldId
string<uuid>
slug
string | null
ok
boolean

Whether the kernel author landed clean.

cover
string
schemaVersion
string
Example:

"1.0"