Skip to main content
Every API key is either test or live. A test key runs against a sandbox: the generative endpoints return deterministic, canned responses instead of calling a real GPU or vendor backend. Use it to build and test your integration end-to-end — wiring, error handling, request/response shapes — with zero cost and zero real generation, then swap in a live key to ship.

​
Test vs live keys

Keys come in two modes, chosen when you mint the key (mode on POST /v1/apps/{id}/keys, default test). The prefix tells you which: A key’s mode is fixed at creation. To go from sandbox to production, mint a live key — you don’t “flip” a test key.

​
What a test key returns

The generative endpoints below short-circuit before any backend call and return a shape-faithful mock carrying a "mock": true marker. Responses are otherwise deterministic — a 1×1 placeholder image, canned text — with one exception: a newly created world/character still gets a real, freshly-generated id (and, being private, no slug).
The "mock": true field is the reliable way to detect at runtime that you’re on a test key. Exception: POST /v1/characters/{id}/tts streams a tiny silent audio/mpeg clip (real bytes, so it can flow through your audio path) — being binary, it carries no mock marker in the body. Detect test mode from the key prefix there.
POST /v1/worlds with a compiled world body (import) is not mocked — there’s no GPU to skip. The world is validated and stored verbatim, just namespaced into your test data (see below).

​
Isolation

Test resources live in a separate namespace from live ones:
  • Test worlds and characters are stored mode='test', forced private, and are never given a slug — so they can never appear in a catalog or at a public /?play=… URL.
  • Live reads never see test rows, and test reads never see live rows. A test key calling GET /v1/worlds/{id} on a live world’s id gets 404, and vice versa.
  • Usage counters are tracked per mode, so test traffic never moves your live numbers.

​
Cost & quota

  • Test usage is never billed, and that is permanent. Even after runtime billing is enabled, test-mode session_seconds are excluded.
  • The generative endpoints above consume no daily quota in test mode (they short-circuit before the quota reserve), so they’re effectively uncapped — go ahead and hammer them in CI.
  • The one metered path is session-token minting (POST /v1/sessions/token): it still counts against a separate test-namespace session counter (same default caps), but is never billed.

​
Idempotency across modes

Idempotency-Key is scoped per (app, mode, key value) — test and live keep separate idempotency caches, so reusing the same key value across a test call and a live call on the same app is safe (each replays only within its own mode).

​
Before you ship

  • Swap sk_test_… → sk_live_… (and pk_test_… → pk_live_…). Nothing else in your request code changes.
  • async: true is ignored by test keys (they always return the sync mock, so there’s no job to poll and no webhook fires). Test the async/webhook path with a live key.
  • Re-run your happy path against live once to confirm real covers, real slugs, and real play URLs come back where the mocks had placeholders.
See Concepts → Keys & modes for the key model, and Pricing for how live runtime billing works.