Covers

Generate covers for a book (async)

Queues an asynchronous cover-generation job through the V2 engine and returns 202 immediately. Costs count credits (reserved up-front; unused credits for partially/fully failed generations are refunded). Every genre is supported; a book in a genre that uses subgenres but has none set gets one before its first render, as in the app: the detected subgenre at confidence 50 or higher, else the genre's default (stored on the book). 422 unsupported_genre remains as a safety net for a genre/subgenre with no route. Note: unlike the other job-creating endpoints, the fresh 202 envelope from this endpoint does NOT include an operation field (the idempotent 200 replay does).

post/api/v1/covers/generate

Request

Base URL: https://beyourcover.com
URL: https://beyourcover.com/api/v1/covers/generate
Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional idempotency key. If a resource/job was already created with the same key (scoped to the API key for jobs, to the user for books), the endpoint returns 200 with the existing resource instead of creating a duplicate. Concurrent duplicates are also collapsed via a unique-constraint retry.

Request body

bookIdstring uuid required

ID of a book previously created via POST /api/v1/books. Must belong to the API key owner.

countinteger

Number of covers to generate (1-5). Each cover costs 1 credit.

templateIdstring

Optional. Pin a specific V2 template. Must be a valid V2 template id (see GET /api/v1/templates); unknown ids return invalid_template_id.

promptstring

Optional. With prompt_mode: "note" (default, up to 1500 characters) it is a refinement note merged into the template's prompt (internally mainElements). With prompt_mode: "verbatim" (up to 6000 characters) it is the whole cover prompt, rendered as written.

prompt_mode'note' | 'verbatim'

How prompt is used. note: merged into a template prompt. verbatim: rendered exactly as written with no template, like the app's Prompt mode; prompt is then required, and templateId, variant_overrides, motif_id, colorPalette and mood are refused with prompt_mode_conflict.

variant_overridesobject

Optional style choices for the pinned templateId, as axis → option (e.g. {"titleColor": "bone-white"}). The axes and options are the template's variants from GET /api/v1/templates; an axis left out (or set to null) is picked by the engine. Requires templateId (variant_overrides_requires_template); an unknown axis or option returns invalid_variant_axis or invalid_variant_value.

motif_idstring

Optional motif id from GET /api/v1/books/{bookId}/motifs: the story object or symbol the cover shows. Applies to templates that render a motif. Not this book's → 404 motif_not_found; a pinned template that renders no motif → 400 motif_not_used.

Optional. Must be one of the predefined palettes (custom is not accepted via the API).

Optional. Must be one of the predefined mood values.

external_refstring

Optional caller-supplied reference, stored on the job and echoed in responses and webhooks.

webhookUrlstring

Optional per-job webhook URL. Overrides the API key's default webhook URL for this job.

Response

Idempotent replay: a job with the same Idempotency-Key already exists for this API key. Includes operation.

jobIdstring uuid required

status'queued' | 'processing' | 'completed' | 'failed' required

Current status of the previously created job.

credits_reservedinteger

What the ORIGINAL job reserved. Returned by the variations, edit-image, upscale, audiobook-cover, remove-text, wraps and extend-front endpoints when the job recorded it.

included_formatboolean

true when the book's marketing kit paid for the ORIGINAL job instead of credits. Returned by the edit-image, upscale, audiobook-cover, remove-text, wraps and extend-front endpoints.

external_refstring nullable required

The external_ref stored on the ORIGINAL job.

created_atstring date-time required

poll_urlstring required

Changes

No recorded changes to this operation across all 1 revision of this API.