Book Cover Generation API

Generate, edit, and download professional AI book covers programmatically. Built for publishers, self-publishing platforms, and developer teams who need automated book cover design at scale.

REST API10 EndpointsWebhook SupportHMAC-SHA256 Signed

Read the Docs View API Plans

Who Uses the Book Cover API?

Self-Publishing Platforms

Offer built-in cover generation to your authors. Integrate with a few API calls and let users create covers without leaving your platform.

Publishing Houses & Agencies

Generate hundreds of cover variations for your catalog. Use bulk generation to A/B test covers and find what converts best.

Author Tools & SaaS Products

Add professional cover design to your writing, formatting, or marketing tool. White-label ready with full control over the generation pipeline.

How It Works

Create a Book

Send title, author, genre, and a summary to POST /books. The summary helps the AI generate relevant imagery.

Generate Covers

Call POST /generate with your book ID. Get up to 5 AI-generated covers per request, delivered via polling or webhooks.

Edit, Upscale & Download

Refine covers with AI edits, create variations, generate audiobook versions, and upscale to high resolution — all through the API.

← Back

API Documentation

Generate book covers programmatically with the BeYourCover REST API.

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the Account Dashboard. Don't have an account yet? Choose an API plan to get started.

Header

Authorization: Bearer byc_sk_your_api_key_here

Rate Limits

Plan	Credits/mo	Concurrent Jobs
Starter	300	5
Growth	500	10
Scale	1,500	20

See full plan details and pricing on the Enterprise Plans page.

Endpoints

POST/api/v1/books

Create a book record. Required before generating covers.

Field	Required	Max	Description
`title`	required	100	Book title
`author`	required	100	Author name
`genre`	required	—	Genre slug — see Genres section
`subtitle`	optional	300	Book subtitle
`subgenre`	optional	100	Subgenre — available for Romance, Fantasy, Children's
`summary`	recommended	1000	Book synopsis — strongly recommended, used by the AI to create relevant imagery
`target_audience`	optional	—	Restricted values: `children`, `middle-grade`, `young-adult`, `new-adult`, `adult`
`external_ref`	optional	200	Your internal ID — echoed back in responses

Tip: Always provide a summary. The AI uses it to select visual metaphors, color palettes, and imagery that match your book. Without it, the cover will be based on title and genre alone, which produces more generic results.

Note: Title, author, and subtitle do not support Arabic or Hindi (Devanagari) scripts. Most other scripts including Latin, CJK, Cyrillic, and accented characters are supported.

Example Request

{
  "title": "Scale Without Limits",
  "author": "Alex Carter",
  "genre": "business-economics",
  "subtitle": "Systems and Strategies for Explosive Business Growth",
  "summary": "A practical guide for entrepreneurs and executives on building scalable systems, creating predictable growth, and leading high-performing organizations in competitive markets.",
  "target_audience": "adult",
  "external_ref": "book-123"
}

Headers (optional)

Idempotency-Key: unique-request-id

Response 201 (or 200 if idempotent duplicate)

{
  "bookId": "uuid",
  "external_ref": "book-123",
  "created_at": "2025-01-15T10:30:00Z"
}

POST/api/v1/covers/generate

Start an async cover generation job. Returns 202 immediately.

Field	Required	Max	Description
`bookId`	required	—	UUID of the book created via POST /api/v1/books
`count`	optional	—	Number of covers to generate. Integer 1–5, default 1. Each cover costs 1 credit.
`templateId`	optional	—	Template ID from GET /templates. If omitted, auto-selected by genre.
`mainElements`	optional	1000	Free-text prompt describing desired visual elements (e.g. "dark forest with glowing runes")
`mood`	optional	—	Restricted values: `intense`, `mysterious`, `romantic`, `intellectual`, `uplifting`, `epic`, `melancholic`
`colorPalette`	optional	—	Restricted values: `monochrome`, `pastel`, `earth`, `muted`, `dark`, `bold`, `warm`, `cool`, `metallic`, `duotone`
`external_ref`	optional	200	Your internal ID — echoed back in responses and webhooks
`webhookUrl`	optional	500	Per-job webhook override. Falls back to the URL configured in your dashboard.

Example Request

