Create a campaign (multi-chapter book → game)
Turn a whole book (text) into N linked chapter-worlds — one story spine and one playable world per chapter — through the same book pipeline that POST /v1/worlds {text} runs for a single chapter, extended to segment the book, build a shared story bible + spine, and author each act in order.
Always asynchronous → 202 { jobId, campaignId }. The campaign container is created immediately; 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.
Metering: one generation per chapter, reserved fail-closed right before each chapter is authored (not a flat per-request charge). If a mid-campaign chapter hits the daily quota the job stops with the chapters authored so far intact (partial campaign) and no half-charge; already-authored chapters are never re-charged on a retry.
Character carry. One canonical character reference is carried into EVERY chapter’s seed so the protagonist stays visually identical across the whole book — same face, build, hair and clothing. Provide it as subject_ref (a hosted image_url, or image_b64 which is hosted first); if you omit it the server paints one protagonist reference from the book bible and carries THAT into every chapter. The chosen reference is stamped on each chapter world’s subjectRef, so you can keep generating more scenes for any chapter with POST /v1/worlds/{id}/scenes.
A test-mode key returns a deterministic mock campaign (a canned campaignId + one mock chapter, jobId: "test_mock") with no quota spend and no generation.
Authorizations
An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) is read-only (browser-safe).
Headers
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
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.
200000Optional campaign title; defaults to a title distilled from the book bible.
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.
faithful, spirit 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.
2 <= x <= 12Optional 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.

