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 APIMCP Server15 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.

Quick Start

Generate your first cover with 4 API calls and the bare minimum data. Grab your API key from the Authentication section, then run the commands below.

Create a book — only title, author, and genre are required.
Generate a cover — pass the bookId. Returns a job ID.
Poll the job until status is completed.
Download the cover from the asset download endpoint.

End-to-end minimum (curl)

# 1. Create a book (only title, author, genre required)
curl -X POST https://beyourcover.com/api/v1/books \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Novel","author":"Jane Doe","genre":"fantasy"}'
# -> { "bookId": "uuid", ... }

# 2. Generate a cover (only bookId required)
curl -X POST https://beyourcover.com/api/v1/covers/generate \
  -H "Authorization: Bearer byc_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"bookId":"<bookId>"}'
# -> { "jobId": "uuid", "poll_url": "/api/v1/jobs/uuid", ... }

# 3. Poll until status === "completed"
curl https://beyourcover.com/api/v1/jobs/<jobId> \
  -H "Authorization: Bearer byc_sk_your_key"
# -> { "status": "completed", "result": { "covers": [{ "coverId": "uuid", ... }] } }

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

Tip: Adding a summary to the book dramatically improves cover quality — the AI uses it to pick imagery and color. See the full endpoint reference for count, templates, mood, webhooks, and more.

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	150	5
Growth	500	10
Scale	1,500	20

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

MCP Server (for AI agents)

BeYourCover ships a remote Model Context Protocol server, so AI agents (Claude, and any MCP-capable client) can generate covers through the same partner pipeline as the REST API — spending the same credits. It's served over Streamable HTTP at https://beyourcover.com/api/mcp/mcp and supports two ways to authenticate.

Option A — API key (Claude Code, scripts, bridges)

Fastest for developers. Uses the same byc_sk_ key as the REST API in an Authorization: Bearer header.

Claude Code (one line)

claude mcp add --transport http beyourcover \
  https://beyourcover.com/api/mcp/mcp \
  --header "Authorization: Bearer byc_sk_your_api_key_here"

For a client that only accepts a URL (e.g. Claude Desktop's config file), bridge to it with mcp-remote, passing the key as a header:

claude_desktop_config.json (mcp-remote bridge)

{
  "mcpServers": {
    "beyourcover": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://beyourcover.com/api/mcp/mcp",
        "--header", "Authorization:${BYC_AUTH}"
      ],
      "env": { "BYC_AUTH": "Bearer byc_sk_your_api_key_here" }
    }
  }
}

Option B — OAuth (Claude Desktop & claude.ai connectors)

For a one-click “Add custom connector” experience with no config files or keys to paste. Add the server URL in your client's connector settings and it walks you through the standard OAuth sign-in:

Add custom connector

Connector URL:  https://beyourcover.com/api/mcp/mcp

The client discovers our authorization server (via /.well-known/oauth-protected-resource), registers itself, and sends you to a BeYourCover sign-in + approval screen. On approval it receives a scoped token tied to your subscription — no byc_sk_ key required. Authorization uses the OAuth 2.1 authorization-code flow with PKCE; you can revoke a connected client anytime from your dashboard.

The server exposes 10 task-shaped tools (not a 1:1 REST mirror): create_book_and_generate_covers, get_generation_status, list_templates_for_genre, get_credit_balance, list_books, download_cover, upscale_cover (free), edit_cover, create_audiobook_cover and calculate_kdp_wrap (the wrap calculator is free and uses no credits). Covers are returned as short-lived signed URLs, never inline image data.

