Production API workflow

Remove image backgrounds through one asynchronous API

Peelaway's background removal API accepts a base64 JPEG, PNG, or WebP plus the instruction “remove the background.” It creates an asynchronous job and returns a transparent PNG at the processed dimensions, capped at an 8,192-pixel edge. Poll for completion or use a signed webhook, then fetch the signed result URL. Each image uses one credit; 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

Background removal quickstart

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.