Surgepix Remove Background

Remove Background — AI-Powered Background Removal

Remove the background from an image and return a transparent PNG using the platform API. Use when the user asks to remove background, cut out a subject, make an image transparent, or create a PNG with no background.

Language consistency

This skill does not generate on-image text. Reply to the user in the same language they used in their request.

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-remove-background/scripts/remove_background.mjs.

Usage Examples

First run — pass a local file, script uploads automatically:

node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" \
  ./photo.jpg
# Script uploads the image automatically — no separate step needed.
# Output (JSON):
#   {"ok":true,"taskId":"task_abc123","sessionId":123,"progress":"succeeded","download":"<DOWNLOAD_URL>"}
#   ← Save sessionId for retries

Not satisfied — retry with same session ID:

node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" \
  ./photo.jpg \
  --session-id 123                ← Pass the sessionId from previous output (number type)

Submit task and get taskId only (do not wait for completion):

node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" \
  ./photo.jpg --nowait true
# Returns JSON immediately:
#   {"ok":true,"async":true,"taskId":"task_abc123","sessionId":123,"progress":"processing","download":null,"hint":"<HINT>"}

# Then use the surgepix-query-task skill to poll the taskId until progress becomes succeeded

Batch: remove backgrounds from multiple images:

node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" ./img1.jpg
node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" ./img2.jpg
node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" ./img3.jpg

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 → script uploads automatically, then calls API
• URL → script uses it directly

Step 2: Collect inputs

• The user must provide an image. Accept either:
  • Local file path (e.g. ./photo.jpg)
  • URL pointing to an image
• Session ID (optional): if the user is retrying the same image, ask them to provide the sessionId printed by the last run. If this is a fresh image, omit it — the platform will auto-create a new session.
• Validate the file before submitting:
  • Supported formats: JPEG, JPG, PNG, WEBP
  • Maximum size: 20MB
  • If unsupported format or oversized, inform the user and ask for a different file.

Step 3: Submit the removal task

node "<skills-dir>/surgepix-remove-background/scripts/remove_background.mjs" \
  "<file path or URL>" \
  [--session-id <sessionId>] \
  [--nowait <true|false>]

• The image parameter is a positional argument (required). Pass the file path or URL directly — no --file prefix needed. The script uploads the image automatically, then calls the platform API and receives a taskId.
• The request is always submitted asynchronously. By default (--nowait false), the script polls GET /tasks/{taskId} every 2 seconds until status is succeeded or failed.
• Pass --nowait true to skip polling and return the taskId immediately; resolve it later with the surgepix-query-task skill.
• Output is always .png to preserve transparency information.

Step 4: Parse output

Sync success (--nowait false, stdout):

{"ok":true,"taskId":"task_abc123","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_abc123","sessionId":123,"progress":"processing","download":null,"hint":"<HINT>"}

Failure (stderr):

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

Step 5: Handle the 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.
• Edge quality issues: If the user reports rough edges (common with hair, fur, or complex backgrounds), inform them that a higher-contrast or higher-resolution source image may improve results, and offer to retry with the same sessionId.
• On failure: Report the error message from the error field. Common causes:
  • unsupported_image_format — file format not supported
  • image_too_large — file exceeds 20MB

Step 6: Session sync and iteration

• 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 wants to retry, instruct them to pass --session-id 123 (number type) — both attempts appear in the same session history.

Step 7: Batch processing

• If the user provides multiple images, repeat Steps 3–6 for each one.
• After all are complete, present all download links together.

Parameters

remove-background

Notes

• Output is always .png — do not rename to .jpg as transparency will be lost.
• Supported input formats: JPEG, JPG, PNG, WEBP. Max file size: 20MB.
• The download link in the result is valid for 24 hours; download before it expires.
• Always display the sessionId from the output (note: it is a number type, e.g. 123). If the user wants to retry (e.g. due to edge quality issues), they pass --session-id 123 in the next run — both attempts appear in the same session on the frontend.
• If --session-id is omitted, the platform auto-creates a new session for the run.
• The image parameter is a positional argument — pass the path or URL directly, no --file prefix. The script auto-detects whether it is a local file or a remote URL.
• Must run check_env.mjs before first use in each session.
• Never pass local paths to the API — script handles upload internally.
• Never invent download URLs — only use the download value from the output.
• Never expose auth tokens in logs or output.