Film Storyboards Generator

SurgePix Film Storyboards Generator

Generate film storyboard images (landscape, 16:9 by default) from a script / storyboard description via the platform API, and return a download link.

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

   The core input comes from the user: the script / outline text (--script). The shot specs (--shots) are automatically generated by the Agent before the call and are not required from the user.

   • Script (required): the script or story outline text. The user only needs to describe it in natural language; the more complete the script (scenes, action, dialogue, mood), the more accurate the storyboard.
   • Count (optional, default 4, range 1-30): the number of shots. The Agent splits the script into that many shots; one storyboard sheet holds at most 12 shots — more than 12 are automatically split into multiple sheets (e.g. 20 shots → sheet 1 with 12 + sheet 2 with 8).
   • Aspect ratio (optional, default 16:9): frame ratio. Options: 16:9 (TV/film), 2.35:1 (widescreen), 4:3 (classic film / animation), 9:16 (vertical).
   • Reference image (optional): local file path or image URL; the script uploads automatically. Repeatable for multiple images. Supported formats: JPEG / JPG / PNG / WEBP — max 20MB each.
   • Session ID (optional): when iterating on a previous result, ask for the sessionId (number type) printed by the previous run; omit for a fresh request — the platform auto-creates a new session.
   • Local reference image → script uploads automatically, then calls API
   • Reference image URL → script uses it directly

3. Step 2: Run generate-storyboard

   node "<skills-dir>/surgepix-generate-storyboard/scripts/generate_storyboard.mjs" \
     [--script "<script>"] [--shots '<json>'] [--shots-file "<path>"] \
     [--count <1-30>] [--aspect-ratio <16:9>] [--reference "<path-or-url>" ...] \
     [--session-id <id>] [--nowait <true|false>]

   Parameter	Description
   --script <text>	Script / story outline (provided by the user; recommended mode)
   --shots <json>	Shot spec JSON array (an Agent-generated internal artifact, not filled in by the user)
   --shots-file <path>	Script / story outline (provided by the user; recommended mode)
   --count <1-30>	Number of shots, default 4; one sheet holds at most 12 shots — more auto-split into multiple sheets
   --aspect-ratio <16:9>	Frame ratio: 16:9 / 2.35:1 / 4:3 / 9:16
   --reference <path-or-url>	Reference image (local path auto-uploaded; repeatable for multiple images)
   --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

   Single storyboard (--count 1 or --shots with only 1 entry, 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): single storyboard image URL
     • resultType: "zip" (imageCount > 1): ZIP archive — do not list per-image URLs
   • Storyboard sheet count note: ≤ 12 shots = 1 sheet; > 12 shots outputs multiple sheets (max 12 shots each). Tell the user "N shots total, split into M storyboard sheets."
   • On failure: Report the error field. Common causes:
     • missing_required_param — --script (script / outline) not provided
     • invalid_param_value — --count out of range or invalid --aspect-ratio
     • unsupported_image_format — reference image format not supported
     • image_too_large — reference image exceeds 20MB
     • generation_failed — internal error; retry or simplify the description