{
  "bookId": "550e8400-e29b-41d4-a716-446655440000",
  "count": 3,
  "mood": "intellectual",
  "colorPalette": "muted"
}

Headers (optional)

Idempotency-Key: unique-request-id

Response 202

{
  "jobId": "uuid",
  "status": "queued",
  "operation": "generate",
  "external_ref": "gen-001",
  "created_at": "2025-01-15T10:30:00Z",
  "poll_url": "/api/v1/jobs/uuid"
}

GET/api/v1/jobs/:jobId

Poll job status. Each call returns freshly signed URLs valid for 1 hour. The result shape varies by operation — see each endpoint for details.

Response 200 (completed — generate/variation)

{
  "jobId": "uuid",
  "status": "completed",
  "operation": "generate",
  "external_ref": "gen-001",
  "credits_used": 2,
  "created_at": "...",
  "started_at": "...",
  "completed_at": "...",
  "result": {
    "bookId": "uuid",
    "covers": [
      {
        "coverId": "uuid",
        "signedUrl": "https://...",
        "expiresAt": "2025-01-15T11:30:00.000Z",
        "coverStyle": "template-name"
      }
    ]
  },
  "error": null
}

Important: Signed URLs expire after 1 hour. Download or serve images on your infrastructure before the expiresAt timestamp. You can re-poll the job at any time to get fresh URLs.

GET/api/v1/templates

List available cover templates. Authentication required. No credits are consumed. Use the same genre values from the Genres & Subgenres section to filter.

Query Parameters

?genre=fantasy              // optional, use any genre slug from the list below
?genre=science-fiction
?genre=business-economics

Response 200

{
  "templates": [
    {
      "id": "cinematic-drama",
      "name": "Cinematic Drama",
      "family": "cinematic",
      "templateType": "photo",
      "genreBuckets": ["Fantasy", "SciFi"],
      "previewImage": "https://images.beyourcover.com/previews/...webp"
    }
  ],
  "total": 53
}

GET/api/v1/covers/:coverId

Get cover metadata and asset availability. Returns fresh signed URLs for any available assets as a convenience. For stable retrieval, use GET /.../download. No credit charge.

Param	In	Description
`coverId`	path	UUID of the cover (from generate or variation results)

Response 200

{
  "coverId": "uuid",
  "bookId": "uuid",
  "coverStyle": "cinematic-drama",
  "assets": {
    "preview": {
      "available": true,
      "signedUrl": "https://...",
      "expiresAt": "2025-01-15T11:30:00.000Z"
    },
    "full": {
      "available": false
    },
    "audiobook_preview": {
      "available": false
    },
    "audiobook_full": {
      "available": false
    }
  }
}

Tip: Use this endpoint to inspect which assets exist on a cover and retrieve fresh temporary URLs. For a stable retrieval path, use the asset download endpoint.

Asset types: preview is the standard cover image, full is the upscaled version, audiobook_preview is the square audiobook cover, and audiobook_full is the upscaled audiobook cover.

GET/api/v1/covers/:coverId/assets/:assetType/download

Download a cover asset. Returns a 302 redirect to a signed URL valid for 1 hour. No credit charge.

Param	In	Description
`coverId`	path	UUID of the cover
`assetType`	path	One of: `preview`, `full`, `audiobook_preview`, `audiobook_full`

Example

curl -L https://beyourcover.com/api/v1/covers/<coverId>/assets/preview/download \
  -H "Authorization: Bearer byc_sk_your_key" \
  -o cover.png

POST/api/v1/covers/:coverId/variations

Generate new cover variations using the same prompt and style as the source cover. Async job — returns 202.

Field	Required	Description
`coverId`	path	UUID of the source cover
`count`	optional	Number of variations (1–5, default 1). Each costs 1 credit.
`external_ref`	optional	Your internal ID
`webhookUrl`	optional	Per-job webhook override

Example Request

curl -X POST https://beyourcover.com/api/v1/covers/<coverId>/variations \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"count": 3}'

Headers (optional)

Idempotency-Key: unique-request-id

Response 202

{
  "jobId": "uuid",
  "status": "queued",
  "operation": "variation",
  "external_ref": null,
  "created_at": "2025-01-15T10:30:00Z",
  "poll_url": "/api/v1/jobs/uuid"
}