Generation is asynchronous: the create tool returns a jobId that agents poll with get_generation_status. Genre coverage matches the REST API — see Genres & Subgenres or call GET /api/v1/capabilities.

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. *Optional when `genre` is `planner-journal` — planner covers typically lead with a brand wordmark and omit the author.
`genre`	required	—	Genre slug — see Genres section
`subtitle`	optional	300	Book subtitle
`subgenre`	optional	100	Subgenre (kebab-case — see Genres section). For genres that use subgenres, omitting this auto-detects one from your title and summary; an explicit value always wins.
`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
`planner_year`	optional	—	Free-form year label rendered prominently on the cover (typically foil-stamped). Only relevant when `genre` is `planner-journal`. Any string is accepted — e.g. `2026`, `2026-2027`, `FY26`.

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.

Planner & Journal covers: When genre is planner-journal, the author field becomes optional (most planners lead with a brand wordmark and have no author). Use title for the brand/wordmark, subtitle for the tagline, and planner_year for a prominent foil-stamped year on the cover.

Subgenre auto-detection: For genres that use subgenres (Romance, Fantasy, Thriller, Mystery, Science Fiction, Horror, Contemporary Fiction, Biography & Memoir, Planner & Journal, Children's), omitting subgenre auto-detects one from your title and summary; the resolved value is returned as subgenre in the response. A few genres (Self-Help, Business, Religion, Health & Fitness, Historical Fiction) need no subgenre at all. An explicit subgenre always takes precedence.

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"
}

Example Request — Planner & Journal (no author)

{
  "title": "The Daily Momentum Planner",
  "subtitle": "Master Your Work Hours and Reclaim Your Time",
  "genre": "planner-journal",
  "subgenre": "productivity",
  "planner_year": "2026",
  "summary": "A weekly planner for entrepreneurs focused on quarterly goal tracking, time blocking, and reflection prompts.",
  "external_ref": "planner-001"
}

Headers (optional)

Idempotency-Key: unique-request-id

Response 201 (or 200 if idempotent duplicate)

{
  "bookId": "uuid",
  "subgenre": null,
  "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, the best template is auto-selected for the book's genre & subgenre. An unrecognized id returns `400 invalid_template_id`.
`prompt`	optional	1500	Free-text prompt or instructions for the cover. Short text is treated as visual elements and enhanced by our AI.
`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.

Supported genres & credit safety: Generation requires the book's genre/subgenre to be supported. If it isn't — e.g. a genre that uses subgenres with none set — the request returns 422 unsupported_genre and no credits are charged. Letting POST /books auto-detect the subgenre avoids this. All synchronous rejections (404, 422, 400) happen before credits are reserved.

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",
        "prompt": "A dark, moody book cover featuring..."
      }
    ]
  },
  "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, any genre slug
?genre=science-fiction
?genre=thriller&subgenre=cozy           // optional; subgenre requires genre
?genre=romance&subgenre=dark-romance
?genre=fantasy&subgenre=romantasy

subgenre uses the kebab-case values from the Genres & Subgenres table (e.g. cozy, dark-romance, epic-fantasy). With genre and subgenre, the response includes that subgenre's templates plus broader genre-level templates, each tagged with a subgenreMatch boolean so you can distinguish bespoke-subgenre templates from generic ones. With genre alone, it returns every template available across that genre's subgenres.

Errors: 400 invalid_genre, 400 invalid_subgenre (lists valid values), 400 missing_genre_for_subgenre (subgenre sent without genre).

Response 200

{
  "templates": [
    {
      "id": "v2-thriller-bigtype-house",
      "name": "Big Type Over House",
      "family": "thriller-bigtype-house",
      "templateType": "photographic",
      "genreBuckets": ["Thriller & Mystery:domestic", "Thriller & Mystery:psychological", "Thriller & Mystery:rural"],
      "previewImage": "https://images.beyourcover.com/style-previews/v2/thriller-bigtype-house.png",
      "subgenreMatch": true    // only present when subgenre is in the query
    }
  ],
  "total": 135
}

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"
    }
  ]
}

Agent endpoints (account & discovery)

Read-only helpers so agents and integrations can inspect account state without side effects. All require authentication, consume no credits, and use the standard error envelope. List endpoints return newest-first with opaque cursor pagination: pass the returned next_cursor back as ?cursor= to fetch the next page (null means no more results).

GET/api/v1/credits

Current credit balance, plan tier, and concurrency limit for the authenticated subscription. Check this before large batches. Insufficient-credit errors on generation also carry error.details (balance, required, billing_url).

Response 200

{
  "tier": "growth",
  "credits_remaining": 120,   // unused monthly credits
  "credits_monthly": 500,     // monthly allowance at renewal
  "overage_credits": 30,      // purchased overage
  "total_available": 150,     // credits_remaining + overage_credits
  "concurrent_limit": 10,     // max queued/processing jobs at once
  "is_active": true,
  "billing_url": "https://beyourcover.com/enterprise-dashboard"
}

GET/api/v1/capabilities

