Surgepix Generate Xhs

SurgePix Generate Xiaohongshu Images

Generate Xiaohongshu (小红书) vertical carousel image sets (cover + content pages) from per-page copy descriptions plus optional reference images, and get a download URL.

Language consistency

Match the user's conversation language for on-image text and --prompt copy — unless the user explicitly requests another language.

• Always pass --language — do not omit it. If omitted, the API may default to Chinese on-image text.
• Do not default to --language zh 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 横版/16:9 文章插图
• User did not mention 小红书/RED/笔记/竖版, and the content is for a blog or WeChat article

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

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

When to use

• User says "生成小红书套图", "做小红书图", "小红书笔记图", "generate xiaohongshu images", "make RED post images"
• User explicitly mentions 小红书, RED, 笔记, 竖版轮播, or vertical carousel for social posts
• User provides per-page copy and wants cover + content images in Xiaohongshu style

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-xhs/scripts/generate_xhs.mjs.

API: prompt is list(string)

The API field prompt is a string array, not a single string. Each item describes one image in the set:

Length rule: prompt.length must equal count.

• count=1 → 1 prompt (cover only)
• count=4 → 4 prompts (1 cover + 3 content pages)

CLI shortcut: pass a single --prompt with --count > 1 — the script repeats that text to fill the list (same as the API example).

Usage Examples

Single cover image:

node "<skills-dir>/surgepix-generate-xhs/scripts/generate_xhs.mjs" \
  --prompt "春季护肤 5 个误区，很多人第一条就踩坑" \
  --count 1 \
  --style modern \
  --language zh
# API body: {"prompt":["春季护肤 5 个误区，很多人第一条就踩坑"], "count":1, ...}
# Output (JSON):
#   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>"}
#   ← Save sessionId for retries

Full image set — same topic on all pages (auto-repeat):

node "<skills-dir>/surgepix-generate-xhs/scripts/generate_xhs.mjs" \
  --prompt "零基础学 Python：7 天入门路线" \
  --count 4 \
  --style bold \
  --language zh \
  --reference ./brand-ref.png
# API body: {"prompt":["零基础学 Python：7 天入门路线", ...×4], "count":4, ...}
# Output: cover + 3 content images packaged as a ZIP

Full image set — per-page copy (recommended for richer content):

node "<skills-dir>/surgepix-generate-xhs/scripts/generate_xhs.mjs" \
  --prompt "零基础学 Python：7 天入门路线 | 封面：7天从零到能写脚本" \
  --prompt "Day 1-2：环境搭建 + 变量与类型，附推荐资源" \
  --prompt "Day 3-4：循环、函数、列表字典，3 个小练习" \
  --prompt "Day 5-7：小项目实战 + 下一步学习路线" \
  --count 4 \
  --style bold \
  --language zh

Not satisfied — iterate with same session ID:

node "<skills-dir>/surgepix-generate-xhs/scripts/generate_xhs.mjs" \
  --prompt "零基础学 Python：7 天入门路线，改为简约风格，配色用浅蓝白" \
  --count 4 \
  --style minimalist \
  --language zh \
  --session-id 123                ← Pass the sessionId from previous output (number type)
# Both versions appear in the same session on the platform frontend.

With reference images (URL or local):

node "<skills-dir>/surgepix-generate-xhs/scripts/generate_xhs.mjs" \
  --prompt "咖啡店探店 | 藏在巷子里的宝藏小店" \
  --count 6 \
  --reference ./shop-photo1.jpg --reference <IMAGE_URL> \
  --language zh

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 --prompt is required. Repeat --prompt for each page when count > 1 and pages need different copy.

Agent guidance for multi-page sets:

1. Ask how many images the user wants (count).
2. If the user only gives a general topic, use one --prompt + --count (auto-repeat).
3. If the user provides an outline or per-page points, craft one --prompt per page (cover first, then content pages).
4. Ensure --prompt count matches --count before running (unless using the single-prompt auto-repeat shortcut).

• Local reference image → script uploads automatically, then calls API
• Reference image URL → script uses it directly

Step 2: Run generate-xhs

node "<skills-dir>/surgepix-generate-xhs/scripts/generate_xhs.mjs" \
  --prompt "<text>" [--prompt "<text>" ...] \
  [--count <1-16>] [--style <name>] [--language <zh|en|jp>] \
  [--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、prompt 内容推测并编造单张图片链接。
• 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 解压查看」。
• 绝对禁止编造「封面图」「第 2 张」等单张图片下载链接——API 不会返回这些 URL。
• 若用户需要单张直链，只能以 --count 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 — no --prompt provided
    • --prompt count does not match --count (and not using single-prompt auto-repeat)
    • --count out of range (must be 1–16)
    • Reference image format not supported or exceeds 20MB
    • Generation failed — internal error; retry or simplify the prompts
  • 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

Preset Styles

Rules

• This skill is for 小红书/RED vertical套图 only — never use it for 公众号/博客/推文横版配图 (use surgepix-generate-illustrations)
• 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 --prompt is required — never run the command without it
• API prompt is list(string); script sends an array. --prompt count must equal --count, except when only 1 --prompt is given and count > 1 (script auto-repeats)
• --count must be 1–16 when provided; 1 means cover only, N>1 means 1 cover + (N-1) content images
• 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 cover/content 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 count > 1, the download is a ZIP containing all images (cover first, then content images in order).
• Language: Always pass --language matching the user's conversation language; English prompt → --language en, 中文 → --language zh.