Job Result (when completed)

{
  "sourceCoverId": "uuid",
  "covers": [
    {
      "coverId": "uuid",
      "signedUrl": "https://...",
      "expiresAt": "2025-01-15T11:30:00.000Z",
      "coverStyle": "cinematic-drama"
    }
  ]
}

POST/api/v1/covers/:coverId/edit-image

Edit a cover image using a text prompt. Creates a modified version of the existing cover. Async job — returns 202. Costs 1 credit.

Field	Required	Max	Description
`coverId`	path	—	UUID of the cover to edit
`prompt`	required	1000	Description of the changes to make (e.g. "make the sky more dramatic")
`external_ref`	optional	—	Your internal ID
`webhookUrl`	optional	—	Per-job webhook override

Example Request

curl -X POST https://beyourcover.com/api/v1/covers/<coverId>/edit-image \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Make the background darker and add more stars"}'

Headers (optional)

Idempotency-Key: unique-request-id

Response 202

{
  "jobId": "uuid",
  "status": "queued",
  "operation": "edit_image",
  "external_ref": null,
  "created_at": "2025-01-15T10:30:00Z",
  "poll_url": "/api/v1/jobs/uuid"
}

Job Result (when completed)

{
  "sourceCoverId": "uuid",
  "covers": [
    {
      "coverId": "uuid",
      "signedUrl": "https://...",
      "expiresAt": "2025-01-15T11:30:00.000Z",
      "coverStyle": "cinematic-drama"
    }
  ]
}

POST/api/v1/covers/:coverId/upscale

Upscale a cover asset to high resolution. Async job — returns 202. Costs 1 credit. Returns 409 if the upscaled version already exists.

Field	Required	Description
`coverId`	path	UUID of the cover
`sourceAsset`	required	Which asset to upscale: `preview` → `full`, or `audiobook_preview` → `audiobook_full`
`external_ref`	optional	Your internal ID
`webhookUrl`	optional	Per-job webhook override

Example Request

curl -X POST https://beyourcover.com/api/v1/covers/<coverId>/upscale \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sourceAsset": "preview"}'

Headers (optional)

Idempotency-Key: unique-request-id

Response 202

{
  "jobId": "uuid",
  "status": "queued",
  "operation": "upscale",
  "external_ref": null,
  "created_at": "2025-01-15T10:30:00Z",
  "poll_url": "/api/v1/jobs/uuid"
}

Job Result (when completed)

{
  "covers": [
    {
      "coverId": "uuid",
      "asset": "full",
      "signedUrl": "https://...",
      "expiresAt": "2025-01-15T11:30:00.000Z"
    }
  ]
}

POST/api/v1/covers/:coverId/audiobook-cover

Generate a square (1:1) audiobook version of a cover. Async job — returns 202. Costs 1 credit. Requires the cover to have a preview image.

Field	Required	Description
`coverId`	path	UUID of the cover
`external_ref`	optional	Your internal ID
`webhookUrl`	optional	Per-job webhook override

Example Request

curl -X POST https://beyourcover.com/api/v1/covers/<coverId>/audiobook-cover \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{}'

Headers (optional)

Idempotency-Key: unique-request-id

Response 202

{
  "jobId": "uuid",
  "status": "queued",
  "operation": "audiobook_cover",
  "external_ref": null,
  "created_at": "2025-01-15T10:30:00Z",
  "poll_url": "/api/v1/jobs/uuid"
}

Job Result (when completed)

{
  "covers": [
    {
      "coverId": "uuid",
      "asset": "audiobook_preview",
      "signedUrl": "https://...",
      "expiresAt": "2025-01-15T11:30:00.000Z"
    }
  ]
}

Genres & Subgenres

Use these values for the genre and subgenre fields when creating a book. Genre is required; subgenre is optional and only available for Romance, Fantasy, and Children's. All genre and subgenre values are case-sensitive and must be sent exactly as shown.

Available Genres

