SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsstory-cover

story-cover

Design & creation

View repository

Updated 10-16 09:30

About this skill

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 containing the book title and author name in one pass.

Core principle: The cover is the reader's first impression; it conveys the genre and atmosphere at a glance.

Generation pathways

  • Codex built-in (preferred): When the current Codex CLI session can call $imagegen / image_gen , generate directly and write to disk; counts toward general Codex usage, no OPENAI_API_KEY or GPT_IMAGE_API_KEYrequired, and does not run curl。story-cover to call tools on its own, and does not make the user open another command.
  • API fallback: Used only when the session has no built-in tool or the user explicitly specifies the API; requires GPT_IMAGE_API_KEY. A missing tool does not mean the Codex subscription does not support image generation; when the built-in call fails, report the error first, and do not silently switch to a possibly billable API.

Output parameters and API fallback environment variables

Variable Required Default Description
GPT_IMAGE_API_KEY Required for API fallback — API Key for OpenAI or a compatible proxy; not used by the Codex built-in pathway
GPT_IMAGE_BASE_URL https://api.openai.com/v1 Change this when using a compatible proxy
GPT_IMAGE_MODEL gpt-image-2 Override only when testing a new model
GPT_IMAGE_SIZE 1024x1536 Target aspect ratio hint for API fallback (Fanqie 3:4→768x1024, default 2:3→1024x1536). The official gpt-image-2 accepts any size that is a multiple of 16 (ratio ≤3:1), butmany relay proxies ignore size and return roughly 2:3 by preset(tested)—platform dimensions do not rely on it; the "Export platform upload size" step covers this
UPLOAD_SIZE — Platform-fixed upload pixels (Fanqie 600x800); once set, the "Export platform upload size" step center-crops + scales to the upload version (no distortion, independent of the generated image size)
BOOK_DIR ✅ — Output directory, recommended ./covers/<书名>
REF_IMAGE — Local path or URL of the reference image; the built-in pathway first loads the image into the session, the API fallback uses images/edits image-to-image

Generation workflow

Step 1: Collect information

Required: book title, author name (pen name), target platform, output directory BOOK_DIR(recommended ./covers/<书名>; the API fallback uses environment variables, the built-in pathway directly uses the current task value). When asking the author, say "Where should the cover be saved? Default ./covers/<书名>", and do not throw variable names at the author as questions Optional: reference image REF_IMAGE(local path or URL; once set, switch to image-to-image), style preference, size

Book title and pen name are required cover information: If either is missing, you must first use AskUserQuestion to ask the user to fill it in; do not fabricate or leave it blank.

Set cover dimensions according to the target platform: Fanqie upload 600×800 is 3:4(not 2:3); if the generated image ratio is wrong, the platform's secondary crop will cut off the book title/pen name.

Platform Upload size Ratio Generate GPT_IMAGE_SIZE(as much as possible)
Fanqie Novel 600×800 3:4 768x1024
Other platforms (default vertical) Per platform specs 2:3 1024x1536

