> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# World generation examples

> Create a world from a premise, an image URL, or an uploaded frame.

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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.alakazam.gg/v1/worlds", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Coastal Castle",
      premise: "A grand, ivy-covered castle rises from the shoreline at sunset",
    }),
  });
  console.log(await res.json());
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://api.alakazam.gg/v1/worlds",
      headers={"Authorization": "Bearer YOUR_SECRET_KEY"},
      json={
          "name": "Coastal Castle",
          "premise": "A grand, ivy-covered castle rises from the shoreline at sunset",
      },
  )
  print(res.text)
  ```
</CodeGroup>

## 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.

```bash cURL theme={null}
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"
  }'
```

<Note>
  If a URL won't fetch (hotlink protection, a login wall), upload the image
  inline with `frame_b64` instead.
</Note>

## From a local image

Send the image inline as base64 with `frame_b64` (a data URL or raw base64):

```python Python theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
# 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.