Remove BG

Overview

Remove BG removes the background from any image and returns a transparent PNG. One endpoint, one required field, one response shape. Designed for product pages, design tools, ad creative pipelines, and any workflow that needs clean cutouts at scale.

Endpoint

POSThttps://api.codia.ai/v1/open/remove_bg

Authentication is via bearer token. Get a key at codia.ai/dashboard/developer.

Request

Field	Type	Required	Description
`image_url`	string	yes in JSON mode	Publicly-reachable URL of the source image.
`image`	file	yes in multipart mode	Local source image file sent as `multipart/form-data`. `file` is also accepted as a compatible field name.

JSON URL example

bash

curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -H 'Content-Type: application/json' \
  --data '{
    "image_url": "your image url"
  }'

Direct upload example

bash

curl 'https://api.codia.ai/v1/open/remove_bg' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./product.png'

Codia checks credits before reading and uploading multipart files. If credits are insufficient, the request returns 402 without uploading the image.

Response

json

{
  "code": 0,
  "message": "ok",
  "data": {
    "image_url": "https://processed-image-url.com/result.png"
  }
}

Field	Description
`code`	`0` on success. Non-zero values indicate input or processing errors.
`message`	Human-readable status.
`data.image_url`	CDN URL of the result PNG with transparent background. Pull and store on your side; URLs are not long-lived.

Output characteristics

Format — PNG with alpha channel.
Resolution — matches input up to the plan's maximum (HD on all tiers).
Edge quality — sub-pixel matting, color decontamination on the foreground, no background-shadow smear.
Self-shadows on the subject — retained (e.g., shaded underside of a mug).

Performance

Setting	Value
Typical processing time	~600 ms
End-to-end latency	800 – 1200 ms
Concurrency	Plan-dependent; typical plans support hundreds of parallel requests

Supported inputs

Input	Recommendation
Common formats	JPEG, PNG, WEBP
Minimum resolution	400 px on long edge
Maximum size	Plan-dependent; defaults to 25 MB
Images with existing alpha	Flatten onto white before calling to preserve intended transparency
Extreme motion blur	Works but edges soften
Subject / background color collision (e.g., white on white)	Usable but consider human review

Error codes

`code`	Meaning
`0`	Success.
`40001`	`image_url` missing or unreachable.
`40002`	Unsupported format.
`40003`	Image exceeds size limit.
`42900`	Rate limit exceeded — back off and retry.
`50000`	Transient server error — retry with backoff.

Always treat non-zero code as a signal to branch: retry on transient errors, fail fast on input errors.

Integration patterns

Product upload (synchronous)

const res = await fetch('https://api.codia.ai/v1/open/remove_bg', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CODIA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image_url: sourceUrl }),
}).then((r) => r.json())

if (res.code === 0) {
  await saveToBucket(res.data.image_url)
}

Batch ingestion (asynchronous)

For large catalogs, run a worker pool at your plan's concurrency limit and retry transient failures. Skip images below the minimum resolution rather than wasting calls.

Compositing

Composite the returned PNG onto a dark background (e.g., #111) during development to spot edge fringing. Clean cutouts hold up; if you see a halo, inspect the input.

FAQ

Can I upload instead of passing a URL?

Yes. Send multipart/form-data with the local image in the image field, or keep using JSON with image_url when the source image is already public.

Are output URLs permanent?

No. Download the result and store it in your own bucket — URLs are valid long enough to retrieve but expire.

Does pricing vary by image size?

No. Pricing is per successful call, flat.

Is there rollover for unused credits?

Yes — unused credits roll over monthly on paid plans. See pricing.

Can I keep cast shadows?

The default removes all background, including cast shadows. Keeping shadows is available on enterprise deployments with a configuration flag.

Next steps

PDF to Visual Struct — structural conversion of PDF documents.
Visual Struct — structural conversion of images.
Full endpoint reference at /api#remove-background.