Peelaway Image API

Background removal API for transparent PNG output

Peelaway's background removal API accepts JPEG, PNG, or WebP images and returns transparent PNG output. Submit the image with the instruction “remove the background,” then poll the asynchronous job or receive a signed webhook before fetching the signed result URL. Each image uses one credit, and failed jobs refund it.

Verify the request and response fields in the live OpenAPI 3.1 contract and review the shipped integration skill.

Create an API key

Start with the background removal API

Send an image and the canonical background-removal instruction. The workflow forces PNG output so transparency is preserved even when another output format is requested.

curl

# Submit a background-removal job. webhook_url is optional.
curl -sS -X POST https://api.peelaway.io/api/process \
  -H "Authorization: Bearer $PEELAWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "image": "<base64-encoded JPEG, PNG, or WebP>",
    "prompt": "remove the background",
    "webhook_url": "https://your.app/hooks/peelaway"
  }'
# -> {"job_id":"...","credits_remaining":9}

# Without a webhook, poll until pending becomes done or error.
curl -sS \
  -H "Authorization: Bearer $PEELAWAY_API_KEY" \
  "https://api.peelaway.io/api/process/status?job_id=<job_id>"
# -> {"status":"pending"}

# After done, fetch the signed PNG result URL and metadata.
curl -sS \
  -H "Authorization: Bearer $PEELAWAY_API_KEY" \
  "https://api.peelaway.io/api/process/result?job_id=<job_id>"

Source: Peelaway OpenAPI.

Compare REST and MCP access

Choose polling or a signed webhook

Poll explicit states

Store the returned job ID and poll the status endpoint until pending becomes done or error. After done, retrieve the signed result URL and copy the PNG into storage you control.

Receive a callback

Supply a public HTTPS webhook URL on submit. Peelaway signs the terminal callback; verify its timestamp and signature, then deduplicate retries by job ID.

Output, dimensions, and credits

Output format: Background removal returns a transparent PNG regardless of a different requested format.
Dimensions: The output matches the processed frame. Inputs with an edge above 8,192 pixels are downscaled before processing; source EXIF preservation is not claimed.
Credits: One image debits one credit. A job that settles as an error refunds that credit to the same credit grants it used.

These are workflow boundaries, not quality or latency promises. Evaluate representative source images before automating publication.