Generate a Cinematic Restaging from an Image

Generate restaged cinematic artwork (Restaged Cinematic) from one or more uploaded photos via the platform API, and return a download link for the finished piece(s).

What the Skill Does

Workflow

1. Step 0: Check environment (required)

   Before running, verify your configuration:

   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 restaging request. Specify what to keep, how aggressively to simplify, the one impossible scale/spatial logic you want, e.g. "keep the cyclist's pose, minimal environment, emphasize the contrast between the person and the color field".
   • Size (optional): output size as WxH, eg. 1024X1024, 1920x1080. When the user provides one, it takes priority; when omitted, each piece defaults to the size of its corresponding reference image — piece i uses the size of reference i.
   • Session ID (optional): for session grouping; omit on the first run 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 generate-restaged-cinematic

   node "<skills-dir>/surgepix-generate-restaged-cinematic/scripts/generate_restaged_cinematic.mjs" \
     --reference "<path-or-url>" [--reference "<path-or-url>" ...] \
     --prompt "<conversion request>" \
     [--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; each generates one piece)
   --prompt <text>	Restaging request (required): what to keep, simplification, expected scale / spatial logic, etc.
   --size <WxH>	Uniform output size as WxH; when omitted, defaults to the corresponding reference image size; a user-provided value takes priority
   --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 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):

   Single piece:

   {"ok":true,"taskId":"task_xxx","sessionId":123,"progress":"succeeded","download":"https://...images.zip","resultType...":4,"resultType":"zip","note":"API 仅返回 ZIP 下载地址，不含单张图片 URL；禁止编造单张链接"}

   Multiple pieces:

   {"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 the download link
     • resultType: "image" (single) — download is a single image URL
     • resultType: "zip" (multiple) — download is a ZIP; show only the ZIP link, stating N "finished pieces; download and unzip to view"; never fabricate per-image URLs
   • 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 request