Value (slug)	Description
`business-economics`	Business & Economics
`religion-spirituality`	Religion & Spirituality
`non-fiction`	Non-Fiction
`fantasy`	Fantasy
`romance`	Romance
`thriller`	Thriller
`mystery`	Mystery
`science-fiction`	Science Fiction
`horror`	Horror
`historical-fiction`	Historical Fiction
`health-fitness`	Health & Fitness
`contemporary-fiction`	Contemporary Fiction
`young-adult`	Young Adult
`childrens`	Children's
`self-help`	Self-Help & Personal Development
`biography-memoir`	Biography & Memoir
`poetry`	Poetry

romance Subgenres

Value	Label
`contemporary`	Contemporary Romance
`romantasy`	Romantasy
`new-adult`	New Adult Romance
`dark-romance`	Dark Romance
`sports`	Sports Romance
`romantic-suspense`	Romantic Suspense
`erotic`	Erotic Romance
`paranormal-monster`	Paranormal & Monster Romance
`historical-romance`	Historical Romance

fantasy Subgenres

Value	Label
`romantasy`	Romantasy
`epic-fantasy`	Epic & High Fantasy
`dystopian`	Dystopian
`dark-fantasy`	Dark Fantasy & Horror
`cozy-fantasy`	Cozy Fantasy
`litrpg`	LitRPG & Progression
`dark-academia`	Dark Academia Fantasy
`myth-folklore`	Myth & Folklore Retellings
`contemporary-urban`	Contemporary & Urban Fantasy
`grounded-low`	Grounded & Low Fantasy

children's Subgenres

Value	Label
`picture-book`	Picture Book
`early-reader`	Early Reader
`chapter-book`	Chapter Book
`middle-grade`	Middle Grade
`other`	Other

Example: Book with subgenre

{
  "title": "Crown of Shadows",
  "author": "Elena Blackwood",
  "genre": "fantasy",
  "subgenre": "dark-fantasy",
  "summary": "A disgraced knight seeks redemption..."
}

Webhooks

Configure a webhook URL in your dashboard to receive job completion notifications. You can also override the URL per-job via the webhookUrl field in the generate request. Payloads are signed with HMAC-SHA256.

Webhook Header

X-BYC-Signature: sha256=<hmac_hex_digest>

Verification (Node.js)

import crypto from 'crypto';

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body)
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Webhook Payload (generate / variation)

{
  "event": "job.completed",
  "jobId": "uuid",
  "external_ref": "gen-001",
  "status": "completed",
  "timestamp": "2025-01-15T10:32:00Z",
  "data": {
    "bookId": "uuid",
    "covers": [
      {
        "coverId": "uuid",
        "signedUrl": "https://...",
        "expiresAt": "2025-01-15T11:32:00.000Z",
        "coverStyle": "template-name"
      }
    ]
  }
}

Webhook Payload (edit_image)

{
  "event": "job.completed",
  "jobId": "uuid",
  "status": "completed",
  "timestamp": "2025-01-15T10:32:00Z",
  "data": {
    "sourceCoverId": "uuid",
    "covers": [
      {
        "coverId": "uuid",
        "signedUrl": "https://...",
        "expiresAt": "2025-01-15T11:32:00.000Z",
        "coverStyle": "template-name"
      }
    ]
  }
}

Webhook Payload (upscale / audiobook_cover)

{
  "event": "job.completed",
  "jobId": "uuid",
  "status": "completed",
  "timestamp": "2025-01-15T10:32:00Z",
  "data": {
    "covers": [
      {
        "coverId": "uuid",
        "asset": "full",
        "signedUrl": "https://...",
        "expiresAt": "2025-01-15T11:32:00.000Z"
      }
    ]
  }
}

Important: Webhook image URLs also expire after 1 hour. Download or cache images on your servers as soon as you receive the webhook. If a URL has expired, poll the job endpoint to get a fresh one.

Errors

All errors return a structured JSON object with a code and message.

Error Response Format

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Need 3, have 1 (0 monthly + 1 overage)."
  }
}

