Skip to main content
In Alakazam, a world is software you generate and then program. This page covers the pieces you work with: worlds, apps and keys, sessions, and how they fit together.

​
Worlds

A world is a programmable, playable graph of states (what the scene is) and events (what the player can do to move between them), rendered live as the player navigates it. You don’t author that graph by hand. You describe a premise and the API generates a complete, valid world. From there it’s yours to program: read it, patch it, fork variants, and react to its events at runtime. Every world returned by the API conforms to a frozen, versioned contract, the SMWorld schema (schemaVersion: "1.0"). New optional fields may be added in minor versions; breaking changes only ever come with a major version, and the previous major stays readable. See the SMWorld schema in the API reference for the full shape.

​
Apps and keys

An app is your project: the tenant every world, session, and usage record belongs to. Each app issues API keys:
  • Publishable (pk_…): safe to expose in a browser, read-only (it can also drive a like button). It cannot mint session tokens, so embedding a world is driven by a session token your server mints with a secret key, not by a pk_ key directly.
  • Secret (sk_…): server-only. Creates and edits worlds and mints session tokens.
Keys come in test and live modes. The prefix tells you which (sk_test_… vs sk_live_…). A test key runs against a free sandbox: generative endpoints return deterministic mocks ("mock": true), test data is isolated from live, and nothing is billed. See Testing.

​
Sessions and the two-token rule

To play an embedded world, the browser needs a credential, but never your secret key. Instead:
  1. Your server calls /v1/sessions/token with the secret key.
  2. You get back a short-lived session token, scoped to one world, one player, and (optionally) one embedding origin.
  3. The browser passes that token to @alakazamworld/embed.
Short token lifetimes are a feature: the SDK can refresh through your server, so each renewal is a re-authorization checkpoint.

​
Idempotency

POST /v1/worlds, POST /v1/characters, and POST /v1/worlds/{id}/edit accept an Idempotency-Key header. A retried request with the same key returns the original result (cached for 24h) instead of generating a second time. Use it whenever a network retry is possible. Keys are scoped per (app, mode, key value), so test and live keep separate idempotency caches. Reusing the same key across modes is safe.

​
Quota and billing

Every operation is reserved before any GPU spend against a per-app daily quota; over it you get 402 and nothing runs. That is a free abuse guard, not a charge. Billing, when enabled, is runtime-only: you pay for session_seconds (live play time), while creating, editing, and everything else are free. Test-mode usage is never billed. Everything is free during the developer preview. Check your balance with GET /v1/usage; see Pricing for the full model.