SurgePix Background Remover

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

What the Skill Does

Workflow

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

2. Step 1: Identify the input

   • Local file → script uploads automatically, then calls API
   • URL → script uses it directly

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

4. Step 3: Submit the removal task

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

   • 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.
   • By default, polls GET /v1/tasks/{taskId} every 5 seconds until status is succeeded or failed.
   • Pass --noWait to skip polling and return the taskId immediately.
   • Output is always .png to preserve transparency information.

5. Step 4: Parse output

   Success (stdout):

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

   Failure (stderr):

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

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

7. Step 6: Batch processing

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

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.