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"