Surgepix Generate Illustrations

SurgePix Generate Illustrations

Generate 16:9 horizontal article illustrations (hand-drawn style, fixed 1536×864) from a topic or per-shot specifications, and get a download URL.

Language consistency

Match the user's conversation language for on-image handwritten labels and all text parameters — unless the user explicitly requests another language.

• This skill has no --language flag — language is controlled entirely via --topic, --shots, and shot labels.
• Do not default to Chinese labels when the user prompts in English.
• Reply to the user in the same language they used in their request.

Skill router (read first)

Do NOT use this skill when:

• User wants 小红书套图, 小红书笔记图, 竖版轮播, or RED post images
• User explicitly mentions 小红书, RED, 笔记, or vertical social carousel

Ambiguous input: If the user only says「配图」「做几张图」without platform or aspect ratio, ask:

是要 小红书竖版套图（笔记轮播），还是 公众号/博客横版插图（16:9）？

When to use

• User says "文章配图", "博客插图", "公众号配图", "推文配图", "generate illustrations", "make article images"
• User wants horizontal (16:9) illustrations for blog posts, WeChat Official Account articles, tweets, or other editorial content
• User provides a topic/article summary or detailed per-shot specifications
• User says「生成配图」and context indicates 公众号/博客/文章/横版 (not 小红书/笔记/竖版)

Prerequisites

• Node.js >= 18
• SURGEPIX_API_KEY configured (see Step 0)

What the Skill Does

The script always submits the task asynchronously (the API returns a taskId immediately). The --nowait flag controls what the script does next:

• --nowait false (default) — the script polls internally until the task is succeeded/failed and returns the final download URL in one call.
• --nowait true — the script returns the taskId immediately without waiting; resolve it later with the surgepix-query-task skill.

Setup

Requirement: Set the SURGEPIX_API_KEY environment variable. Get your API Key at your platform's API management page.

export SURGEPIX_API_KEY=your-api-key-here

This skill uses the script at <skills-dir>/surgepix-generate-illustrations/scripts/generate_illustrations.mjs.

Usage Examples

Auto-generate by topic (simplest mode):

node "<skills-dir>/surgepix-generate-illustrations/scripts/generate_illustrations.mjs" \
  --topic "内容生产闭环：从选题、写作到分发与复盘" \
  --count 4
# Output (JSON):
#   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>","imageCount":4,"resultType":"zip","note":"API 仅返回 ZIP 下载地址，不含单张图片 URL；禁止编造单张链接"}
#   ← Save sessionId for retries

Per-shot detailed specifications (inline JSON):

node "<skills-dir>/surgepix-generate-illustrations/scripts/generate_illustrations.mjs" \
  --shots '[{"theme":"内容生产闭环","structureType":"Workflow","coreIdea":"用传送带表现选题→写作→分发→复盘","composition":"小黑站在传送带旁推纸条","elements":["传送带","纸条","四个槽口"],"labels":["选题","写作","分发","复盘"]},{"theme":"算法推荐与人工干预","structureType":"before-after","coreIdea":"对比纯算法推流与人工校准后两种状态"}]'
# Generates 2 illustrations with precise control

Per-shot from file (recommended for complex specs):

node "<skills-dir>/surgepix-generate-illustrations/scripts/generate_illustrations.mjs" \
  --shots-file ./illustration-specs.json \
  --reference ./style-ref.png

Iterate with same session ID:

node "<skills-dir>/surgepix-generate-illustrations/scripts/generate_illustrations.mjs" \
  --topic "内容生产闭环：从选题、写作到分发与复盘" \
  --count 4 \
  --session-id 123                ← Pass the sessionId from previous output (number type)
# Both versions appear in the same session on the platform frontend.

Workflow

Step 0: Check environment (required)

Before running, verify config:

node "<skills-dir>/surgepix-setup/scripts/check_env.mjs"

• Exit 0 → proceed to Step 1
• Exit 1 → follow surgepix-setup skill to configure .env, then retry

Step 1: Gather inputs

At least one of --topic or --shots/--shots-file must be provided.

• Topic (conditionally required): article topic or body text summary. Required when --shots is not provided.
• Shots (optional): per-shot illustration specifications as a JSON array (inline via --shots or from file via --shots-file). When provided, takes priority over --topic/--count and generates images in array order.
• Count (optional, default 4, range 1–9): number of images to auto-generate from --topic. Only effective when --shots is not provided.
• Reference image (optional): local file path or image URL for style calibration; script uploads automatically. Repeatable for multiple images. Supported formats: JPEG, JPG, PNG, WEBP — max 20MB each.
• Session ID (optional): if the user is iterating on a previous result, ask them to provide the sessionId (number type) printed by the last run.

Shot Specification Object (for --shots array elements):

Step 2: Run generate-illustrations

node "<skills-dir>/surgepix-generate-illustrations/scripts/generate_illustrations.mjs" \
  [--topic "<text>"] [--shots '<json>'] [--shots-file "<path>"] \
  [--count <1-9>] [--reference "<path-or-url>" ...] \
  [--session-id <id>] [--nowait <true|false>]

