BackgroundCut API v3 Beta

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

File Storage

Upload files with paths you control (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 file path in your space.

Access Tokens

For client-side integrations, your server mints scoped short-lived tokens so your API key is never exposed to the browser.

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, download the result, then discard. Persist any outputs you need to your own storage 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

Each account has a persistent storage space. You control file paths; the API stores and retrieves by those paths.

Upload files with a path you choose: upload_path=my-project stores the file as my-project/<detected-name>.<ext>. The same path is passed directly to tool endpoints as input_file_path.

Output files are also stored in your space at the path you specify in output_file_path for each variant. You can then download them, copy them, or delete them via the File Operations endpoints.

To download a file, send GET /v3/files/{path} with your API key. Direct browser access without an Authorization header will return 401.

Storage quota

10 GB default. Check usage at GET /v3/file-ops/usage/.

File expiry

Hard limit: 2 hours. All files are automatically deleted after 2 hours regardless of any other setting. You may set a shorter TTL via expires_in_hours, 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/tools/ai/remove-bg/process/",
        "/v3/tools/ai/ai-cut/segment/",
        "/v3/files/*"
    ],
    "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 one or more image files to your space. Accepts JPEG, PNG, WebP, AVIF. Returns the paths the files were stored at.

Form Fields

Field	Type	Required	Description
`files`	`file[]`	required	One or more image files. JPEG, PNG, WebP, AVIF accepted. 50 MB per file max.
`upload_path`	`string`	required	Destination folder (e.g. `my-project`). Each file is stored as `{upload_path}/{stem}.{ext}`.
`expires_in_hours`	`integer`	optional	Auto-delete after this many hours. Omit for no expiry.

Response 200 OK

{
    "file_paths": ["my-project/photo.jpg"]
}

Pass file_paths[0] directly as input_file_path in tool endpoints.

GET /v3/files/{path}

Download a file from your space. Response body is the raw file bytes with original Content-Type. Requires Authorization header — browsers cannot fetch these URLs directly without it.

GET /v3/file-ops/list/

List all files as a flat array. Optional pattern query param accepts glob (e.g. my-project/*.jpg).

GET /v3/file-ops/info/

Get metadata for one file: size, content type, dimensions, expiry. Pass file_path as a query parameter.

GET /v3/file-ops/usage/

Returns used_bytes, file_count, quota_bytes, and quota_used_pct.

POST /v3/file-ops/copy/

Copy a file to a new path. Body: source_path, destination_path.

POST /v3/file-ops/delete/

Delete a single file. Body: file_path. Succeeds silently if the file does not exist.

POST /v3/file-ops/delete-folder/

Delete a folder and all its contents. Body: folder_path. Returns deleted_count.

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 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_file_path`	`string`	required	The file path from the upload response (e.g. `my-project/photo.jpg`).
`output_variants`	`array`	required	1–10 output configurations. Each must include `output_file_path`.

Example Body

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

Response 200 OK

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

Field	Type	Description
`output_file_paths`	`string[]`	Ordered list of output file paths in your space, one per variant. Download via `GET /v3/files/{path}`.

Output Variant Fields

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

Field	Type	Default	Description
`output_file_path`	`string`	—	required Destination path in your space (e.g. `my-project/result.png`).
`format`	`string`	`"png"`	Output file format. Options: `png`, `jpeg`, `jpg`, `webp`, `avif`. Use PNG/WebP/AVIF 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`	`"high"`	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 file path in both input_file_path and output_file_path.

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_file_path in your space.

Request

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

Request Body

Field	Type	Default	Description
`input_file_path`	`string`	—	required Path of the source JPEG in your space.
`output_file_path`	`string`	—	required Destination path 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_file_path": "my-project/photo.jpg",
    "output_file_path": "my-project/segment.jpg",
    "foreground_points": [{"x": 250, "y": 300}, {"x": 260, "y": 310}],
    "background_points": [{"x": 50, "y": 50}]
}

Response 200 OK

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

Field	Type	Description
`output_file_path`	`string`	Path of the segmented output in your space. Download via `GET /v3/files/{path}`.

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, 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_file_path` 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).
`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": "medium"`.
`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

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