Surgepix Generate Poster

SurgePix Generate Poster

Generate an event poster (PNG) from event info (name, date, venue) plus optional styling and reference images, and get a download URL.

Language consistency

Match the user's conversation language for all text printed on the poster — unless the user explicitly requests another language.

• This skill has no --language flag — language is controlled via printed text fields and --prompt.
• Do not use Chinese for --event-name / --venue / --description when the user prompts in English.
• Reply to the user in the same language they used in their request.

When to use

• User says "生成海报", "做个海报", "generate poster", "make a poster", "create a poster"
• User provides an event name, date, and venue, optionally with styling hints or reference images

Prerequisites

• Node.js >= 18
• SURGEPIX_API_KEY configured (see Step 0)

What the Skill Does

The script always submits the task asynchronously (the API returns a taskId immediately). The --nowait flag controls what the script does next:

• --nowait false (default) — the script polls internally until the task is succeeded/failed and returns the final download URL in one call.
• --nowait true — the script returns the taskId immediately without waiting; resolve it later with the surgepix-query-task skill.

Setup

Requirement: Set the SURGEPIX_API_KEY environment variable. Get your API Key at your platform's API management page.

export SURGEPIX_API_KEY=your-api-key-here

This skill uses the script at <skills-dir>/surgepix-generate-poster/scripts/generate_poster.mjs.

Usage Examples

First run — using --prompt for creative direction (no --style needed):

node "<skills-dir>/surgepix-generate-poster/scripts/generate_poster.mjs" \
  --event-name "2026 Design Summit" \
  --date "2026-06-15 19:00" \
  --venue "Shanghai · Expo Center" \
  --description "Top designers explore the future of creativity" \
  --prompt "Dark background, neon blue and purple gradient, centered large title, futuristic tech style" \
  --size 1080x1920
# Output (JSON):
#   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>"}
#   ← Save sessionId for retries

Not satisfied — adjust prompt direction with same session ID:

node "<skills-dir>/surgepix-generate-poster/scripts/generate_poster.mjs" \
  --event-name "2026 Design Summit" \
  --date "2026-06-15 19:00" \
  --venue "Shanghai · Expo Center" \
  --description "Top designers explore the future of creativity" \
  --prompt "Change to white background, gold accents, premium minimalism, larger bolder title font" \
  --size 1080x1920 \
  --session-id 123                ← Pass the sessionId from previous output (number type)
# Both versions appear in the same session on the platform frontend.

Generate with a brand reference image (uploaded automatically):

node "<skills-dir>/surgepix-generate-poster/scripts/generate_poster.mjs" \
  --event-name "Brand Launch" \
  --date "2026-07-01 14:00" \
  --venue "Beijing · National Convention Center" \
  --style bold \
  --reference ./logo.png
# Script uploads the image automatically — no separate step needed.

Multiple reference images:

node "<skills-dir>/surgepix-generate-poster/scripts/generate_poster.mjs" \
  --event-name "Summer Music Festival" \
  --date "2026-08-10 20:00" \
  --venue "Shenzhen · Seaside Plaza" \
  --reference ./logo.png --reference ./mood.jpg --reference <IMAGE_URL> \
  --size 1080x1920

Workflow

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

Step 1: Gather inputs

--event-name, --date, and --venue are required.

• Event name (required): main title displayed on the poster

• Date and time (required): e.g. 2026-06-15 19:00

• Venue (required): location name or address shown on the poster

• Prompt (optional): free-form creative direction — describe desired color scheme, typography, layout, imagery, or atmosphere. This instructs the AI and does not appear as text on the poster.

• Description (optional): tagline or intro text printed on the poster, max 100 characters

• Style (optional): layout and typography preset. Choose from: modern / vintage / minimalist / bold. Use as a quick shorthand for visual direction; omit if --prompt already describes the style. See Preset Styles section below for detailed descriptions.

• Size (optional, default 1080x1920): custom dimensions in WxH format, e.g. 1080x1920, 1080x1080, 1920x1080

• Reference image (optional): local file path or image URL; script uploads automatically. Repeatable for multiple images. Supported formats: JPEG, JPG, PNG, WEBP — max 20MB each.

• Session ID (optional): if the user is iterating on a previous result, ask them to provide the sessionId (number type) printed by the last run. If this is a fresh request, omit it — the platform auto-creates a new session.

• Local reference image → script uploads automatically, then calls API

• Reference image URL → script uses it directly

Step 2: Run generate-poster

node "<skills-dir>/surgepix-generate-poster/scripts/generate_poster.mjs" \
  --event-name "<text>" --date "<text>" --venue "<text>" \
  [--prompt "<text>"] [--description "<text>"] [--style <name>] \
  [--size <1080x1920>] [--reference "<path-or-url>" ...] [--session-id <id>] \
  [--nowait <true|false>]

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":"<DOWNLOAD_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":"<HINT>"}

Failure (stderr):

{"ok":false,"error":"<ERROR>"}

Step 4: Present result

• On success: Show the download URL. 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 parameter — --event-name, --date, or --venue not provided
  • --description exceeds 100 characters
  • Reference image format not supported or exceeds 20MB
  • Invalid --size value
  • Generation failed — internal error; retry or simplify the prompt
• The result is automatically attached to the session (auto-created or reused). The user can open the platform frontend to see all iterations in one place.
• If the user is not satisfied and wants to iterate, instruct them to pass --session-id <sessionId> (number type) in the next run — both versions appear in the same session history on the frontend.

Parameters

Preset Styles

Rules

• ALWAYS run check_env.mjs before first use in a session
• --event-name, --date, --venue are all required — never run the command if any is missing
• --description must be at most 100 characters
• The request is always submitted asynchronously; --nowait only controls whether the script polls locally (false, default) or returns the taskId immediately (true) — do not treat it as the API noWait field
• In async mode (--nowait true), guide the user/Agent to resolve the taskId via the surgepix-query-task skill
• NEVER pass local reference image paths to the API — script handles upload internally
• NEVER invent download URLs — only use the download value from the output
• NEVER echo auth tokens in logs or output
• If the user wants to iterate, they pass --session-id 123 in the next run — both versions appear in the same session on the frontend.
• If --session-id is omitted, the platform auto-creates a new session for the run.
• If the user provides a brand color, pass it via --prompt, e.g. --prompt "Brand color #FF5A00, tech style, dark background". Do not put creative direction in --description — that field is reserved for text printed on the poster.
• The poster download URL is valid for 24 hours; download before it expires.
• To generate multilingual versions of the same poster, run the command separately for each language, adjusting --event-name, --venue, and --description accordingly.
• Language: Write all on-poster text fields in the user's conversation language; never default to Chinese when the user writes in English.
• Reference image supported formats: JPEG, JPG, PNG, WEBP — max 20MB each.