BackgroundCut API v3

Remove backgrounds, generate multiple output variants, and segment objects with AI.

Quick Start Get API Key Interactive Docs ↗

Two-Step Processing

Upload once, process multiple times. Reuse the same image to generate different outputs without re-uploading.

Output Variants

Generate multiple sizes, formats, and background colors in a single process request.

Presigned URLs

For client-side integrations (browser, mobile), your server generates presigned URLs so images never route through your infrastructure.

Authentication

All requests require an Authorization header with your API key as a Bearer token. Get your API key from the Dashboard.

Header	Value	Required
`Authorization`	`Bearer YOUR_API_KEY`	Required

Keep your API key secret. Never include it in client-side code (browser JavaScript, mobile apps). Use presigned URLs for client-side integrations — see the Integration Guide.

Base URL

https://api.backgroundcut.co

All endpoint paths below are relative to this base URL.

Background Removal

Two-step process: upload the image, then process it with your desired output settings.

POST /v3/remove-bg/upload-image/

Upload an image to the API. Returns a unique_filename that is used in all subsequent processing requests.

Request

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`multipart/form-data` Set automatically when using `files=` or `FormData`

Form Fields

Field	Type	Required	Description
`image`	`file`	required	Image file. Supported: PNG, JPG, JPEG, WebP.

Response 200 OK

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Type	Description
`unique_filename`	`string`	Identifier for the uploaded image. Pass this to the process endpoint.

Presigned URL alternative — for client-side use (no API key on client):
1. Your server calls POST /v3/remove-bg/upload-image/presign/ with Bearer auth → gets signed_request
2. Client calls POST /v3/remove-bg/upload-image/presigned/?signed_request=<value> with the image file → same response

POST /v3/remove-bg/process-image/

Process a previously uploaded image and generate one or more output variants with background removed. A single request can produce multiple outputs (e.g. full-res PNG + thumbnail WebP + white background JPG) with one credit charge.

Request

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`application/json` Must be set explicitly. Body is JSON, not form data.

Request Body

Field	Type	Required	Description
`unique_filename`	`string`	required	From the upload response.
`output_variants`	`array`	optional	List of output configurations. If omitted, one variant with all defaults is produced.

Example Body

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "output_variants": [
        {
            "variant_name": "full",
            "max_resolution": 12000000,
            "format": "png",
            "background_color": null,
            "quality": "high",
            "output_compression": 85,
            "autocrop": false
        },
        {
            "variant_name": "thumb",
            "max_resolution": 250000,
            "format": "webp",
            "background_color": "#ffffff",
            "quality": "medium",
            "output_compression": 80,
            "autocrop": true
        }
    ]
}

Response 200 OK

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "input_url": "https://cdn.backgroundcut.co/.../input.jpg",
    "output_urls": {
        "full": "https://cdn.backgroundcut.co/.../full.png",
        "thumb": "https://cdn.backgroundcut.co/.../thumb.webp"
    }
}

Field	Type	Description
`unique_filename`	`string`	Image identifier. Save this to reuse the image.
`input_url`	`string`	URL to the original uploaded image.
`output_urls`	`object`	Map of `variant_name` → CDN URL. URLs are temporary — download or cache results promptly.

Presigned URL alternative — for client-side use:
1. Your server calls POST /v3/remove-bg/process-image/presign/ with Bearer auth + same JSON body → gets signed_request
2. Client calls POST /v3/remove-bg/process-image/presigned/ with body {"signed_request": "..."} → same response

Output Variant Fields

Each object in output_variants can have the following fields. All are optional — omit any field to use the default.

Field	Type	Default	Description
`variant_name`	`string`	`"default"`	Your identifier for this output. Appears as a key in `output_urls`. Use descriptive names like `"full"`, `"thumb"`, `"white_bg"`.
`max_resolution`	`integer`	`12000000`	Maximum pixel count (width × height) of the output image. `12000000` = 12MP. Output is scaled down proportionally if the input exceeds this.
`format`	`string`	`"png"`	Output file format. Options: `"png"` (lossless, supports transparency), `"jpg"` (no alpha channel — use with a background color), `"webp"` (smaller file size, supports transparency).
`background_color`	`string \| null`	`null`	Fill color for the background. Accepts hex values: `"#ffffff"`, `"#1A01FF"`. `null` or omitting this field means transparent. Note: transparent is not possible with `"jpg"` format — use `"png"` or `"webp"` instead.
`quality`	`string`	`"high"`	Background removal model quality. Options: `"high"`, `"medium"`, `"low"`. Higher quality increases processing time.
`output_compression`	`integer`	`85`	Compression level for lossy formats (`jpg`, `webp`). Range: `1`–`100`. Has no effect on `png`.
`autocrop`	`boolean`	`false`	Crop the output canvas tightly to the subject, removing empty transparent border. Adds 0.5 credits per variant with autocrop enabled.

Presigned URL Endpoints

Use presigned URLs when clients (browser, mobile) need to upload or process images directly without your API key being exposed. Your server mints the presigned URL; the client uses it with no auth header.

