BackgroundCut API v3 Beta

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

Warning: API v3 is currently in beta and may have breaking changes without notice. Do not integrate it into production or any live application. You are welcome to test and experiment with it, but treat all endpoints as unstable until a stable release is announced.

Quick Start Get API Key API Explorer ↗

Key-based Storage

Upload files under keys you choose (e.g. my-project/photo.jpg). Storage is regional (not global) and ephemeral. All files are hard-deleted after 2 hours.

Output Variants

Generate multiple sizes, formats, and background colors in a single process request. Each variant gets its own key in your space.

Public URLs

Your space is private. Mint a short-lived public URL for any file via POST /v3/file-ops/get-public-url/ to share or display results without an auth header.

Infrastructure

Regional storage, not global. api.backgroundcut.co is a geodistributed system managed by GeoDNS. Every request is automatically routed to the nearest available regional server. File storage is regional: a file uploaded to one server is stored only on that server and is not replicated to any other region.

If your upload and your subsequent process or download requests happen to route to different regional servers, the file will not be found and you will receive a 404 Not Found. This can happen even within the same session if network conditions change.

Recommendation: Always complete an upload and all operations that depend on it within the same session, from the same location. Do not assume a file uploaded in one request is accessible from a different server.

Ephemeral storage, 2-hour hard limit. All uploaded files are automatically and permanently deleted after 2 hours. This is a hard system-wide limit with no option to extend it.

The storage layer is intentionally short-lived. Regional clusters are brought up and down on a rolling basis and files are not preserved across cluster lifecycle events. If the server where you uploaded a file goes offline before the 2-hour TTL is reached, that file may be lost immediately.

Do not treat this as persistent storage. The intended workflow is: upload an image, run a tool, mint a public URL for the result, download it to your own storage, then discard. Persist any outputs you need before the 2-hour window closes.

Authentication

All requests require an Authorization header. Get your API key from the Dashboard.

Credential	Header format	When to use
API key	`Authorization: Token YOUR_API_KEY`	Server-to-server calls
Access token	`Authorization: AccessToken <token>`	Client-side calls (browser, mobile)

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

Base URL

https://api.backgroundcut.co

All endpoint paths below are relative to this base URL.

File Storage

Your space is flat and S3-like. You control the key (full object name including any slashes); slashes are part of the key name, not directories.

Upload a file by specifying the key you want it stored under: key=my-project/photo.jpg. You already know the key, so no need to read it from the upload response.

Pass the same key as input_key to tool endpoints. Output files are stored under the output_key you specify in each variant.

To access a result, call POST /v3/file-ops/get-public-url/ with the key. This returns a short-lived presigned URL that serves the file directly from the edge. Drop it into a browser, <img src="">, or any HTTP client without an Authorization header. The URL stops working after ~2 hours.

Storage quota

10 GB default across your space.

File expiry

Hard limit: 2 hours. All files are automatically deleted after 2 hours. Set a shorter TTL via expires_in_hours at upload time, but the 2-hour cap is always enforced.

Access Tokens

Mint short-lived tokens scoped to specific endpoints so clients can call the API without your secret key.

POST /v3/auth/access-token/

Returns a short-lived token your client can use in the Authorization: AccessToken <token> header. The token is restricted to the paths you list and expires after the configured TTL.

Request

Header	Value
`Authorization`	`Token YOUR_API_KEY`
`Content-Type`	`application/json`

Request Body

Field	Type	Default	Description
`paths`	`string[]`	`["*"]`	Glob patterns restricting which endpoints this token may call. `""` allows all. e.g. `["/v3/tools/ai/remove-bg/"]`.
`expires_in`	`integer`	`60`	Token lifetime in seconds (1–600). Mint tokens immediately before use — do not store them.

Example Body

{
    "paths": [
        "/v3/file-ops/upload/",
        "/v3/file-ops/get-public-url/",
        "/v3/tools/ai/remove-bg/process/",
        "/v3/tools/ai/ai-cut/segment/"
    ],
    "expires_in": 600
}

