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.
Authorizations
An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) is read-only (browser-safe).
Headers
Path Parameters
Body
The new scene to paint your character into (becomes the "new scene" description).
Pin the generated image as the world's entrance seed (a versioned set_entrance write; keeps the current entrance state).
Seed-frame POV. Defaults to third_person_shoulder.
first_person, third_person_shoulder Optimistic-concurrency token for the pin write (or send If-Match).
Response
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).
Hosted URL of the generated scene seed.
Whether it was pinned as the world's entrance seed.
The contract version — present on every 200 body.
"1.0"
The new world rev — present only when pinned.
Present on a graceful fallback (generated but pin skipped/failed).
Present and true only for TEST-mode keys — a deterministic sandbox response, no real generation.

