> ## 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. # Generate the next scene with your character (subjectRef) > "Make the next scene/level with the character I defined at the start." Paints a new seed FROM the world's canonical character (`subjectRef`, set at create time via `subject_ref`) plus your scene `prose`. Identity rides on PIXELS — face, build, hair and clothing — so the same character appears across scenes, levels and book chapters (the mechanism the hand-authored Stormcaller tutorial→fight seed does manually). With `pin:true` the result is pinned as the world's entrance seed via a versioned `set_entrance` write. The world MUST carry a `subject_ref` (else `404`). Metered `image` (reserve-before-spend, fail-closed); a pin failure still returns the generated image so a paid render is never lost. ## OpenAPI ````yaml /alakazam-v1.yaml post /v1/worlds/{id}/scenes openapi: 3.0.3 info: title: 'Alakazam: Programmable Worlds API' version: '1.0' description: > **Alakazam is the programmable worlds API.** Generate playable, AI-rendered worlds from a prompt or an image, program their logic, and embed them in your own products and games. A world is *programmable*: a live graph of states and events you generate, then read, edit, fork, drive, and react to through the API. Two surfaces: a **Creation API** (generate, read, manage, fork worlds) and a **Runtime/Embed API** (mint short-lived session tokens your end-users' browsers use to boot an embedded world). **Authentication.** Two schemes. Management endpoints (`/v1/apps*`) use your Supabase user session. Data endpoints use an **API key** issued per app: `pk_…` (publishable, browser-safe, read-only) and `sk_…` (secret, server-only — create/edit worlds and mint session tokens). Embedding a world in a browser uses a short-lived **session token** minted server-side with a secret key (not a publishable key directly). Never ship a secret key to a browser. **Test vs live.** Keys come in `test` and `live` modes — the prefix tells you which (`sk_test_…`/`pk_test_…` vs `sk_live_…`/`pk_live_…`). A **test** key runs against a sandbox: every generative endpoint returns a deterministic mock marked `"mock": true`, with no GPU or vendor spend; test worlds/characters are isolated from live data (forced `private`, never slugged or discoverable); and test usage is **never** billed. See the Testing guide. **Usage, quota & billing.** Every operation is counted against a per-app daily quota, reserved before any GPU spend. Exceeding it returns `402`. The quota is a free abuse guard, not a charge. Billing, when enabled, is **runtime-only**: you pay for `session_seconds` (live play time). Creating worlds and every other operation are free. Test-mode usage is never billed, even after billing is enabled. The API is in developer preview. See Pricing. **Building with an AI coding agent?** Install the skill (`npx skills add -g https://docs.alakazam.gg/skill.md`) and the MCP server (`npx @alakazamworld/mcp`) so your agent knows this API and can call it live. See the Agent quickstart. servers: - url: https://api.alakazam.gg description: Production (placeholder, set to your conjure-service host) security: [] tags: - name: Apps & Keys description: >- Create apps (tenants) and manage API keys. Authenticated with your user session. - name: Worlds description: >- Create, read, manage, and fork SMWorld games. Authenticated with an API key. - name: Graph editing description: > Read and program a world's graph of states (nodes), events (edges), and the entrance, using deterministic CRUD, a batch op vocabulary, a natural-language kernel-agent edit, and the kernel validate/lint gate. Every write is validated fail-closed before it persists. Authenticated with an API key. - name: Versions description: > Snapshot, branch, check out, and diff a world's graph. Versions form a branching tree of full snapshots; a HEAD pointer tracks the working graph. Authenticated with an API key. - name: Characters description: > Create, manage, and talk to characters: a SMWorld subtype that pairs a stance-graph with a "brain" (persona, lore, voice). CRUD is authenticated with an API key. The live talk turn (/say) and voice (/tts) are called from the browser with a short-lived session token. - name: Scenario Studio description: > Author variation/counterfactual plans over an episode or scenario, submit them as durable batches (N verified clips), poll them, and accept/reject each result. Nothing bills at submit — a clip is charged only when accepted; rejected and failed clips never touch the ledger. Authenticated with an API key. - name: Sessions description: Mint short-lived runtime tokens for embedding a world. - name: Usage description: Per-app usage and quota. - name: Webhooks description: >- Register HTTPS endpoints to receive signed server-side event notifications. Managed with your user session. - name: Simulation & Data description: > **Beta — self-hosted runner.** Drive a world headlessly as a training environment (gym) and stream the SNN-controller observation contract: two virtual proximity sensors, collision spikes, object labels, and an optional square RGB camera. The same schema is emitted offline by the dataset exporter (JSONL episodes + train-ready NPZ), so controllers trained on recorded data plug straight into the live loop. paths: /v1/worlds/{id}/scenes: post: tags: - Worlds summary: Generate the next scene with your character (subjectRef) description: > "Make the next scene/level with the character I defined at the start." Paints a new seed FROM the world's canonical character (`subjectRef`, set at create time via `subject_ref`) plus your scene `prose`. Identity rides on PIXELS — face, build, hair and clothing — so the same character appears across scenes, levels and book chapters (the mechanism the hand-authored Stormcaller tutorial→fight seed does manually). With `pin:true` the result is pinned as the world's entrance seed via a versioned `set_entrance` write. The world MUST carry a `subject_ref` (else `404`). Metered `image` (reserve-before-spend, fail-closed); a pin failure still returns the generated image so a paid render is never lost. parameters: - name: id in: path required: true schema: type: string format: uuid - name: If-Match in: header required: false schema: type: string requestBody: required: true content: application/json: schema: type: object required: - prose properties: prose: type: string description: >- The new scene to paint your character into (becomes the "new scene" description). pin: type: boolean default: false description: >- Pin the generated image as the world's entrance seed (a versioned set_entrance write; keeps the current entrance state). pov: type: string enum: - first_person - third_person_shoulder description: Seed-frame POV. Defaults to third_person_shoulder. expectedRev: type: string description: >- Optimistic-concurrency token for the pin write (or send If-Match). responses: '200': description: >- Scene generated (and pinned when pin:true). A graceful pin fallback returns the image with `pinned:false` and a `detail`. `schemaVersion` is present on EVERY 200 body (pinned, plain and the test-mock). content: application/json: schema: type: object required: - image_url - pinned - schemaVersion properties: image_url: type: string description: Hosted URL of the generated scene seed. pinned: type: boolean description: Whether it was pinned as the world's entrance seed. rev: type: string description: The new world rev — present only when pinned. detail: type: string description: >- Present on a graceful fallback (generated but pin skipped/failed). mock: type: boolean description: >- Present and `true` only for TEST-mode keys — a deterministic sandbox response, no real generation. schemaVersion: type: string example: '1.0' description: The contract version — present on every 200 body. '400': description: Missing prose content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Daily image quota exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: API key is missing the required scope for this operation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- World not found, OR the world has no subject_ref to generate a consistent scene from. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: > Concurrent modification during the pin: the world's rev moved under the pin write. The image was STILL generated and charged — it is returned in `image_url` (with `pinned:false`) so the paid render is never lost. Reload the world and retry the pin against the new rev. content: application/json: schema: type: object required: - image_url - pinned - detail - expectedRev properties: image_url: type: string description: >- Hosted URL of the generated scene seed (the paid render — kept even though the pin failed). pinned: type: boolean description: Always `false` on this response — the pin did not land. detail: type: string description: >- Human-readable explanation of the concurrent-modification conflict. expectedRev: type: string description: >- The rev the pin was attempted against. Reload the world and retry with the current rev. '502': description: >- Scene paint/host upstream failure — the image backend errored or the generated render could not be hosted. The image reservation is refunded (no charge for a failed render). content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Quota backend unavailable (fail-closed) content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: Error: type: object properties: detail: type: string description: Human-readable error message. errors: type: array items: type: string description: Field-level validation errors (e.g. on 422 from POST /v1/worlds). schemaVersion: type: string required: - detail securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- An app API key, e.g. `Authorization: Bearer sk_live_…`. Secret (`sk_`) for writes/sessions; publishable (`pk_`) is read-only (browser-safe). ````