Response 200 OK

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Send the value in the Authorization: AccessToken <token> header on the client. Tokens are scoped to the requested paths only — calls to other endpoints are rejected.

File Operations

Manage files in your storage space. All endpoints require Authorization: Token YOUR_API_KEY.

POST /v3/file-ops/upload/

Upload a single image file to your space under the key you choose. Accepts JPEG, PNG, WebP, AVIF, HEIC/HEIF.

Form Fields

Field	Type	Required	Description
`file`	`file`	required	A single image file. JPEG, PNG, WebP, AVIF, HEIC/HEIF accepted. 50 MB max.
`key`	`string`	required	Full object key including filename (e.g. `my-project/photo.jpg`). Slashes are part of the key name, not directories. Overwrite-safe: uploading to an existing key replaces it.
`expires_in_hours`	`integer`	optional	Auto-delete after this many hours. Omit for default (2-hour hard cap always applies).

Response 200 OK

{
    "success": true,
    "message": "File uploaded."
}

The file is stored under exactly the key you provided. You already know the key — pass it directly as input_key to tool endpoints.

POST /v3/file-ops/get-public-url/

Mint a public URL for a file in your space. Your space is private. This returns a short-lived presigned URL that grants time-limited read access to the file, served directly from the edge. No Authorization header needed. The signature is unguessable and self-expiring: the URL stops working after ~2 hours (or sooner if the underlying file hits its 2-hour TTL), returning a 403/404. Call this again to mint a fresh URL.

Request Body

{
    "key": "my-project/result.png"
}

Response 200 OK

{
    "url": "https://cdn.backgroundcut.co/pub/abc123.../result.png"
}

Drop the URL directly into a browser, <img src="">, or any HTTP client. No auth header required. Returns 404 if the key does not exist.

GET /v3/file-ops/list/

