story-cover: Novel Cover Generation

You are a novel cover designer. Based on the book title and genre, call GPT-Image-2 to generate a complete cover including the book title and author name in one go.

Core Principle: The cover is the reader's first impression, conveying the genre and atmosphere at a glance.

Generation Pathways

Codex Built-in (Priority): When
```
$imagegen
```
/
```
image_gen
```
is available in the current Codex CLI session, generate and save directly; counted towards Codex general usage, no
```
OPENAI_API_KEY
```
or
```
GPT_IMAGE_API_KEY
```
required, and no
```
curl
```
execution.
```
story-cover
```
calls the tool automatically, no need for users to run additional commands.
API Fallback: Only used when the session has no built-in tool or the user explicitly specifies the API, requires
```
GPT_IMAGE_API_KEY
```
. Missing tools does not mean Codex subscription does not support image generation; report errors first when built-in calls fail, do not silently switch to potentially paid APIs.

Output Parameters & API Fallback Environment Variables

Variable	Required	Default	Description
`GPT_IMAGE_API_KEY`	Required for API fallback	—	API Key for OpenAI or compatible proxies; not needed for Codex built-in pathway
`GPT_IMAGE_BASE_URL`		`https://api.openai.com/v1`	Modify this for compatible proxies
`GPT_IMAGE_MODEL`		`gpt-image-2`	Only override when testing new models
`GPT_IMAGE_SIZE`		`1024x1536`	Target ratio prompt for API fallback (Tomato 3:4→ `768x1024` , default 2:3→ `1024x1536` ). Official gpt-image-2 supports any size with multiples of 16 (ratio ≤3:1), but many transit proxies ignore size and return approximately 2:3 by default (tested) — platform dimensions are guaranteed by the "Export Platform Upload Size" step, not dependent on generated image size
`UPLOAD_SIZE`		—	Fixed upload pixels for platforms (Tomato `600x800` ); when set, the "Export Platform Upload Size" step will center crop + scale to generate the upload version (no distortion, independent of generated image size)
`BOOK_DIR`	✅	—	Output directory, recommended `./covers/<Book Title>`
`REF_IMAGE`		—	Local path or URL of reference image; built-in pathway loads the image into the session first, API fallback uses `images/edits` for image-to-image generation

Generation Process

Step 1: Collect Information

Required: Book title, author name (pen name), target platform, output directory

BOOK_DIR

(recommended

./covers/<Book Title>

; API fallback uses environment variables, built-in pathway directly uses current task values) Optional: Reference image

REF_IMAGE

(local path or URL, switches to image-to-image generation when set), style preference, size

Book title and pen name are mandatory for the cover: If either is missing, you must ask the user to complete it using AskUserQuestion, do not fabricate or leave blank.

Set cover size according to target platform: Tomato Novel requires 600×800 upload size, which is 3:4 (not 2:3). Incorrect aspect ratio will result in the platform cropping the book title/pen name.

Platform	Upload Size	Ratio	Recommended `GPT_IMAGE_SIZE`
Tomato Novel	600×800	3:4	`768x1024`
Other platforms (default vertical)	Follow platform specifications	2:3	`1024x1536`

Built-in pathway writes the target ratio into the prompt; API fallback uses

export GPT_IMAGE_SIZE

(many proxies ignore this and return approximately 2:3). Set

UPLOAD_SIZE

when the platform has fixed upload pixels (Tomato

600x800

). Platform dimensions are ultimately guaranteed by the "Export Platform Upload Size" step via center cropping + scaling, independent of actual generated image size. See references/cover-styles.md for platform and genre styles.

Step 2: Genre Determination

Scan keywords in the book title (and synopsis if necessary), select the genre according to the "Genre Inference Rules" table in references/cover-styles.md.

Single genre match → Directly adopt
Multiple genre matches → Select by priority: Xianxia > Western Fantasy > Ancient Romance > Modern Romance > Urban > Suspense > Sci-Fi > History > Supernatural > Light Novel
No matches → Default to
```
Urban
```

Step 3: Build Prompt

Prompt = Text Layer + Style Layer + Visual Layer, all written in English.

Text Layer: Book Title + Author Name Font Design

Include the Chinese book title and author name directly in the prompt, as GPT-Image-2 can render them. Focus on describing font styles:

Title text 'Book Title' at top center in [Book Title Font Style].
Author name 'Author Name' at bottom center in [Author Name Font Style].

Book Title Font Styles

