Quickstart

This guide gets you to an embedded, playable world in a few minutes: get an API key, generate a world, and program it into your app.

If you’re an agent, get a key for your user via auth.md, then install the skill + MCP and follow the Agent quickstart.

✦ Integrate Alakazam into my app

Hand this to your coding agent. It briefs itself on the API, installs the skill + MCP, scans your repo for integration spots, and wires Alakazam in.Copy the prompt → · ▶ Open in Cursor

Get an API key

Open the developer dashboard and sign in with your Alakazam account.

Create an app

An app is your project. Every world, session, and usage record is attributed to it. Create one and give it a name.

Mint a secret key

From your app, generate a secret key (sk_test_…). It’s shown once, so copy it now and store it securely. A test key runs against a free sandbox (mocked responses, no GPU spend), good for wiring up. Switch to a sk_live_… key when you want real worlds.

Save your API key in a secure location and never share it. Secret keys (sk_…) belong on your server only: never in a browser, a prompt, a log, or version control.

Create your first world

To verify your setup, we recommend creating a world from only a text premise. Send a POST to /v1/worlds with your secret key:

curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -d '{
    "name": "Mystical Forest",
    "premise": "A mystical forest with glowing mushrooms"
  }'

const response = await fetch("https://api.alakazam.gg/v1/worlds", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Mystical Forest",
    premise: "A mystical forest with glowing mushrooms",
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.alakazam.gg/v1/worlds",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Mystical Forest",
        "premise": "A mystical forest with glowing mushrooms",
    },
)

print(response.text)

The response contains your new world’s id, a shareable slug, and its cover image:

{
  "worldId": "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
  "slug": "mystical-forest",
  "ok": true,
  "cover": "https://cdn.alakazam.gg/covers/mystical-forest.png",
  "schemaVersion": "1.0"
}

The response above is what a live key returns. A test key (sk_test_…) returns the same shape but with "mock": true, a placeholder cover, and no slug (test worlds are private). It’s a mocked sandbox response with no GPU spend. See Testing before you rely on the values.

A live creation reserves one generation against your daily quota (test-mode creates are free and uncapped). You can check what’s left any time with GET /v1/usage.

Embed it

A world is meant to be played. Embedding is two steps: mint a session token on your server, then boot the world in the browser with the SDK.

Mint a session token (server)

Call /v1/sessions/token with your secret key. Bind it to the player and to the origin you’ll embed on.

const r = await fetch("https://api.alakazam.gg/v1/sessions/token", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    worldId: "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
    playerIdentity: user.id,
    origin: "https://yourgame.com",
  }),
});
const { token } = await r.json(); // send `token` to the browser

import requests

r = requests.post(
    "https://api.alakazam.gg/v1/sessions/token",
    headers={"Authorization": "Bearer YOUR_SECRET_KEY"},
    json={
        "worldId": "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
        "playerIdentity": user_id,
        "origin": "https://yourgame.com",
    },
)
token = r.json()["token"]  # send to the browser

Boot the world (browser)

Install the SDK and mount the world. Pass the session token, never your secret key.

npm install @alakazamworld/embed

import { createEmbed } from "@alakazamworld/embed";

createEmbed({
  container: "#game",
  slug: "mystical-forest",
  token, // the session token from your server
  onEnding: (e) => console.log("ending reached", e),
});

Get started

Agents & SDKs

Engine SDKs

Guides

Resources

✦ Integrate Alakazam into my app

Get an API key

Create your first world

Embed it

Next steps

World generation examples

Embedding

✦ Integrate Alakazam into my app

​Get an API key

​Create your first world

​Embed it

​Next steps

World generation examples

Embedding

Get an API key

Create your first world

Embed it

Next steps