Covers

Generate a cover from reference images (async)

Generates a NEW cover for a book from 1-4 reference images plus art direction. A vision model reads the references and writes a self-contained prompt which the text-to-image chain renders — the image model never receives the reference images, so the output is an original cover in the referenced style, not a derivative. Costs 1 credit. References come from POST /api/v1/uploads (reference_upload_ids) and/or existing covers in the account (reference_cover_ids). Uploads are size-, dimension-, and content-checked, and instructions are moderated, all before the credit is reserved. Covers produced this way have a null coverStyle (they sit outside the template system).

post/api/v1/covers/generate-reference

Request

  • Base URL: https://beyourcover.com
  • URL: https://beyourcover.com/api/v1/covers/generate-reference
  • 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

The book the new cover belongs to.

instructionsstring required

Art direction: what to take from the references and what to change.

reference_upload_idsstring[]

upload_ids from POST /api/v1/uploads. Combined with reference_cover_ids, 1-4 total.

reference_cover_idsstring[]

Public coverIds of existing covers to use as references. Combined with reference_upload_ids, 1-4 total.

external_refstring

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

webhookUrlstring

Optional per-job webhook URL.

Response

Idempotent replay of an existing job with the same Idempotency-Key.

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

Current status of the previously created job.

operation'generate' | 'variation' | 'edit_image' | 'upscale' | 'audiobook_cover' | 'remove_text' | 'generate_reference' | 'wrap' | 'wrap_extend_front' required
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.