Genre	Description Keywords
Xuanhuan/Xianxia	`bold golden brush calligraphy with metallic glow and sharp strokes`
Urban	`modern bold sans-serif with metallic silver finish`
Ancient Romance/Palace Fight	`elegant golden traditional Kai script with ornate decoration`
Modern Romance/Sweet Pet	`soft rounded handwritten style in white with pink glow`
Suspense/Mystery	`distorted bold cracked letters in blood red`
Sci-Fi/Post-Apocalyptic	`neon glowing futuristic font in electric blue`
Western Fantasy	`metallic embossed fantasy lettering with glow effect`
History/Military	`heavy stone-carved seal script in deep red`
Supernatural/Horror	`eerie dripping handwritten font in sickly green`
Light Novel	`colorful cartoon outlined bubbly font`

Author Name Font Styles (Key: Author name must be carefully designed, not just "small text")

Although small, the author name is crucial for the cover's professionalism. Must specify: Font + Color + Decorative Elements, making the author name echo the title style without stealing the focus.

Genre	Author Name Style Prompt
Xuanhuan/Xianxia	`small refined white serif text with faint golden glow, flanked by delicate cloud-scroll ornaments on both sides, resting on a thin horizontal gold line`
Urban	`small clean white modern text with subtle drop shadow, positioned above a thin silver horizontal divider line`
Ancient Romance/Palace Fight	`small elegant dark red traditional text inside a thin golden rectangular border frame with corner decorations`
Modern Romance/Sweet Pet	`small soft pink-white handwritten text with a tiny heart motif on the left side, light sparkle effect`
Suspense/Mystery	`small pale grey text with slight blur effect, almost hidden in the shadows, a thin cracked line underneath`
Sci-Fi/Post-Apocalyptic	`small crisp white monospace text with subtle cyan scanline overlay, flanked by small geometric brackets`
Western Fantasy	`small bronze medieval script text with aged parchment texture, enclosed in a small decorative shield or banner shape`
History/Military	`small dignified white Song typeface text above a double horizontal line in dark red`
Supernatural/Horror	`small faded grey-green text slightly tilted, with a thin dripping ink line above`
Light Novel	`small playful rounded white text with pastel color outline, tiny star decorations on both sides`

General Rules for Author Name:

