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.

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 --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):

   Field	Required	Description
   theme	Yes	This image's theme
   structureType	No	Structure type, e.g. Workflow / before-after / concept metaphor
   coreIdea	No	Core message this image should convey
   composition	No	Specific scene description
   elements	No	Suggested visual elements (string array)
   labels	No	Suggested handwritten annotation labels (string array; use the user's language)

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

   Flag	Description
   --topic <text>	Article topic or body summary (required when shots not provided)
   --shots <json>	Per-shot specs as inline JSON array
   --shots-file <path>	Per-shot specs from a JSON file
   --count <1-9>	Auto-generate count from topic, default 4
   --reference <path-or-url>	Style reference image (local path auto-uploaded; repeatable)
   --session-id <id>	Session ID; pass the sessionId (number type) from a previous run to iterate
   --nowait <true|false>	Wait mode, default false 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://...illustrations.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 — 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.