Status	Code	Meaning
400	`missing_required_fields`	Required fields are missing from the request body
400	`missing_book_id`	bookId is required for cover generation
400	`invalid_count`	count must be an integer between 1 and 5
400	`invalid_genre`	Genre value not recognized
400	`unsupported_characters`	Text fields contain unsupported characters (Arabic, Hindi)
400	`field_too_long`	One or more fields exceed their maximum length
400	`invalid_field_type`	A field has the wrong type (expected string)
400	`invalid_field_value`	A field value is not in the allowed set (e.g. mood, target_audience)
400	`content_policy_violation`	Content violates the content policy
400	`missing_prompt`	Edit image requires a non-empty prompt
400	`missing_cover_image`	Cover has no preview image (required for edit/audiobook)
400	`invalid_source_asset`	sourceAsset must be "preview" or "audiobook_preview"
401	`unauthorized`	Invalid or missing API key
402	`insufficient_credits`	Not enough credits for this operation
403	`forbidden`	No active enterprise subscription for this key
404	`book_not_found`	Book not found or doesn't belong to your account
404	`cover_not_found`	Cover not found or doesn't belong to your account
404	`asset_not_available`	The requested asset has not been generated yet (download or upscale of a missing asset)
404	`job_not_found`	Job not found or doesn't belong to your account
409	`asset_already_exists`	The upscaled version already exists for this cover
429	`concurrency_limit`	Too many concurrent jobs running
500	`internal_error`	Internal server error

Full Example

End-to-end flow (curl)

# 1. Create a book
curl -X POST https://beyourcover.com/api/v1/books \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: book-001" \
  -d '{"title":"My Novel","author":"Jane","genre":"fantasy"}'

# 2. Generate covers
curl -X POST https://beyourcover.com/api/v1/covers/generate \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-001" \
  -d '{"bookId":"<bookId>","count":3}'

# 3. Poll for results
curl https://beyourcover.com/api/v1/jobs/<jobId> \
  -H "Authorization: Bearer byc_sk_your_key"

# 4. Get cover metadata
curl https://beyourcover.com/api/v1/covers/<coverId> \
  -H "Authorization: Bearer byc_sk_your_key"

# 5. Edit a cover
curl -X POST https://beyourcover.com/api/v1/covers/<coverId>/edit-image \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Make the sky more dramatic"}'

# 6. Upscale to high resolution
curl -X POST https://beyourcover.com/api/v1/covers/<coverId>/upscale \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sourceAsset":"preview"}'

# 7. Download the upscaled image
curl -L https://beyourcover.com/api/v1/covers/<coverId>/assets/full/download \
  -H "Authorization: Bearer byc_sk_your_key" \
  -o cover-hd.png

Frequently Asked Questions

What is the BeYourCover Book Cover Generation API?

The BeYourCover API is a REST API that lets you generate professional AI book covers programmatically. You send book details (title, author, genre, summary) and receive high-quality cover images. It supports generation, editing, variations, upscaling, and audiobook covers.

What programming languages can I use with the API?

The API uses standard REST conventions with JSON payloads, so it works with any language that can make HTTP requests — Python, JavaScript/Node.js, Ruby, PHP, Go, Java, C#, and more. All you need is an HTTP client and your API key.

How does API pricing work?

API plans start at $149/month for 300 credits (Starter), with Growth ($199/mo, 500 credits) and Scale ($399/mo, 1,500 credits) tiers available. Each cover generation, edit, upscale, or audiobook cover costs 1 credit. Overage credits are available on all plans.

Can I generate book covers in bulk?

Yes. The API supports concurrent requests (5–20 depending on your plan) and asynchronous job processing. You can submit multiple generation requests and poll or use webhooks to collect results. This makes it ideal for batch processing entire book catalogs.

What book cover formats and sizes does the API support?

The API generates standard ebook covers (vertical aspect ratio) and square audiobook covers (1:1). You can upscale any cover to high resolution for print-ready quality. Downloads are available as PNG files via signed URLs.

How do I get started with the API?

Sign up for an API plan on the Enterprise Plans page, get your API key from the Account Dashboard, and make your first request. The documentation on this page covers authentication, all 10 endpoints, webhooks, and includes a complete curl example.

Do you support webhooks?

Yes. The API sends HMAC-SHA256 signed webhook events when jobs complete, so you don't need to poll. You can configure a default webhook URL in your dashboard and optionally override it per-job.

Can I use the API for a white-label product?

Yes. The API gives you full control over the generation pipeline. You can integrate cover generation into your own product without exposing the BeYourCover brand to your end users.

Start Building with the Book Cover API

Get your API key and generate your first cover in minutes. Plans start at $149/month with 300 credits.

View API Plans Contact Sales