Surgepix Generate Presentation

SurgePix Generate Presentation

Generate a presentation (PPTX) from a topic prompt and/or outline documents, and get a download URL.

Language consistency

Match the user's conversation language for slide content — unless the user explicitly requests another language.

• Always pass --language — do not rely on API auto-detect alone when the user's language is clear.
• Do not default to Chinese slides when the user prompts in English.
• Reply to the user in the same language they used in their request.

When to use

• User says "生成PPT", "做个演示文稿", "generate ppt", "make slides", "create a presentation"
• User provides a topic, key points, or an outline document (local file or URL)

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-presentation/scripts/generate_presentation.mjs.

Usage Examples

First run — prompt only, --style as a quick preset:

node "<skills-dir>/surgepix-generate-presentation/scripts/generate_presentation.mjs" \
  --prompt "Q3 2026 marketing results review with data highlights, problem analysis, and next quarter suggestions" \
  --n 10 \
  --style corporate \
  --language zh
# Output (JSON):
#   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>"}
#   ← Save sessionId for retries

With an outline file — detailed prompt, no --style needed:

node "<skills-dir>/surgepix-generate-presentation/scripts/generate_presentation.mjs" \
  --prompt "Generate annual strategy PPT based on this outline, dark business style, highlight data charts" \
  --outline ./outline.txt \
  --n 15

Not satisfied — iterate with adjusted prompt and same session ID:

node "<skills-dir>/surgepix-generate-presentation/scripts/generate_presentation.mjs" \
  --prompt "Q3 2026 marketing results review with data highlights, problem analysis, and suggestions — change to light and minimal style, blue/white palette" \
  --n 10 \
  --language zh \
  --session-id 123                ← Pass the sessionId from previous output (number type)
# Both results appear in the same session on the platform frontend.

Multiple outline files:

node "<skills-dir>/surgepix-generate-presentation/scripts/generate_presentation.mjs" \
  --prompt "年度战略规划摘要" \
  --outline ./part1.docx --outline ./part2.pdf --outline ./appendix.md \
  --n 20

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

--n is required, and at least one of --prompt or --outline must also be provided.

• Prompt (optional): text describing the presentation topic, purpose, and key points.

• Outline (optional): local file path or document URL. Script uploads automatically. Supported formats: doc, docx, pdf, txt, md, html, pptx — max 50MB.

• Slide count (required, range 5–30): use --n (integer)

• Aspect ratio (optional, default 16:9): 16:9 (widescreen) / 4:3 (standard)

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

• Language (required in practice): match user's conversation language — zh / en / ja. Always pass --language; do not omit when user language is clear.

• 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 outline file → script uploads automatically, then calls API

• Outline URL → script uses it directly

Step 2: Run generate-presentation

node "<skills-dir>/surgepix-generate-presentation/scripts/generate_presentation.mjs" \
  --n <5-30> [--prompt "<text>"] [--outline "<path-or-url>" ...] \
  [--aspect-ratio <16:9>] [--style <name>] \
  [--language <zh|en|ja>] [--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 — --n not provided, or neither --prompt nor --outline provided
  • Unsupported outline format — file format not supported
  • Outline file too large — exceeds 50MB
  • --n out of range (must be 5–30) or invalid --language code
  • 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
• Provide at least --prompt or --outline
• --n is required and must be an integer between 5 and 30 — never run the command without it
• 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
• 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.
• The .pptx download URL is valid for 24 hours; download before it expires.
• Supported outline formats: doc, docx, pdf, txt, md, html, pptx — max 50MB.
• NEVER pass local outline 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
• Language: Always pass --language matching the user's conversation language; English prompt → --language en, 中文 → --language zh.