SurgePix Poster Creator

Generate a professional event poster image from structured event details using the SurgePix API. Use when the user asks to create an event poster, activity flyer, promotional banner, or any visual announcement for an event.

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

2. 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 --promptPreset 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

3. 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>]

   Flag	Description
   --event-name <text>	Main title on the poster (required)
   --date <text>	Event date and time, e.g. 2026-06-15 19:00 (required)
   --venue <text>	Location text shown on the poster (required)
   --prompt <text>	Creative direction (color, typography, layout) — not printed on poster
   --description <text>	Tagline printed on the poster, max 100 characters
   --style <name>	Layout preset: modern / vintage / minimalist / bold
   --size <WxH>	Output dimensions, default 1080x1920
   --reference <path-or-url>	Reference image (local path auto-uploaded; repeatable for multiple files)
   --session-id <id>	Session ID; pass the sessionId (number type) from a previous run to iterate

   The script always uses asynchronous mode (internal noWait=true) — it submits the task and automatically polls until complete. noWait is hardcoded inside the script; do NOT pass it as a parameter.

4. Step 3: Parse output

   Success (stdout):

   {"ok":true,"taskId":"task_xxx","sessionId":123,"progress":"succeeded","download":"https://...poster.png"}

   Failure (stderr):

   {"ok":false,"error":"..."}

5. 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.

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.
• NEVER pass noWait — it is hardcoded to true inside the script.
• 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.
• Reference image supported formats: JPEG, JPG, PNG, WEBP — max 20MB each.