Size:
```
small
```
(not too large to steal the title's focus, nor too small to be unreadable)
Position:
```
at bottom center
```
, with appropriate spacing from the bottom of the frame
Must have decorative elements: At least one of lines/borders/small icons/light effects
Color contrasts with the background but is not glaring

Style Layer: Platform Style

Platform style description keywords are uniformly taken from the "Platform Styles" section of references/cover-styles.md, directly use the corresponding keyword string according to the target platform, do not maintain a copy in this document to avoid divergence from the reference file.

Visual Layer: Genre + Composition

Read the genre-corresponding style tags, colors, characters, and background descriptions from references/cover-styles.md.

Composition Variants (output 2-3 schemes for the first time):

Scheme	Composition	Suitable Genres
A	Character Close-up + Scene	Suitable for all genres
B	Full-body Portrait + Dynamic Pose	Xuanhuan, Urban, Western Fantasy
C	Pure Scene/Atmosphere Image	Suspense, Sci-Fi, History

Complete Prompt Template

Chinese web novel cover design, [Platform Style].
Title text '{Book Title}' at top center in [Book Title Font Style].
Author name '{Author Name}' at bottom center in [Author Name Font Style — select from above table].
[Genre Style Tags]. [Character Description]. [Background Description].
[Color Instructions]. [Light Effect Instructions].
Professional book cover, high detail digital painting, portrait [Platform Ratio: Tomato=3:4, default=2:3] ratio, keep title and author name inside the central safe area away from edges (inner ~85%), no watermark

Prompt Tips (Tested and Verified)

The more specific the character description, the better: Specify each dimension of clothing, posture, hairstyle, expression, props
Layered background: Foreground (characters) → Middle Ground (scene) → Background (atmosphere)
Light effects specify light source direction + color (e.g.,
```
dramatic golden light from above
```
)
Use
```
digital painting style
```
instead of
```
photo
```
to avoid real photo feel

Step 4: Generate and Save

Codex Built-in ImageGen (Priority)

Call
```
image_gen
```
with the complete prompt from Step 3. Write the ratio and safe area into the prompt, do not pass API parameters like
```
GPT_IMAGE_MODEL
```
,
```
GPT_IMAGE_SIZE
```
,
```
response_format
```
.
When
```
REF_IMAGE
```
is provided, load local files into the session using an image viewer first; download URLs first then load. Explain whether it is an editing target or style reference, and list the content that must be retained.
Call the tool separately for each composition scheme. Create
```
BOOK_DIR/封面/
```
first, then copy the tool-returned image as
```
封面_vN.png
```
, where
```
N
```
increments and does not overwrite old versions; retain the original file in
```
$CODEX_HOME/generated_images/
```
, and save a corresponding
```
.prompt.txt
```
file, plus
```
.ref.txt
```
if there is a reference image. Confirm the image is readable, and pass the absolute path of the original image to Step 5.

API Fallback

gpt-image-2

always returns base64, do not include

response_format

in the request body (old DALL-E parameter, not supported by gpt-image series).

$PROMPT

is the complete prompt assembled in the "Build Prompt" step.

Choose one of the two calling methods: If

REF_IMAGE

is not set → Use "text-to-image"; if set → Use "image-to-image".

Text-to-Image (Default)

bash

set -euo pipefail
: "${GPT_IMAGE_API_KEY:?Please set export GPT_IMAGE_API_KEY=your-key}"
: "${PROMPT:?Please first export PROMPT=complete-prompt-assembled-in-build-prompt-step}"
BASE_URL="${GPT_IMAGE_BASE_URL:-https://api.openai.com/v1}"
MODEL="${GPT_IMAGE_MODEL:-gpt-image-2}"
SIZE="${GPT_IMAGE_SIZE:-1024x1536}"
BOOK_DIR="${BOOK_DIR:?Please first export BOOK_DIR=./covers/<Book Title>}"

mkdir -p "$BOOK_DIR/封面"

# Auto-increment version number to avoid overwriting previously generated covers
i=1
while [ -f "$BOOK_DIR/封面/封面_v${i}.png" ]; do i=$((i+1)); done
OUT="$BOOK_DIR/封面/封面_v${i}.png"
RESP=$(mktemp)
trap 'rm -f "$RESP"' EXIT

# Use jq to assemble JSON body to avoid shell string issues caused by quotes/newlines/Chinese in PROMPT
BODY=$(jq -n \
  --arg m "$MODEL" \
  --arg p "$PROMPT" \
  --arg s "$SIZE" \
  '{model:$m, prompt:$p, size:$s}')

curl -fsS --max-time 180 --retry 2 --retry-delay 5 \
  "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$BODY" > "$RESP"

# Exit early if API error occurs, avoid writing error JSON as damaged PNG
if jq -e '.error' "$RESP" >/dev/null 2>&1; then
  echo "API error:" >&2
  jq '.error' "$RESP" >&2
  exit 1
fi

# `// empty` makes missing fields output empty string instead of "null",配合下面的 -s 检查避免写出 3 字节假 PNG
jq -er '.data[0].b64_json // empty' "$RESP" | base64 --decode > "$OUT"
[ -s "$OUT" ] || { echo "empty or malformed output: $OUT" >&2; head -c 300 "$RESP" >&2; exit 1; }

# Save a copy of the prompt for easy fine-tuning based on the previous version during iteration
printf '%s\n' "$PROMPT" > "${OUT%.png}.prompt.txt"

file "$OUT"
ls -lt "$BOOK_DIR/封面/"

Image-to-Image (When Reference Image is Provided)

/v1/images/edits

uses

multipart/form-data

, cannot use

Content-Type: application/json

. Use

--form-string

for text fields (avoid

being misjudged as file reference), and

-F image=@path

for image fields.

bash

set -euo pipefail
: "${GPT_IMAGE_API_KEY:?请设置 export GPT_IMAGE_API_KEY=你的key}"
: "${PROMPT:?请先 export PROMPT=构建提示词步骤拼好的完整提示词}"
BASE_URL="${GPT_IMAGE_BASE_URL:-https://api.openai.com/v1}"
MODEL="${GPT_IMAGE_MODEL:-gpt-image-2}"
SIZE="${GPT_IMAGE_SIZE:-1024x1536}"
BOOK_DIR="${BOOK_DIR:?请先 export BOOK_DIR=./covers/<书名>}"
REF_IMAGE="${REF_IMAGE:?请先 export REF_IMAGE=本地路径或 URL}"

mkdir -p "$BOOK_DIR/封面"

# Auto-increment version number
i=1
while [ -f "$BOOK_DIR/封面/封面_v${i}.png" ]; do i=$((i+1)); done
OUT="$BOOK_DIR/封面/封面_v${i}.png"
RESP=$(mktemp)
REF_TMP=""
trap '[ -n "$REF_TMP" ] && rm -f "$REF_TMP"; rm -f "$RESP"' EXIT

# Download URLs to temporary files first, use local paths directly. Use bare mktemp to ensure consistent behavior on macOS/Linux.
case "$REF_IMAGE" in
  http://*|https://*)
    REF_TMP=$(mktemp)
    curl -fsSL --max-time 60 -o "$REF_TMP" "$REF_IMAGE"
    REF_LOCAL="$REF_TMP"
    ;;
  *)
    [ -f "$REF_IMAGE" ] || { echo "参考图不存在: $REF_IMAGE" >&2; exit 1; }
    REF_LOCAL="$REF_IMAGE"
    ;;
esac

