| name | kdp-cover-creator |
| description | Generate full-color KDP book cover (front + spine + back) as PDF. Handles both 8.5x11 (portrait) and 8.5x8.5 (square) books with correct aspect ratios. Uses the configured image renderer (from IMAGE_RENDERER in .env) for artwork. Outputs cover PNG + PDF ready for KDP upload. USE WHEN user says 'make cover', 'generate cover', 'create book cover', 'kdp cover', 'tao bia sach', 'cover pdf', 'build cover', 'cover for coloring book'.
|
KDP Cover Creator
Generate a full KDP-compliant book cover (front + spine + back) as both PNG and PDF.
Input
Accept any of these:
- Theme key — looks up plan from
output/{theme_key}/plan.json and theme from config.py
- Plan JSON path — reads book details directly
- Manual details — concept, title, author, page count, page size
Always need:
- Author name (for cover text)
- Theme key (for file paths and config lookup)
Process
Step 1: Read Book Details
Read output/{theme_key}/plan.json to get:
title — for front cover textsubtitle — for front cover text (optional)audience — adults or kids (affects style)page_size — critical: "8.5x11" or "8.5x8.5"cover_prompt — AI prompt for front artworkpage_prompts — count determines spine width
Also check config.py THEMES dict for theme registration.
Step 2: Determine Aspect Ratios
This is critical for correct cover generation.
| Book Size | Front Cover Aspect Ratio | Back Cover Image Ratio | Trim Size |
|---|
| 8.5x11 (portrait) | 3:4 | 3:4 | 8.5" x 11" |
| 8.5x8.5 (square) | 1:1 | 1:1 | 8.5" x 8.5" |
The aspect ratio affects:
- Front artwork generation (AI33
aspect_ratio parameter)
- Back cover sample page thumbnails (must match page shape)
- Overall cover height calculation
Step 3: Generate Front Cover Artwork
Run generate_cover.py with the correct parameters:
python generate_cover.py --theme {theme_key} --author "{author}" --size 8.5x11
python generate_cover.py --theme {theme_key} --author "{author}" --size 8.5x8.5
python generate_cover.py --theme {theme_key} --author "{author}" --size 8.5x11 --renderer ai33
IMPORTANT: Before running, verify that generate_cover.py uses the correct aspect ratio for the book size. The code in generate_front_artwork() must pass the right aspect ratio to the renderer:
- For 8.5x11:
aspect_ratio="3:4"
- For 8.5x8.5:
aspect_ratio="1:1"
If the code hardcodes 3:4, fix it first:
page_size = size if size else config.DEFAULT_PAGE_SIZE
ar = config.PAGE_SIZES[page_size]["ai33_aspect_ratio"]
return _generate_image_ai33(prompt, aspect_ratio=ar)
Step 4: Fix Back Cover for Square Books
For 8.5x8.5 books, the back cover sample page thumbnails must use 1:1 aspect ratio:
In generate_cover.py, the page_ratio variable in the sample pages grid section:
page_dims = config.get_page_dims(size)
page_ratio = page_dims["height_px"] / page_dims["width_px"]
This ensures square books show square thumbnails on the back cover.
Step 5: Cover Dimensions
Cover dimensions are auto-calculated:
Spine width = total_pages × 0.002252" (white paper)
Full width = (2 × trim_width) + spine + (2 × 0.125" bleed)
Full height = trim_height + (2 × 0.125" bleed)
| Book Size | Approx Cover Width (50 pages) | Cover Height |
|---|
| 8.5x11 | ~17.36" | 11.25" |
| 8.5x8.5 | ~17.36" | 8.75" |
KDP can also provide exact dimensions — use --kdp-width and --kdp-height to override.
Old cover is auto-backed-up. Before writing the new cover.png/cover.pdf,
generate_cover.py copies any existing ones to output/{theme_key}/backups/ with a
timestamp — a rebuild never destroys the version that may already be on KDP.
Step 6: Verify Output (KDP Pre-flight)
Check:
output/{theme_key}/cover.png exists and > 500KBoutput/{theme_key}/cover.pdf exists (this is what KDP needs)- Front artwork matches theme and has title text
- Back cover shows sample pages with correct aspect ratio
- For square books: back thumbnails are square, NOT portrait rectangles
- Author name visible on front
- Barcode area clear on back — NO template text in barcode area (triggers rejection)
- Spine text clearance: if spine has text, verify 0.0625" clearance on each side
- Spine text only if 79+ pages — fewer pages = no spine text allowed
- Metadata consistency: title on cover must match title on interior title page
- Text safe zone (#1 cover reject) —
generate_cover.py now auto-runs the safe-zone
checker and writes output/{theme_key}/cover_safe_check.png (green trim line, red
text-safe line at 0.375" inside trim). OPEN it and confirm NO text/badge/author crosses
the RED line (decorative art crossing it is fine). Re-run any time with
python scripts/check_cover_safezone.py {theme_key}. If text crosses, regenerate the front
so all text sits in the central ~75% of the panel.
Output
COVER GENERATED!
Cover PNG: output/{theme_key}/cover.png
Cover PDF: output/{theme_key}/cover.pdf ← Upload this to KDP
Dimensions: {width}px × {height}px ({full_width}" × {full_height}")
Spine: {spine_width}" ({total_pages} pages)
Page size: {page_size}
Aspect ratios: front={ar}, back thumbnails={ar}
Code Fixes Required
Before running for the first time, apply these fixes to generate_cover.py:
Fix 1: Front artwork aspect ratio (line ~199)
The generate_front_artwork() function needs a size parameter:
def generate_front_artwork(theme: str, title: str = "", renderer: str = "gemini", size: str = config.DEFAULT_PAGE_SIZE) -> Image.Image | None:
And use it for AI33:
if renderer == "ai33":
ar = config.PAGE_SIZES[size]["ai33_aspect_ratio"]
return _generate_image_ai33(prompt, aspect_ratio=ar)
Fix 2: Back cover thumbnail ratio (line ~584)
Replace hardcoded ratio:
page_ratio = 3300 / 2550
page_dims_for_ratio = config.get_page_dims(size)
page_ratio = page_dims_for_ratio["height_px"] / page_dims_for_ratio["width_px"]
Fix 3: Pass size to generate_front_artwork (line ~406)
artwork = generate_front_artwork(theme, title, renderer=renderer)
artwork = generate_front_artwork(theme, title, renderer=renderer, size=size)
Quality Checklist
