SurgePix Image Editing

Edit an image via the platform API based on submitted reference images and a text edit instruction (change style, recolor, replace elements, adjust composition, etc.), and return a download link for the edited image.

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 → configure .env following the surgepix-setup skill, then retry

2. Step 1: Gather inputs

   Everything is entered via parameters (this skill has no dialogue step).

   • Reference image (required, at least one): a local file path or an image URL; repeatable for multiple images. Every submitted image participates in the edit as a reference. Accepts:
     • Local file path (e.g. ./photo.png)
     • URL pointing to an image
   • Prompt (required): the edit instruction. State clearly what to change about the reference image (style / color scheme / elements / composition / mood), e.g. "turn the image into anime illustration style", "switch the whole image to warm tones", "replace the background with a beach".
   • Size (optional): output size as WxH, eg. 1024X1024, 1920x1080. When the user provides one, it takes priority; when omitted, defaults to the size of the submitted reference image — the first one when multiple.
   • Session ID (optional): for session grouping. sessionId can be reused across skills; it only serves to show this result together with previous generation results in the same frontend session history. When switching to this skill to adjust a result from another generation-type skill because the user is not satisfied with it, reuse the sessionId (number type) output by that skill; omit it on a brand-new request and the platform auto-creates a new session.
   • Validate every reference image before submission:
     • Supported formats: JPEG / JPG / PNG / WEBP
     • Max size: 20MB each
     • If the format is unsupported or the file is too large, tell the user and ask them to replace the file.
   • Local reference image → the script uploads it automatically, then calls the API
   • Image URL → used directly by the script

3. Step 2: Run image-edit

   node "<skills-dir>/surgepix-image-edit/scripts/image_edit.mjs" \
     --reference "<path-or-url>" [--reference "<path-or-url>" ...] \
     --prompt "<edit instruction>" \
     [--size <WxH>] \
     [--session-id <id>] [--nowait <true|false>]

   Flag	Description
   --reference <path-or-url>	Reference image (local paths are auto-uploaded; repeatable; at least one required)
   --prompt <text>	Edit instruction (required): what to change
   --size <WxH>	Output size as WxH;when omitted, defaults to the reference image (the first one when multiple); a user-provided value takes priority
   --session-id <id>	Session ID (number type); can be reused across skills, only to show results in the same frontend session history
   --nowait <true|false>	Wait mode, default false (see below)

   The request is always submitted asynchronously. --nowait false (default) makes the script poll internally until completion and return the final download ; --nowait true returns 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","resultType...":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,"resultType":"..."}

   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.
   • On failure: Report the error field. Common causes:
     • missing_required_param — no reference image or --prompt provided
     • unsupported_image_format — file format not supported
     • image_too_large — file exceeds 20MB
     • invalid_param_value — --size invalid format or value
     • generation_failed — internal error; retry or simplify the instruction