The built-in pipeline writes the target ratio into the prompt; API fallback then export GPT_IMAGE_SIZE(many proxies ignore it and return about 2:3). When the platform has fixed upload pixels, set UPLOAD_SIZE(Fanqie 600x800）。Platform dimensions are ultimately guaranteed by the "Export Platform Upload Size" step via center cropping + scaling, and do not depend on the actual generated image dimensions. For platform and genre styles, see references/cover-styles.md。

Step 2: Genre determination

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

  • Single genre hit → use directly
  • Multiple genre hits → choose one by priority: Xianxia > Western Fantasy > Ancient Romance > Modern Romance > Urban > Suspense > Sci-Fi > Historical > Supernatural > Light Novel
  • Zero hits → default 都市

Step 3: Build the prompt

Prompt = Text layer + Style layer + Scene 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; GPT-Image-2 can render them directly.Focus on describing the font style：

Title text '书名' at top center in [书名字体风格].
Author name '作者名' at bottom center in [作者名字体风格].

Book title font style

Genre Description keywords
Fantasy/Xianxia bold golden brush calligraphy with metallic glow and sharp strokes
Urban modern bold sans-serif with metallic silver finish
Ancient Romance/Palace Intrigue 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/Apocalypse neon glowing futuristic font in electric blue
Western Fantasy metallic embossed fantasy lettering with glow effect
Historical/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 style (key point: the author name must be carefully designed, not just "small text")

Although the author name is small, it is key to a professional cover. You must specify:Font + Color + Decorative elements, so that the author name echoes the book title style without stealing focus.

Genre Author name style prompt
Fantasy/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 Intrigue 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/Apocalypse 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
Historical/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(it must not be so large that it steals focus from the book title, nor so small that it is illegible)
  • Position:at bottom center, keeping an appropriate distance from the bottom of the image
  • Must have decorative elements: at least one of lines/borders/small icons/light effects
  • Color contrasts with the background but is not harsh

Style layer: platform style

The platform style description keywords uniformly come from references/cover-styles.md 's "Platform Style" section; directly use the corresponding keyword string for the target platform, and do not maintain a copy in this file to avoid drifting from the reference file.

Scene layer: genre + composition

From references/cover-styles.md , read the style tags, colors, characters, and background description corresponding to the genre.

Composition variants (output 2-3 options the first time):

Option Composition Suitable genres
A Character close-up + scene Suitable for all genres
B Full-body portrait + dynamic pose Fantasy, urban, Western fantasy
C Pure scene/atmosphere image Suspense, sci-fi, historical

Complete prompt template

Chinese web novel cover design, [平台风格].
Title text '{书名}' at top center in [书名字体风格].
Author name '{作者名}' at bottom center in [作者名字体风格 — 从上表选择].
[题材风格标签]. [人物描述]. [背景描述].
[色彩指令]. [光效指令].
Professional book cover, high detail digital painting, portrait [平台比例：番茄=3:4，默认=2:3] ratio, keep title and author name inside the central safe area away from edges (inner ~85%), no watermark

Prompt techniques (verified in practice)

  • Character descriptions should be as specific as possible: specify every dimension—clothing, pose, hairstyle, expression, props
  • Background layering: foreground (character) → midground (scene) → background (atmosphere)
  • Lighting means specifying light source direction + color (e.g. dramatic golden light from above）
  • Use digital painting style instead of photo, to avoid a photorealistic-photo feel

Step 4: Generate and save

Codex built-in ImageGen (preferred)

  1. Use the complete prompt from Step 3 to call image_gen. Write the aspect ratio and safe area into the prompt; do not pass GPT_IMAGE_MODEL、GPT_IMAGE_SIZE、response_format or other API parameters.
  2. When there is REF_IMAGE , for local files first load them into the session with an image viewing tool; for URLs, download first and then load. Explain whether it is the edit target or a style reference, and list what must be preserved.
  3. Call once separately for each composition plan. First create BOOK_DIR/封面/, then copy the image returned by the tool as 封面_vN.png，N with auto-increment so old versions are not overwritten; keep the $CODEX_HOME/generated_images/ original file, and also save a same-named .prompt.txt; if there is a reference image, also save .ref.txt. Confirm the image is readable, and hand the absolute path of the original image to Step 5.

API fallback

gpt-image-2 always returns base64; do not include response_formatin the request body (old DALL-E parameter, not supported by the gpt-image series).$PROMPT is the complete prompt assembled in the “Build prompt” step.

Choose one of the two invocation methods: if REF_IMAGE is not set → use “text-to-image”; if set → use “image-to-image”.

Text-to-image (default)

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/<书名>}"

mkdir -p "$BOOK_DIR/封面"

# 自增版本号，避免覆盖之前生成的封面
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

# 用 jq 拼 JSON 体，避免 PROMPT 里的引号/换行/中文把 shell 字符串撑破
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"

# API 出错时早退，避免把 error JSON 当成 base64 写成损坏 PNG
if jq -e '.error' "$RESP" >/dev/null 2>&1; then
  echo "API error:" >&2
  jq '.error' "$RESP" >&2
  exit 1
fi

# `// empty` 让缺失字段输出空串而非 "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"

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

Image-to-image (when a reference image is provided)

/v1/images/edits use multipart/form-data，cannot use Content-Type: application/json. For text fields use --form-string(to avoid @ being mistaken for a file reference), and for image fields use -F image=@path。

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/封面"

# 自增版本号
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

# URL 先下载到临时文件，本地路径直接用。用裸 mktemp 以保证 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` 让缺失字段输出空串而非 "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 to platform upload size (when the platform has fixed pixels)

When the platform has fixed upload pixels (Tomato 600×800), crop the original imagecenter-crop + scaleto the upload size—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 out the book title/pen name again. Keep the original image and save a separate _上传 version;SRC and TARGET directly use the task values from the preceding steps, without relying on cross-shell temporary variables:

SRC='<Step 4 生成的原图绝对路径>'
TARGET='<Step 1 确定的平台上传尺寸；无则留空>'
[ -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"  # 缩放填满后居中裁
  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 是 高 宽，居中裁
  else
    echo "无 magick/convert/sips，跳过；手动把 $SRC 居中裁剪+缩放到 $TARGET 再上传" >&2
  fi
  [ -f "$UP" ] && file "$UP"
fi

The book title/pen name already have a central safe area reserved in the prompt, so center-cropping will not cut them off.

Step 6: Quality check + iteration

Check item Standard
Text rendering The book title is clearly legible, and the font style matches the genre
Genre match The visual style is consistent with the book title's genre
Reasonable composition The subject stands out, and the text does not obscure the core image
Platform fit Matches the cover style tone of the target platform
Platform size The aspect ratio matches the platform's; after scaling to the upload size, the book title and pen name are fully visible and not cropped

When dissatisfied, adjust direction: change composition, adjust color tone, change font style, change platform style.

Tell the author this when delivering; do not paste commands, environment variables, or interface errors to the author. On failure, state the cause and solution in one sentence (e.g., "The image generation interface is not configured properly; you need to set the API Key first"):

封面做好了：`{封面图路径}`{；{平台}上传版（{上传尺寸}）：`{上传版路径}`}
这版的思路：{构图 + 色调 + 书名字体，一句话}
想调的话可以说：{2-3 个具体方向，如「换成人物特写」「书名改成毛笔字」}

Reference materials

File When to load
references/cover-styles.md Subject matter → visual style mapping, platform style details, prompt templates

Language

  • Reply in the user's language; use whatever language the user uses
  • Chinese replies follow the "Chinese Copywriting Guidelines"