Surgepix Image Translate

Image Translate — Translate Text on Images

Translate text on one or more images to a target language while preserving the background, using the platform API. Use when the user asks to translate image text, localize a poster/screenshot, or convert on-image copy to another language.

Language consistency

--language is the target language for on-image text, not the agent's reply language.

• Always pass --language — do not rely on the script default (en) without checking user intent.
• Reply to the user in the same language they used in their request (agent reply ≠ --language target).

What the Skill Does

By default (--nowait false), the API waits for completion and returns the final download URL in one call. With --nowait true, the API returns a taskId immediately; 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-image-translate/scripts/image_translate.mjs.

Usage Examples

First run — translate a local image to English (default):

node "<skills-dir>/surgepix-image-translate/scripts/image_translate.mjs" \
  ./poster.png
# Output (JSON):
#   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>","imageCount":1,"resultType":"image"}
#   ← Save sessionId for retries

Translate to Chinese:

node "<skills-dir>/surgepix-image-translate/scripts/image_translate.mjs" \
  ./poster.png \
  --language zh

Retry / iterate with same session:

node "<skills-dir>/surgepix-image-translate/scripts/image_translate.mjs" \
  ./poster.png \
  --language en \
  --session-id 123

Multiple images (returns ZIP):

node "<skills-dir>/surgepix-image-translate/scripts/image_translate.mjs" \
  ./page1.png ./page2.png \
  --language en
# download → ZIP URL; resultType=zip

Async submit (return taskId only):

node "<skills-dir>/surgepix-image-translate/scripts/image_translate.mjs" \
  ./poster.png \
  --language ja \
  --nowait true
# Returns JSON immediately:
#   {"ok":true,"async":true,"taskId":"task_abc123","hint":"<HINT>"}

# Then use surgepix-query-task to check status

Workflow

Step 0: Check environment (required)

Before first use, run the environment check:

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

• Exit 0 → proceed to Step 1
• Exit 1 → follow the surgepix-setup skill to configure .env, then retry

Step 1: Identify the input

• Local file(s) → script uploads automatically, then calls API
• URL(s) → script uses them directly
• Ask the user for the target language if not specified. Infer from user language or explicit request (see Language consistency); do not blindly default to en.

Step 2: Collect inputs

• The user must provide at least one image. Accept either:
  • Local file path(s) (e.g. ./poster.png)
  • URL(s) pointing to images
• Language (required in practice): target language code — en, zh, ja, etc. Always pass based on user intent (see Language consistency).
• Session ID (optional): if the user is retrying, use the sessionId from the last run. Omit on first run — the platform auto-creates a new session.
• Validate each file before submitting:
  • Supported formats: JPEG, JPG, PNG, WEBP
  • Maximum size: 20MB per file
  • If unsupported or oversized, inform the user and ask for a different file.

Step 3: Submit the translation task

node "<skills-dir>/surgepix-image-translate/scripts/image_translate.mjs" \
  "<file path or URL>" [<image2> ...] \
  [--language <code>] \
  [--session-id <sessionId>] \
  [--nowait <true|false>]

• Image parameters are positional arguments (at least one required). Pass file paths or URLs directly — no --file prefix. The script uploads local files automatically.
• Default (--nowait false): API waits for completion and returns the final download URL.
• Pass --nowait true to return the taskId immediately; resolve later with surgepix-query-task.

Step 4: Parse output

Sync success (--nowait false, stdout):

{"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>","imageCount":1,"resultType":"image"}

Async submitted (--nowait true, stdout):

{"ok":true,"async":true,"taskId":"task_abc123","sessionId":123,"progress":"processing","download":null,"imageCount":1,"resultType":"image","hint":"<HINT>"}

Failure (stderr):

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

Step 5: Handle the result

• On success: Show the download URL.
  • resultType: "image" — single translated image
  • resultType: "zip" — multiple images packaged as ZIP
• Always show sessionId (number type, e.g. 123) so the user can retry in the same session.
• On failure: Report the error field. Common causes:
  • unsupported_image_format — file format not supported
  • image_too_large — file exceeds 20MB

Step 6: Session sync and iteration

• Results are attached to the session (auto-created or reused). The user can view all iterations on the platform frontend.
• To retry, pass --session-id 123 — both attempts appear in the same session history.

Parameters

image-translate

Notes

• Single image → download is an image URL; multiple images → download is a ZIP URL.
• Supported input formats: JPEG, JPG, PNG, WEBP. Max file size: 20MB per image.
• The download link is valid for 24 hours; download before it expires.
• Always display the sessionId from output (number type). Pass --session-id 123 on retry to keep iterations in one session.
• Image parameters are positional arguments — pass paths or URLs directly, no --file prefix.
• Must run check_env.mjs before first use in each session.
• Never pass local paths to the API — the script handles upload internally.
• Never invent download URLs — only use the download value from output.
• Never expose auth tokens in logs or output.