Endpoint	Auth	Content-Type	Description
`POST /v3/remove-bg/upload-image/presign/`	Bearer key	none required	Returns a `signed_request` token for a single upload operation
`POST /v3/remove-bg/upload-image/presigned/`	None	`multipart/form-data`	Upload image using `?signed_request=<value>` in query string. Returns `unique_filename`
`POST /v3/remove-bg/process-image/presign/`	Bearer key	`application/json`	Accepts same JSON body as the process endpoint. Returns a `signed_request` with the variant config baked in
`POST /v3/remove-bg/process-image/presigned/`	None	`application/json`	Process image using body `{"signed_request": "..."}`. Returns same `ProcessImageOut` response

Presign Response

{
    "signed_request": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Presigned tokens are single-use and short-lived. Request them immediately before use.

AI Cut

Point-based interactive segmentation. Initialize a session once, then refine the selection with green/red dots for free.

Pay Once, Refine Unlimited — Credits are charged at session initialization. All subsequent /v3/ai-cut/segment/ calls for the same session are free.

POST /v3/ai-cut/initialize/

Upload an image and start an AI Cut segmentation session. Returns the session identifier needed for all segment calls.

Request

Header	Value
`Authorization`	`Bearer YOUR_API_KEY`
`Content-Type`	`multipart/form-data`

Form Fields

Field	Type	Required	Description
`image`	`file`	required	Image to segment. Supported: PNG, JPG, JPEG, WebP.

Response 200 OK

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "s3_path": "uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/input.jpg",
    "bucket": "backgroundcut-ai-cut"
}

Field	Type	Description
`unique_filename`	`string`	Session identifier. Required for all segment calls.
`s3_path`	`string`	Internal storage path of the uploaded image.
`bucket`	`string`	Storage bucket name.

Presigned URL alternative — for client-side use:
1. Your server calls POST /v3/ai-cut/initialize/presign/ with Bearer auth → gets signed_request
2. Client calls POST /v3/ai-cut/initialize/presigned/?signed_request=<value> with image file → same response

POST /v3/ai-cut/segment/ FREE after init

Segment the image using point-based selection. Call this repeatedly to refine the result — always include all points accumulated across the session, not just new ones. Increment request_number with each call.

Request

Header	Value
`Content-Type`	`application/json` No `Authorization` header required for segment calls.

Request Body

Field	Type	Default	Description
`unique_filename`	`string`	—	required From the initialize response.
`greenDots`	`array`	`[]`	Points to include in the selection. Each item: `{"x": int, "y": int}` in image pixels.
`redDots`	`array`	`[]`	Points to exclude from the selection. Same format as `greenDots`.
`request_number`	`integer`	`0`	Monotonically increasing counter. Increment by 1 for each new segment call in the session.

Example Body

{
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "greenDots": [{"x": 250, "y": 300}, {"x": 260, "y": 310}],
    "redDots": [{"x": 50, "y": 50}],
    "request_number": 1
}

Response 200 OK

{
    "status": "completed",
    "unique_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "request_number": 1,
    "output_url": "https://cdn.backgroundcut.co/.../segment.png",
    "message": "Segmentation successful",
    "timestamp": 1712345678.123
}

Field	Type	Description
`status`	`string`	`"completed"` on success.
`unique_filename`	`string`	Session identifier.
`request_number`	`integer`	Echo of the request number sent.
`output_url`	`string`	CDN URL of the segmented image. Temporary — download promptly.
`message`	`string`	Human-readable status message.
`timestamp`	`number`	Unix timestamp (float) of when the response was generated.

Coming Soon

AI Background Generation

POST /v3/generate-ai-background/

Image Inpainting

POST /v3/inpaint/

Errors

All error responses use a consistent JSON envelope with a detail field describing the problem.

{
    "detail": "Insufficient credits. Required: 1.0, available: 0.0"
}

Status	Meaning	Common cause
`200`	OK	Request succeeded.
`400`	Bad Request	Missing required field, unsupported image format, malformed JSON body, or `jpg` format requested with transparent background.
`401`	Unauthorized	Missing, malformed, or revoked `Authorization` header. Check the `Bearer` prefix and key value.
`402`	Payment Required	Insufficient credits on the account.
`404`	Not Found	`unique_filename` does not exist or has expired. Re-upload the image.
`429`	Too Many Requests	Rate limit exceeded. Back off and retry after the interval specified in the `Retry-After` response header.
`500`	Internal Server Error	Unexpected server-side error. Retry with exponential backoff.
`503`	Service Unavailable	Server is temporarily overloaded. Retry after a short delay.
`504`	Gateway Timeout	Processing took too long. Try reducing `max_resolution` or using `"quality": "medium"`.

Remove BG Examples

Basic

Upload + process with all defaults.

Multiple Variants

Multiple outputs in one request.

Custom Background

Replace with solid colors.

Image Reuse

New variants without re-uploading.

AI Cut Examples

Basic

Point-based segmentation with refinement.

Documentation

Remove BG Examples

AI Cut Examples

Interactive Docs

BackgroundCut API v3

Authentication

Background Removal

Request

Form Fields

Response 200 OK

Request

Request Body

Example Body

Response 200 OK

Output Variant Fields

Presigned URL Endpoints

Presign Response

AI Cut

Request

Form Fields

Response 200 OK

Request

Request Body

Example Body

Response 200 OK

Coming Soon

Errors

Remove BG Examples

AI Cut Examples