Skip to main content
Alakazam turns a text premise or an image into a playable, AI-rendered game world — and lets you program its logic and embed it in any app or game. One API: generate worlds and talk-to characters, edit their state-machine graph, mint runtime sessions, and drop them into a browser (Unity + Unreal SDKs coming). Base URL: https://api.alakazam.gg. Full reference: https://docs.alakazam.gg (raw index for agents: https://docs.alakazam.gg/llms.txt).

​
When to use Alakazam

Reach for this API when the task is any of:
  • “add an AI game / playable world / interactive scene to my app”
  • “generate a level or world from a prompt or a concept image”
  • “embed a talk-to AI character or NPC (with voice)”
  • “let my users create and share their own games” (UGC)
  • “turn this image into an explorable place with clickable hotspots”

​
Authentication — read this first

Two credential types, issued per app:
  • sk_… secret key — server-only. Creates/edits worlds and mints session tokens. Never ship it to a browser.
  • pk_… publishable key — browser-safe, read-only (it can also drive a like button).
Both come in test and live modes — the prefix tells you (sk_test_… / sk_live_…). A test key runs a free, mocked sandbox (see Test sandbox). Send the key as Authorization: Bearer <key>. The API is CORS-open — call it from any origin with a bearer key; it never uses cookies.

​
The two-token rule (the #1 thing to get right)

To play or embed a world in a browser you do not put your API key client-side. Instead:
  1. Your server calls POST /v1/sessions/token with the secret key → a short-lived session token.
  2. The browser hands that session token to the embed SDK, which exchanges it (/v1/sessions/connect) for a runtime stream.

​
The surface

​
Core flows

1 — Create a world. POST /v1/worlds with {"premise": "..."} (or frame_url / frame_b64, or a compiled world to import verbatim). Returns { worldId, slug, cover, schemaVersion }. Long jobs: add {"async": true} → 202 {jobId}, poll GET /v1/jobs/{jobId}. 2 — Embed it (two-token). Server: POST /v1/sessions/token {worldId, origin, playerIdentity} → {token}. Browser: npm i @alakazamworld/embed → createEmbed({ container: "#game", slug, token }). 3 — Talk-to character. POST /v1/characters (import an example, give an explicit persona/stances, or authored:true from a premise) → mint a session token → the browser calls /{id}/say (returns {reply, stance}), /{id}/tts (streams voice), /{id}/image. 4 — Program the graph. Deterministic CRUD on …/states and …/events, a batch …/ops vocabulary, or a natural-language POST /v1/worlds/{id}/edit. Every write is kernel-validated before it persists. 5 — Frame → world (vision). /v1/seed-frame paints an opening frame; /probe//perceive read an image into world structure; /ground/scene//ground/objects return clickable hotspot boxes.

​
Test sandbox (build for free)

A sk_test_… / pk_test_… key returns deterministic mocks — every response carries "mock": true, nothing spends GPU or quota, and test worlds/characters are namespaced private and isolated from live reads. Build and test your whole integration at zero cost, then swap the key to sk_live_…. Details: https://docs.alakazam.gg/testing.

​
Billing

Runtime-only: you pay for session_seconds (live play time); creating, editing, and everything else are free (bounded by a daily quota, not a charge). Free during the developer preview. https://docs.alakazam.gg/pricing.

​
Gotchas (that trip up integrations)

  • Two-token rule — never ship a secret key to a browser; mint a session token server-side.
  • GET /v1/worlds/{id} nests the graph under .world — metadata (id/name/cover/plays/likes/playUrl) is top-level, but entrance/scene/states/events live at world.entrance, etc. The graph-editing routes (…/scene, …/states) return the flat graph instead.
  • Character create returns id (not characterId). /tts streams raw audio/mpeg bytes (not JSON). /image returns {src, generated}.
  • Session tokens are short-lived — refresh through your server, never embed a long-lived credential.
  • Put an Idempotency-Key on POST /v1/worlds, /v1/characters, /v1/worlds/{id}/edit so a retry doesn’t double-create (scoped per app + mode).

​
SDKs & tools

  • MCP server (@alakazamworld/mcp): live agent tools for the whole surface — ALAKAZAM_SECRET_KEY=sk_… npx @alakazamworld/mcp. Setup: https://docs.alakazam.gg/install-mcp.
  • Web embed: @alakazamworld/embed (createEmbed). See https://docs.alakazam.gg/embedding.
  • Unity SDK · Unreal SDK: coming soon.

​
Quick reference

  • Reference & guides: https://docs.alakazam.gg · Quickstart: /quickstart · Testing: /testing · Errors: /errors · Embedding: /embedding
  • Get an API key: https://play.alakazam.gg/?view=developer