AI
AI background removal
POST /v1/ai/bg-remove — send an image, get back a transparent PNG with the background removed.
Send an image and get back the same subject on a transparent background, as a PNG. Available on Unlimited and Unlimited + AI.
Request
POST /v1/ai/bg-remove
multipart/form-data with an image field (a raw image body also works,
without the multipart wrapper):
Terminal
curl -X POST https://api.helloimg.io/v1/ai/bg-remove \
-H "Authorization: Bearer <your API key>" \
-F "[email protected]" \
-o product-no-bg.png
Response
On success, the response body is the image — Content-Type: image/png,
not a JSON envelope. A few headers describe what happened:
| Header | Description |
|---|---|
X-Processing-Time-Ms | How long the removal took. |
X-Original-Size | Size of the uploaded image, in bytes. |
X-Output-Size | Size of the resulting PNG, in bytes. |
Errors
Errors come back as JSON instead of an image:
| Status | Body | Cause |
|---|---|---|
400 | { "error": "Missing 'image' field in form data" } | No image field in a multipart request. |
400 | { "error": "Empty request body" } | No image data sent at all. |
401 | { "error": "invalid api key" } | Missing or malformed Authorization header. Applies to every /v1/* route — one shared check in front of all of them. |
403 | { "error": "ai requires the Unlimited + AI plan", "code": "ai_plan_required" } | Free plan — AI isn't available at all. |
429 | { "error": "monthly AI credit limit reached", "code": "ai_credits_exhausted" } | Unlimited plan, 100 AI credits already used this month. Unlimited + AI has no cap. |
500 | { "error": "Background removal failed", "details": "..." } | Processing failed. |
Background removal doesn't run through the optimize/job pipeline — there's
no
job_id to poll. The response either is the finished image, or an
error.