Machine-readable generation coverage and pricing. The genres array reports, per genre and subgenre, exactly what the generator will accept — a request for an unsupported pair returns 422 unsupported_genre. The coverage is derived from the same routing logic the generate endpoint uses, so it never over-promises.

Response 200 (abridged)

{
  "api_version": "v1",
  "generation_engine": "v2",
  "genres": [
    {
      "genre": "Romance",
      "slug": "romance",
      "supported": true,
      "subgenre_auto_detected": true,   // detected from title/summary if omitted
      "subgenres": [
        { "value": "contemporary", "label": "Contemporary Romance", "supported": true },
        { "value": "romantasy",    "label": "Romantasy",            "supported": true }
      ]
    },
    { "genre": "Poetry", "slug": "poetry", "supported": false, "subgenre_auto_detected": false, "subgenres": [] }
  ],
  "operations": {
    "generate":        { "credits_per_image": 1, "description": "..." },
    "variation":       { "credits_per_image": 1, "description": "..." },
    "edit_image":      { "credits_per_image": 1, "description": "..." },
    "audiobook_cover": { "credits_per_image": 1, "description": "..." },
    "upscale":         { "credits_per_image": 0, "description": "Free." }
  },
  "limits": { "max_covers_per_generate": 5 },
  "coverage_note": "..."
}

GET/api/v1/jobs

List your jobs, newest first. Result payloads are omitted here — poll GET /api/v1/jobs/:jobId for signed cover URLs. Optional status and operation filters.

Query Parameters

?status=queued|processing|completed|failed   // optional
?operation=generate|variation|edit_image|upscale|audiobook_cover  // optional
?limit=20      // optional, 1–100 (default 20)
?cursor=<opaque>   // optional, from a previous next_cursor

Response 200

{
  "jobs": [
    {
      "jobId": "uuid",
      "status": "completed",
      "operation": "generate",
      "external_ref": "gen-001",
      "credits_used": 2,
      "bookId": "uuid",
      "error": null,
      "created_at": "...",
      "started_at": "...",
      "completed_at": "...",
      "poll_url": "/api/v1/jobs/uuid"
    }
  ],
  "next_cursor": "eyJjIjoi…"   // null on the last page
}

Errors: 400 invalid_status_filter, 400 invalid_operation_filter, 400 invalid_limit, 400 invalid_cursor.

GET/api/v1/books

List books owned by your account, newest first — so an agent can resume work on an existing book without recreating it. (The POST on this path creates a book.)

Query Parameters

?limit=20          // optional, 1–100 (default 20)
?cursor=<opaque>   // optional, from a previous next_cursor

Response 200

{
  "books": [
    {
      "bookId": "uuid",
      "title": "My Novel",
      "author": "Jane Doe",
      "subtitle": null,
      "genre": "Contemporary Fiction",   // canonical value
      "subgenre": "book-club",
      "summary": "...",
      "target_audience": null,
      "created_at": "..."
    }
  ],
  "next_cursor": null
}

GET/api/v1/books/:bookId/covers

List every cover generated for a book (newest first). Each entry exposes its public coverId plus per-asset availability flags. No signed URLs here — fetch those from GET /api/v1/covers/:coverId or the download endpoint.

Query Parameters

?limit=100   // optional, 1–200 (default 100)

Response 200

{
  "bookId": "uuid",
  "covers": [
    {
      "coverId": "uuid",                  // cover's public_id
      "coverStyle": "v2-thriller-house-bigtype",
      "created_at": "...",
      "assets": {
        "preview":           { "available": true },
        "full":              { "available": true },   // present after upscale
        "audiobook_preview": { "available": false },
        "audiobook_full":    { "available": false }
      }
    }
  ],
  "total": 1
}

Errors: 404 book_not_found (missing or not owned by your key), 400 invalid_limit.

Genres & Subgenres

Use these values for the genre and subgenre fields when creating a book. Genre is required; subgenre is optional — if you omit it for a genre that uses subgenres, one is auto-detected from your title and summary when the book is created (see POST /books). 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
`planner-journal`	Planner & Journal

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
`small-town`	Small Town Romance
`clean-sweet`	Clean & Sweet Romance
`romcom`	Romantic Comedy

fantasy Subgenres

