Skip to main content
POST
Generate the next scene with your character (subjectRef)

Authorizations

Authorization
string
header
required

An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) is read-only (browser-safe).

Headers

If-Match
string

Path Parameters

id
string<uuid>
required

Body

application/json
prose
string
required

The new scene to paint your character into (becomes the "new scene" description).

pin
boolean
default:false

Pin the generated image as the world's entrance seed (a versioned set_entrance write; keeps the current entrance state).

pov
enum<string>

Seed-frame POV. Defaults to third_person_shoulder.

Available options:
first_person,
third_person_shoulder
expectedRev
string

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).

image_url
string
required

Hosted URL of the generated scene seed.

pinned
boolean
required

Whether it was pinned as the world's entrance seed.

schemaVersion
string
required

The contract version — present on every 200 body.

Example:

"1.0"

rev
string

The new world rev — present only when pinned.

detail
string

Present on a graceful fallback (generated but pin skipped/failed).

mock
boolean

Present and true only for TEST-mode keys — a deterministic sandbox response, no real generation.