Remove a background

Remove a background and return an image in one request. Requires an API key. If processing takes more than 55 seconds, returns 202 with a job ID; poll that job instead of creating another.

POST/v1.0/removebg

Authenticate with X-API-Key. Keep your key on your server; never embed it in a public website.

Request parameters

image_filebinary

JPG, PNG or WebP file, up to 22 MB. Choose exactly one input source.

image_urlstring

Public HTTP or HTTPS image URL. Private hosts, credentials, non-standard ports and unsafe redirects are rejected.

image_file_b64string

Base64-encoded image bytes. Choose this instead of a file or URL.

qualitystringdefault: fast

Fast uses 1 credit. Fine detail (quality) uses 2. Output resolution is independent of quality.

fastquality

sizestringdefault: auto

auto, preview and small fit within 625 × 400 pixels. full and 50MP preserve original dimensions, up to 50 MP. No upscaling.

autopreviewsmallfull50MP

formatstringdefault: auto

auto chooses JPG for a background or PNG for transparency. ZIP contains color.jpg and alpha.png.

autopngjpgwebpzip

bg_colorstring

Three- or six-digit hex color, with or without #.

bg_image_urlstring

Public image URL for a replacement background. Mutually exclusive with bg_image_file.

bg_image_filebinary

Replacement background file, up to 22 MB.

cropbooleandefault: false

Crop to the detected subject bounds.

crop_marginintegerdefault: 0

Padding around cropped subject, in pixels. Integer from 0 to 1,000.

add_shadowbooleandefault: false

Add a drop shadow when no shadow_type is selected.

shadow_typestringdefault: none

Choose a generated contact or drop shadow.

nonedropgroundcar

shadow_opacityintegerdefault: 35

Shadow opacity from 0 to 100.

semitransparencybooleandefault: true

Preserve soft edges. false thresholds alpha at 128.

channelsstringdefault: rgba

Return color with transparency or a grayscale alpha mask.

rgbaalpha

Response

200 · Success

{
  "binary": "PNG, JPG, WebP or ZIP bytes",
  "headers": {
    "X-Credits-Charged": "1",
    "X-Job-Id": "image_id",
    "X-Width": "1200",
    "X-Height": "800"
  }
}

Errors use a structured error.code and error.message. See error handling →