Value	Label
`romantasy`	Romantasy
`epic-fantasy`	Epic & High Fantasy
`dystopian`	Dystopian
`dark-fantasy`	Dark Fantasy & Horror
`cozy-fantasy`	Cozy Fantasy
`grimdark`	Grimdark
`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

thriller Subgenres

Value	Label
`cozy`	Cozy Mystery
`domestic`	Domestic Thriller
`psychological`	Psychological Thriller
`legal`	Legal Thriller
`political`	Political Thriller
`procedural`	Police Procedural
`dark-academia`	Dark Academia Thriller
`rural`	Rural / Small-Town
`true-crime`	True Crime Fiction
`techno`	Techno-Thriller
`espionage`	Espionage / Spy

mystery Subgenres

Value	Label
`cozy`	Cozy Mystery
`domestic`	Domestic Thriller
`psychological`	Psychological Thriller
`legal`	Legal Thriller
`political`	Political Thriller
`procedural`	Police Procedural
`dark-academia`	Dark Academia Thriller
`rural`	Rural / Small-Town
`true-crime`	True Crime Fiction
`techno`	Techno-Thriller
`espionage`	Espionage / Spy

biography & memoir Subgenres

Value	Label
`literary`	Literary Memoir
`historical`	Historical Biography
`inspirational`	Inspirational & Recovery
`cultural`	Cultural & Travel

contemporary fiction Subgenres

Value	Label
`book-club`	Book Club / Upmarket
`womens-fiction`	Women's Fiction
`family-saga`	Family Saga
`humorous`	Humorous & Satirical

historical fiction Subgenres

Value	Label
`historical-fiction`	Historical Fiction

planner & journal Subgenres

Value	Label
`productivity`	Productivity & Business
`wellness`	Wellness & Gratitude
`budget`	Budget & Finance
`fitness`	Fitness & Health
`minimalist`	Minimalist Notebook
`feminine`	Feminine Lifestyle
`faith`	Faith & Christian
`goal-setting`	Goal-Setting & Vision

science fiction Subgenres

Value	Label
`space-opera`	Space Opera
`dystopian`	Dystopian / Post-Apocalyptic
`hard-sf`	Hard Sci-Fi
`litrpg`	LitRPG / Progression
`cyberpunk`	Cyberpunk / Cli-Fi

horror Subgenres

Value	Label
`gothic`	Gothic Horror
`cosmic`	Cosmic / Lovecraftian
`supernatural`	Supernatural / Ghost Story
`slasher`	Slasher / Splatterpunk
`psychological`	Psychological Horror
`folk`	Folk Horror
`body`	Body Horror
`dark-fantasy`	Dark Fantasy Horror

self-help & personal development Subgenres

Value	Label
`self-help`	Self-Help

business & economics Subgenres

Value	Label
`business`	Business

religion & spirituality Subgenres

Value	Label
`religion`	Religion & Spirituality

health & fitness Subgenres

Value	Label
`health-fitness`	Health & Fitness

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",
        "prompt": "A dark, moody book cover featuring..."
      }
    ]
  }
}

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",
        "prompt": "A dark, moody book cover featuring..."
      }
    ]
  }
}

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	`invalid_template_id`	templateId is not a valid template — see GET /templates
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
422	`unsupported_genre`	The book's genre/subgenre is not supported for generation (e.g. a genre that uses subgenres with none set). No credits are charged.
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 $79/month for 150 credits (Starter), with Growth ($199/mo, 500 credits) and Scale ($399/mo, 1,500 credits) tiers available. Each cover generation, edit, variation, or audiobook cover costs 1 credit per image; upscales are free. 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 15 endpoints, webhooks, and includes a complete curl example.

Can AI agents like Claude use the API?

Yes. BeYourCover runs a remote MCP (Model Context Protocol) server at https://beyourcover.com/api/mcp/mcp over Streamable HTTP, authenticated with the same Bearer API keys. It exposes task-shaped tools for creating books, generating covers, polling jobs, checking credits, downloading covers, upscaling to print resolution, editing covers with text instructions, creating audiobook covers, and calculating KDP print-wrap dimensions, so MCP-capable agents can design covers end to end. There is also a machine-readable capabilities endpoint, an OpenAPI 3.1 spec, and an llms.txt.

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 control over the generation pipeline so you can integrate cover generation into your own product. You remain responsible for reviewing outputs, rights clearance, and any claims you make to your end users about the final files.

Start Building with the Book Cover API

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

View API Plans Contact Sales