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.

| Priority | Rule | |----------|------| | 1 | User explicitly names a target (e.g. "translate to English", "翻译成日文") → use that language code | | 2 | User does not specify target → infer from intent: English request → --language en; 中文请求 → --language zh; 日本語 → --language ja | | 3 | Ambiguous → ask the user which target language they want |

• 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

| Action | Description | |---------------------|-----------------------------------------------------------------------------| | Translate image | Pass local file(s) or URL(s); script uploads and translates in one step | | Batch translate | Pass multiple images in one call; result is a ZIP download URL | | Check task status | When run with --nowait true, poll by taskId via surgepix-query-task | | Download result | Single image → image URL; multiple images → ZIP URL |

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

bash
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):

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

Translate to Chinese:

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

Retry / iterate with same session:

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

Multiple images (returns ZIP):

bash
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):

bash
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":"..."}

# Then use surgepix-query-task to check status

Workflow

Step 0: Check environment (required)

Before first use, run the environment check:

bash
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

bash
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):

json
{"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"https://...","imageCount":1,"resultType":"image"}

Async submitted (--nowait true, stdout):

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

Failure (stderr):

json
{"ok":false,"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

| Parameter | Required | Default | Description | |--------------------------|----------|--------------|-----------------------------------------------------------------------------| | <file path or URL> | Yes | — | Positional argument(s). One or more local paths or image URLs | | --language <code> | Yes | user intent | Target language for on-image text, e.g. `en`, `zh`, `ja`. Always pass — match explicit request or user's language | | `--session-id <id>` | No | auto-created | Omit on first run; provide on retries to group iterations in one session | | `--nowait <true\|false>` | No | `false` | `false` = sync: API waits and returns final `download`. `true` = async: returns `taskId`; resolve via surgepix-query-task |

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.