The request is always submitted asynchronously. --nowait false (default) makes the script poll internally until the task completes and returns the final download; --nowait true makes the script return the taskId immediately, to be resolved later via the surgepix-query-task skill.

Step 3: Parse output

Sync success (--nowait false, stdout):

{"ok":true,"taskId":"task_xxx","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>","imageCount":4,"resultType":"zip","note":"API 仅返回 ZIP 下载地址，不含单张图片 URL；禁止编造单张链接"}
# `<DOWNLOAD_URL>` 仅为文档占位；真实 HTTPS 下载地址以脚本 stdout 为准。

CRITICAL — 禁止编造单张图片链接

• API 的 taskResult 只有 download 一个字段，没有单张图片 URL 列表。
• resultType: "zip"（或 imageCount > 1）时：只展示 download ZIP 链接，告知用户下载 ZIP 后解压获取各张图。
• 绝对禁止根据 imageCount、主题或 shots 推测并编造 image1.png、image2.png 等单张链接。
• resultType: "image"（imageCount === 1）时：download 才是单张图片 URL，也只展示这一个链接。

Async submitted (--nowait true, stdout) — resolve later with the surgepix-query-task skill:

{"ok":true,"async":true,"taskId":"task_xxx","sessionId":123,"progress":"processing","download":null,"hint":"<HINT>"}

Failure (stderr):

{"ok":false,"error":"<ERROR>"}

Step 4: Present result

CRITICAL — 禁止编造单张图片链接（幻觉高发区）

• 脚本输出 resultType: "zip" 或 imageCount > 1 时，API 只返回一个 ZIP 的 download 链接，没有单张图片 URL。
• 只向用户展示 download 这一个 ZIP 链接，说明「共 N 张图，请下载 ZIP 解压查看」。
• 绝对禁止编造「第 1 张」「第 2 张」等单张图片下载链接——API 不会返回这些 URL。
• 若用户需要单张直链，只能重新以 --count 1 或 --shots 只含 1 条重新生成。

• On success: Show only the download URL from script output. Always show sessionId (note: it is a number type, e.g. 123) so the user can pass it in a retry if needed.
  • resultType: "image" (imageCount === 1): download is a single image URL
  • resultType: "zip" (imageCount > 1): download is a ZIP file — do not list per-image URLs
  • On failure: Report the error field. Common causes:
    • Missing required parameter — neither --topic nor --shots/--shots-file provided
    • --count out of range (must be 1–9)
    • --shots JSON parse error
    • Reference image format not supported or exceeds 20MB
    • Generation failed — internal error; retry or simplify the topic
  • The result is automatically attached to the session (auto-created or reused). The user can open the platform frontend to see all iterations in one place.
  • If the user is not satisfied and wants to iterate, instruct them to pass --session-id <sessionId> (number type) in the next run — both versions appear in the same session history on the frontend.

Parameters

Output Format

All generated illustrations are:

• Aspect ratio: 16:9 horizontal
• Resolution: 1536×864 pixels
• Style: Hand-drawn illustration style with handwritten annotations in the user's language

Rules

• This skill is for 16:9 horizontal article/editorial illustrations only — never use it for 小红书/RED vertical套图 (use surgepix-generate-xhs)
• If the user only says「配图」without 小红书/公众号/博客/横版/竖版, ask which platform and aspect ratio before running
• ALWAYS run check_env.mjs before first use in a session
• At least one of --topic or --shots/--shots-file must be provided
• --count must be 1–9 when provided; only effective in topic mode (no --shots)
• When --shots is provided, it takes priority over --topic and --count; images are generated in array order
• The request is always submitted asynchronously; --nowait only controls whether the script polls locally (false, default) or returns the taskId immediately (true) — do not treat it as the API noWait field
• In async mode (--nowait true), guide the user/Agent to resolve the taskId via the surgepix-query-task skill
• If the user wants to iterate, they pass --session-id 123 in the next run — both versions appear in the same session on the frontend.
• If --session-id is omitted, the platform auto-creates a new session for the run.
• NEVER pass local reference image paths to the API — script handles upload internally
• NEVER invent download URLs — only use the download value from the output
• NEVER invent per-image URLs when resultType is zip — the API does not return individual image links; only the ZIP download exists. Do not fabricate img1.png, img2.png, or numbered image URLs.
• When resultType: "zip", present only the ZIP download link and tell the user to unzip for individual images
• NEVER echo auth tokens in logs or output
• The download URL is valid for 24 hours; download before it expires.
• Reference image supported formats: JPEG, JPG, PNG, WEBP — max 20MB each.
• When multiple images are generated, the download is a ZIP containing all illustrations in order.
• For complex per-shot specifications, prefer --shots-file over inline --shots to avoid shell escaping issues.
• Each shot's theme field is required; other fields (structureType, coreIdea, composition, elements, labels) are optional but recommended for precise control.
• Language: Write --topic and shot fields in the user's language; never default on-image text to Chinese when the user writes in English.