Surgepix Generate Storyboard

SurgePix Generate Storyboard

Generate one storyboard image containing multiple shots from a shot script, with optional reference images (local paths auto-uploaded to URLs).

Language consistency

Match the user's conversation language for --script — unless the user explicitly requests another language.

• Reply to the user in the same language they used in their request.

When to use

• User says "分镜头", "故事板", "分镜剧本", "storyboard", "shot list", "分镜图"
• User provides a multi-shot script and wants a single multi-panel storyboard image

Prerequisites

• Node.js >= 18
• SURGEPIX_API_KEY and SURGEPIX_BASE_URL configured (see surgepix-setup)

What the Skill Does

The script always submits asynchronously to the API (noWait=true). CLI --nowait controls local behavior:

• --nowait false (default) — poll until succeeded/failed and return download
• --nowait true — return taskId immediately; use surgepix-query-task later

Setup

Requirement: Set SURGEPIX_API_KEY and SURGEPIX_BASE_URL (see surgepix-setup). Do not ask the user to paste the API key into chat.

# project-root .env
SURGEPIX_API_KEY=your-token
SURGEPIX_BASE_URL=https://api.surgepix.ai/api

Script path: <skills-dir>/surgepix-generate-storyboard/scripts/generate_storyboard.mjs.

Usage Examples

Script only (sync):

node "<skills-dir>/surgepix-generate-storyboard/scripts/generate_storyboard.mjs" \
  --script "第一个镜头：主角站在黄昏海边；第二个镜头：海面上出现帆船；第三个镜头：主角微笑；第四个镜头：帆船驶向远方" \
  --count 4 \
  --aspect-ratio 4:3
# {"ok":true,"taskId":"task_xxx","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>"}
# `<DOWNLOAD_URL>` 仅为文档占位；真实 HTTPS 下载地址以脚本 stdout 为准。

With local reference:

node "<skills-dir>/surgepix-generate-storyboard/scripts/generate_storyboard.mjs" \
  --script "Shot 1: wide establishing; Shot 2: close-up" \
  --reference ./style-ref.png \
  --count 2

Async:

node "<skills-dir>/surgepix-generate-storyboard/scripts/generate_storyboard.mjs" \
  --script "..." \
  --nowait true
# Then: node "<skills-dir>/surgepix-query-task/scripts/query_task.mjs" <taskId>

Workflow

Step 0: Check environment

node "<skills-dir>/surgepix-setup/scripts/check_env.mjs"

• Exit 0 → continue
• Exit 1 → follow surgepix-setup (user writes .env themselves)

Step 1: Collect inputs

• Required: shot script → --script
• Optional: --count (1–12, default 4), --aspect-ratio (default 4:3)
• Optional: --reference (repeatable, max 10; local path or URL), --session-id, --nowait

Step 2: Run

node "<skills-dir>/surgepix-generate-storyboard/scripts/generate_storyboard.mjs" \
  --script "<text>" \
  [--count <1-12>] \
  [--aspect-ratio <ratio>] \
  [--reference <path-or-url> ...] \
  [--session-id <id>] \
  [--nowait <true|false>]

Step 3: Present result

• Success: paste only the download value from script stdout verbatim inside a fenced code block (or raw URL line). Do not retype the hostname; do not “fix” or shorten the URL.
• Always show sessionId (number) for retries.
• Async: show taskId + hint to use surgepix-query-task
• Never invent image URLs; never echo API keys

Parameters

Notes

• Backend accepts URL-only references; the script uploads local files first.
• Calls POST /tasks/generate-storyboard (backend task API), not /skills/*.
• Download links may expire; tell the user to save promptly.
• On missing env → surgepix-setup, do not collect secrets in chat.