curl -fsS --max-time 240 --retry 2 --retry-delay 5 \
  "$BASE_URL/images/edits" \
  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
  --form-string "model=$MODEL" \
  --form-string "size=$SIZE" \
  --form-string "prompt=$PROMPT" \
  -F "image=@$REF_LOCAL" > "$RESP"

if jq -e '.error' "$RESP" >/dev/null 2>&1; then
  echo "API error:" >&2
  jq '.error' "$RESP" >&2
  exit 1
fi

# `// empty` makes missing fields output empty string instead of "null",配合 -s 检查避免写出 3 字节假 PNG
jq -er '.data[0].b64_json // empty' "$RESP" | base64 --decode > "$OUT"
[ -s "$OUT" ] || { echo "empty or malformed output: $OUT" >&2; head -c 300 "$RESP" >&2; exit 1; }

printf '%s\n' "$PROMPT"    > "${OUT%.png}.prompt.txt"
printf '%s\n' "$REF_IMAGE" > "${OUT%.png}.ref.txt"

file "$OUT"
ls -lt "$BOOK_DIR/封面/"

Step 5: Export Platform Upload Size (When Platform Has Fixed Pixels)

When the platform has fixed upload pixels (Tomato 600×800), center crop + scale the original image to the upload size — regardless of whether the generated image is 2:3 or 3:4, crop it to the platform's exact pixels without distortion, to avoid the platform cropping the book title/pen name. Retain the original image, save a separate

_上传

version;

SRC

and

TARGET

directly use task values from previous steps, do not rely on cross-shell temporary variables:

bash

SRC='<Absolute path of original image generated in Step 4>'
TARGET='<Platform upload size determined in Step 1; leave blank if none>'
[ -f "$SRC" ] || { echo "封面原图不存在: $SRC" >&2; exit 1; }
if [ -n "$TARGET" ] && [ -f "$SRC" ]; then
  UP="${SRC%.png}_上传.png"; W="${TARGET%x*}"; H="${TARGET#*x}"
  if command -v magick >/dev/null 2>&1; then M=magick
  elif command -v convert >/dev/null 2>&1; then M=convert; else M=""; fi
  if [ -n "$M" ]; then
    "$M" "$SRC" -resize "${W}x${H}^" -gravity center -extent "${W}x${H}" "$UP"  # Scale to fill then center crop
  elif command -v sips >/dev/null 2>&1; then
    cp "$SRC" "$UP"
    sw=$(sips -g pixelWidth "$UP" | awk '/pixelWidth/{print $NF}')
    sh=$(sips -g pixelHeight "$UP" | awk '/pixelHeight/{print $NF}')
    if [ $((sw*H)) -ge $((sh*W)) ]; then sips --resampleHeight "$H" "$UP" >/dev/null
    else sips --resampleWidth "$W" "$UP" >/dev/null; fi
    sips -c "$H" "$W" "$UP" >/dev/null   # sips -c is height first, width second, center crop
  else
    echo "无 magick/convert/sips，跳过；手动把 $SRC 居中裁剪+缩放到 $TARGET 再上传" >&2
  fi
  [ -f "$UP" ] && file "$UP"
fi

The book title/pen name have been placed in the central safe area in the prompt, so center cropping will not cut them.

Step 6: Quality Check + Iteration

Check Item	Standard
Text Rendering	Book title is clearly recognizable, font style matches the genre
Genre Matching	Visual style is consistent with the book title's genre
Reasonable Composition	Main subject is prominent, text does not block core visuals
Platform Adaptation	Conforms to the target platform's cover style and tone
Platform Dimensions	Ratio matches the platform; after scaling to upload size, book title and author name are fully visible and not cropped

When unsatisfied, adjust directions: Change composition, adjust color tone, switch font style, change platform style.

Reference Materials

File	When to Load
references/cover-styles.md	Genre→visual style mapping, platform style details, prompt templates

Language

Reply in the user's language; use the same language as the user's input
Follow Chinese Copywriting Guidelines for Chinese replies

story-cover

NPX Install

Tags

SKILL.md Content (Chinese)

story-cover: Novel Cover Generation

Generation Pathways

Output Parameters & API Fallback Environment Variables

Generation Process

Step 1: Collect Information

Step 2: Genre Determination

Step 3: Build Prompt

Text Layer: Book Title + Author Name Font Design

Book Title Font Styles

Author Name Font Styles (Key: Author name must be carefully designed, not just "small text")

Style Layer: Platform Style

Visual Layer: Genre + Composition

Complete Prompt Template

Prompt Tips (Tested and Verified)

Step 4: Generate and Save

Codex Built-in ImageGen (Priority)

API Fallback

Text-to-Image (Default)

Image-to-Image (When Reference Image is Provided)

Step 5: Export Platform Upload Size (When Platform Has Fixed Pixels)

Step 6: Quality Check + Iteration

Reference Materials

Language