Skip to main content
POST
Create a campaign (multi-chapter book → game)

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

Idempotency-Key
string

A retried request with the same key returns the original { jobId, campaignId } without starting a second campaign. Keyed per (app, mode, key value) in its own campaign: namespace.

Body

application/json
text
string
required

The book (or a long excerpt) to adapt, as plain text. Required, must be a non-empty string, capped at 200000 characters. A non-string, empty/whitespace-only, or over-cap value → 400.

Maximum string length: 200000
name
string

Optional campaign title; defaults to a title distilled from the book bible.

fidelity
enum<string>
default:faithful

How closely the chapters track the source text — faithful (hew to the book's events and settings) or spirit (keep the tone/premise, invent freely). Defaults to faithful.

Available options:
faithful,
spirit
target_acts
integer

Optional TARGET for how many chapters to author — the story planner aims for it but may author more or fewer (within 2..12) to fit the book's natural act breaks, so treat it as guidance, not a guarantee. If present it must be an integer in 2..12 (else 400); omitted, the spine picks a count. Chapter count is hard-capped at 12 to bound cost.

Required range: 2 <= x <= 12
subject_ref
object

Optional canonical-character reference carried into EVERY chapter's seed (the PIXEL subject lock, applied book-wide). Omit it and the server auto-paints one protagonist reference from the bible and carries that instead. Normalized before anything is persisted: an image_b64 is hosted to a durable URL; a data: URI passed as image_url is rejected (400) — host it first or send it as image_b64.

Response

Campaign created; chapters authoring asynchronously. Poll the job for progress and the campaign for chapters. (No quota is reserved here — each chapter reserves one generation as the worker authors it, so a daily-quota 402 surfaces on the JOB, not on this call.)

Returned by POST /v1/campaigns (always 202). Generation is asynchronous: the campaign container exists immediately; its chapters are authored by a background job. Poll GET /v1/jobs/{jobId} for progress (actsDone/actsTotal) and GET /v1/campaigns/{id} for the chapters authored so far.

jobId
string
required

The durable book→game job to poll (GET /v1/jobs/{jobId}). A test-mode key returns the sentinel test_mock (no real job).

campaignId
string<uuid>
required

The new campaign's id (GET /v1/campaigns/{id}).

schemaVersion
string
Example:

"1.0"