Generate AI-powered 16:9 hand-drawn article illustrations (1536×864) for blogs, WeChat Official Account posts, and tweets — optimized for autonomous agent skill calling and automated workflows. Use when the user asks for article illustrations, blog images, WeChat OA graphics, tweet visuals, or horizontal editorial art. Accepts natural language prompts, per-shot specs, or style reference images. Returns a download URL, session ID, and task ID, with async execution and automatic polling. Supports multi-image packs (ZIP), session-based multi-turn iteration, and auto language detection for on-image labels.
npx skills add https://github.com/surgepix/agent-skills --skill surgepix-generate-illustrationsGenerate 16:9 horizontal article illustrations (hand-drawn style, fixed 1536×864) from a topic or per-shot specifications, and get a download URL.
| Action | Description |
|---|---|
| Generate illustrations | Create 16:9 horizontal illustrations from topic or per-shot specs |
| Upload reference image | Upload a style reference image to calibrate the illustration style |
| Check task status | Poll a generation task by taskId to check progress manuually |
| Download result | Retrieve the .pptx download URL directly from the task result |
| |
Step 0: Check environment (required)
Before running, verify config:
node "<skills-dir>/surgepix-setup/scripts/check_env.mjs"
.env, then retryStep 1: Gather inputs
At least one of --topic or --shots/--shots-file must be provided.
--shots is not provided.--shots or from file via --shots-file ). When provided, takes priority over --topic/--count and generates images in array order. 4, range 1-9): number of images to auto-generate from --topic . Only effective when--shots is not provided.JPEG, JPG, PNG, WEBP — max 20MB each.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) |
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.
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":"..."}
Step 4: Present result
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 neededresultType: "image" (imageCount === 1): download is a single image URLresultType: "zip" (imageCount > 1): download is a ZIP file — do not list per-image URLserror field. Common causes:--topic nor --shots / --shots-file provided--count out of range (must be 1–9)--shots JSON parse error--session-id <sessionId> (number type) in the next run — both versions appear in the same session history on the frontend.Create & Edit Visuals with AI
© 2026 SurgePix. All rights reserved. Made with ❤️ for productivity.