Skip to main content
Every programmable world starts from a prompt. You can create one from a text premise, a seed image, or both. Every request goes to POST /v1/worlds with your secret key; the seed image anchors the world’s opening scene.

​
From a text premise

The simplest path — describe the world and let the API paint its opening frame. 
curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -d '{
    "name": "Coastal Castle",
    "premise": "A grand, ivy-covered castle rises from the shoreline at sunset"
  }'

​
From an image URL

Pass frame_url to open the world on an existing image. The URL must be fetchable by Alakazam’s servers with no cookies, authentication, or referer.
cURL
curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -d '{
    "name": "Atrium",
    "premise": "A sunlit indoor atrium with marble floors and tall glass windows",
    "frame_url": "https://example.com/atrium.jpg"
  }'
If a URL won’t fetch (hotlink protection, a login wall), upload the image inline with frame_b64 instead.

​
From a local image

Send the image inline as base64 with frame_b64 (a data URL or raw base64):
Python
import base64, requests

with open("atrium.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

res = requests.post(
    "https://api.alakazam.gg/v1/worlds",
    headers={"Authorization": "Bearer YOUR_SECRET_KEY"},
    json={
        "name": "Atrium",
        "premise": "A sunlit indoor atrium with marble floors",
        "frame_b64": b64,
    },
)
print(res.json())

​
Retry safely

Set an Idempotency-Key so a network retry never creates — or charges for — a duplicate world: 
curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2f9a1c7e-…' \
  -d '{ "premise": "A neon-lit night market in the rain" }'

​
Generate asynchronously

By default POST /v1/worlds generates inline and returns the world. For long-running or high-volume work, set "async": true to queue a durable job and return immediately — then poll it. The job survives client disconnects and worker restarts. 
# Queue a job
curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "premise": "A neon-lit night market in the rain", "async": true }'
# → 202 { "jobId": "…", "status": "queued" }

# Poll until done
curl 'https://api.alakazam.gg/v1/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'
# → { "status": "succeeded", "worldId": "…", "progress": 1 }
When status is succeeded, worldId points at your new world. A failed job is retried automatically; if it exhausts its attempts it’s marked failed and the reserved quota is refunded.