List all files as a flat array of keys. Optional pattern query param accepts glob (e.g. my-project/*.jpg). Returns {"keys": [...]}.

POST /v3/file-ops/copy/

Copy a file to a new key within your space. Body: source_key, destination_key.

POST /v3/file-ops/delete/

Delete one or more files. Body: pattern (exact key or glob like my-project/*). Returns {"deleted_count": N}. Succeeds silently if no files match.

Background Removal

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

POST /v3/tools/ai/remove-bg/process/

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

Request

Header	Value
`Authorization`	`Token YOUR_API_KEY`
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`input_key`	`string`	required	The key of the uploaded image (e.g. `my-project/photo.jpg`).
`output_variants`	`array`	required	1–10 output configurations. Each must include `output_key`.

Example Body

{
    "input_key": "my-project/photo.jpg",
    "output_variants": [
        {
            "output_key": "my-project/full.png",
            "format": "png",
            "max_resolution": 12000000,
            "quality": "high",
            "background_color": null,
            "output_compression": 85,
            "autocrop": false
        },
        {
            "output_key": "my-project/thumb.webp",
            "format": "webp",
            "max_resolution": 250000,
            "quality": "medium",
            "background_color": "#ffffff",
            "output_compression": 80,
            "autocrop": true
        }
    ]
}

Response 200 OK

{
    "output_keys": [
        "my-project/full.png",
        "my-project/thumb.webp"
    ]
}

Field	Type	Description
`output_keys`	`string[]`	Ordered list of output keys in your space, one per variant. Mint a public URL via `POST /v3/file-ops/get-public-url/` to access the result.

Output Variant Fields

Each object in output_variants must include output_key. All other fields are optional.

Field	Type	Default	Description
`output_key`	`string`	—	required Destination key in your space (e.g. `my-project/result.png`).
`format`	`string`	`"png"`	Output file format. Options: `png`, `jpeg`, `jpg`, `webp`. Use PNG/WebP for transparency; JPEG always gets a fill color.
`max_resolution`	`integer`	`12000000`	Maximum pixel count (width × height). Range: `4096`–`25000000`. Output is scaled down proportionally if the source exceeds this.
`background_color`	`string \| null`	`null`	Fill color: `"#fff"`, `"#ffffff"`, `"#ffffff80"` (with alpha). `null` = transparent. JPEG always gets a fill (white by default).
`quality`	`string`	`"medium"`	AI processing quality. Options: `"high"`, `"medium"`, `"low"`. Higher quality takes longer but produces cleaner edges.
`output_compression`	`integer`	`85`	Encoder quality for lossy formats (1–100). Ignored for PNG (always lossless).
`autocrop`	`boolean`	`false`	Crop the output tightly to the subject, removing empty transparent/background margins.

AI Cut

Point-based interactive segmentation. Upload an image, then segment it using foreground and background point hints.

Input and output must be JPEG. Pass a .jpg or .jpeg key in both input_key and output_key.

Send one request at a time. Processing can take a few seconds. Buffer clicks on the client and send the next request only after the current one completes.

POST /v3/tools/ai/ai-cut/segment/

Segment a previously uploaded JPEG image using point hints. The call blocks until the result is ready (~3 s). The output is written to output_key in your space.

Request

Header	Value
`Authorization`	`Token YOUR_API_KEY`
`Content-Type`	`application/json`

Request Body

Field	Type	Default	Description
`input_key`	`string`	—	required Key of the source JPEG in your space.
`output_key`	`string`	—	required Destination key for the result. Must end in `.jpg` or `.jpeg`.
`foreground_points`	`array`	`[]`	Points to include in the selection. Each item: `{"x": int, "y": int}` in image pixels. More points improve accuracy.
`background_points`	`array`	`[]`	Points to exclude from the selection. Same format as `foreground_points`.

Example Body

{
    "input_key": "my-project/photo.jpg",
    "output_key": "my-project/segment.jpg",
    "foreground_points": [{"x": 250, "y": 300}, {"x": 260, "y": 310}],
    "background_points": [{"x": 50, "y": 50}]
}

Response 200 OK

{
    "output_key": "my-project/segment.jpg"
}

Field	Type	Description
`output_key`	`string`	Key of the segmented output in your space. Mint a public URL via `POST /v3/file-ops/get-public-url/` to access it.

Recommended client flow: User clicks → add to local buffer, send a request with all points so far. While in-flight, collect more clicks but do not send. When response arrives, send the accumulated buffer if non-empty.

Coming Soon

AI Background Generation

POST /v3/tools/ai/generate-ai-background/

Image Inpainting

POST /v3/tools/ai/inpaint/

Image Format Conversion

POST /v3/tools/image/convert/

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
`400`	Bad Request	Missing required field, unsupported image format, malformed JSON, non-JPEG path for AI Cut, or JPEG format with transparent background.
`401`	Unauthorized	Missing, malformed, or revoked `Authorization` header. Check the `Token` prefix and key value.
`402`	Payment Required	Insufficient credits on the account.
`404`	Not Found	`input_key` does not exist. The file may have expired (2-hour TTL), been deleted, or was uploaded to a different regional server. Re-upload the image in the same request session.
`413`	Payload Too Large	File exceeds the 50 MB per-file limit.
`415`	Unsupported Media Type	File is not an accepted image format (JPEG, PNG, WebP, AVIF, HEIC/HEIF).
`429`	Too Many Requests	Rate limit exceeded. Back off and retry after the `Retry-After` response header interval.
`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": "low"`.
`507`	Insufficient Storage	Upload would exceed your 10 GB storage quota.

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.

API v3 Beta

Remove BG Examples

AI Cut Examples

Interactive Docs

BackgroundCut API v3 Beta

Infrastructure

Authentication

File Storage

Access Tokens

Request

Request Body

Example Body

Response 200 OK

File Operations

Form Fields

Response 200 OK

Request Body

Response 200 OK

Background Removal

Request

Request Body

Example Body

Response 200 OK

Output Variant Fields

AI Cut

Request

Request Body

Example Body

Response 200 OK

Coming Soon

Errors

Remove BG Examples

AI Cut Examples