SurgePix Xiaohongshu Post Maker

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

What the Skill Does

Workflow

1. 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

2. Step 1: Gather inputs

   At least one of --prompt is required --prompt for each page when count > 1 and pages need different copy.

   Input	Required	Notes
   Prompt List	Yes	API prompt: list(string) CLI: repeatable --prompt. Index 0 = cover; In1..N-1 = content pages. Length must equal --count
   Count	No	Default = number of --prompt values (or 1 if only one prompt). Range 1-16 1=cover only; N > 1 = 1 cover + (N-1) content images.
   Style	No	modern / vintage / minimalist / bold. Default modern. See Preset Styles.
   Language	No	Text on images: zh / en / jp. Required in practice — set from user's conversation language (see Language consistency).
   Reference image	No	Local path or URL; script uploads automatically. Repeatable. Formats: JPEG, JPG, PNG, WEBP — max 20MB each.
   Session ID	No	For iteration, pass sessionId (number) from the last run. Omit on first run — platform auto-creates a session.

   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

3. 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>]

   Flag	Description
   --prompt <text>	Per-page topic / copy (required, repeatable). Maps to API prompt: list(string)
   --count <1-16>	Total images; default = --prompt count. Must equal number of prompts (unless only 1 prompt, then auto-repeat).
   --style <name>	Visual style: modern / vintage / minimalist / bold
   --language <code>	On-image text language: zh / en / jp. Always set to match user's conversation language.
   --reference <path-or-url>	Reference image (local path auto-uploaded; repeatable for multiple files)
   --session-id <id>	Session ID; pass the sessionId (number type) from a previous run to iterate
   --nowait <true|false>	Wait mode, default false (see below)

   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.

4. Step 3: Parse output

   Sync success (--nowait false, stdout):

   {"ok":true,"taskId":"task_xxx","sessionId":123,"progress":"succeeded","download":"https://...images.zip","imageCount":4,"resultType":"zip","note":"API 仅返回 ZIP 下载地址，不含单张图片 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":"..."}

   Failure (stderr):

   {"ok":false,"error":"..."}

5. Step 4: Present result

   • 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.