Background removal API

Quick start

Create an account and generate an API key. Save a product photo as product.jpg, set FRAMELARK_API_KEY in your environment, and run an example below.

One request returns the finished image. These examples use a free preview with a white background. Use a file under 4 MB; see large images for URL and direct uploads.

# Export FRAMELARK_API_KEY before running.
curl --fail-with-body --max-time 260 '/v1.0/removebg' \
  -H "X-Api-Key: $FRAMELARK_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'size=preview' \
  -F 'bg_color=fff' \
  -F 'format=png' \
  --output product-clean.png

Requires cURL. Remove bg_color for transparency. Set size=full for full resolution.

Migrating from remove.bg

For supported remove.bg workflows, use /v1.0/removebg and replace your X-Api-Key with a FrameLark key from your account. This endpoint defaults to a transparent preview and returns the completed image synchronously. Use GET /v1.0/account for your image balance and remaining free previews.

curl --fail-with-body '/v1.0/removebg' \
  -H 'X-Api-Key: YOUR_NEW_API_KEY' \
  -F 'image_file=@product.jpg' \
  -F 'size=auto' \
  -F 'format=png' \
  --output product-clean.png

Send a file, image_file_b64, or a public image_url using multipart, JSON, or URL-encoded requests. Outputs include PNG, JPG, WebP, ZIP, alpha masks, and base64 JSON with Accept: application/json. Crop, margins, region of interest, scale, position, and replacement backgrounds are supported. Errors use {errors:[{code,title}]}; invalid API keys return 403.

Test your image set before switching. Foreground type selection, classification headers, generated AI shadows, disabling semitransparency, and API OAuth are not supported. Segmentation results may differ. On the current hosting, multipart and base64 requests must fit its 4.5 MB request limit; use image URLs for larger images, up to 22 MB and 50 megapixels.

Authentication

Include your API key in the X-Api-Key header. Create and revoke keys in your account. API requests use the same image balance as website downloads.

X-Api-Key: YOUR_API_KEY

Store your key in a server environment variable. Browser applications should call your own server so the key stays private.

Request parameters

Send multipart, JSON, or URL-encoded data. Binary file uploads use multipart; your HTTP client supplies the boundary.

Full-resolution images use one image from your balance. Failed processing uses none. The first 50 successful API previews per UTC calendar month are free; subsequent previews use 0.25 images each.

Large images and direct uploads

For the simplest large-image request, provide a public image URL. The server downloads it directly, so the request body stays small.

{
  "image_url": "https://example.com/product.jpg",
  "size": "full",
  "bg_color": "fff",
  "format": "png"
}

For private files, the asynchronous upload API below accepts direct uploads and delivers a full-resolution PNG up to 50 MP. It uses a separate request and polling contract.

Upload files over 4 MB directly to storage. The same flow works for smaller images and supports files up to 22 MB and 50 megapixels.

1. Request an upload URL. Send the following JSON to POST /api/uploads/presign with your X-Api-Key header. Set size to the exact file size in bytes.

{
  "contentType": "image/jpeg",
  "size": 5230012
}

2. Upload the file. Send the raw file with PUT to the returned uploadUrl, using the returned headers. Send your API key only to our API, without including it in this storage request.
3. Start processing. Send the following JSON to POST /api/v1/remove-bg with your X-Api-Key header.

{
  "uploadId": "RETURNED_UPLOAD_ID",
  "background": "white",
  "size": "full"
}

The response follows the same status and download rules as a multipart request.

Responses

POST /v1.0/removebg returns a finished image with HTTP 200. Save the binary body directly. It waits for processing and never returns a pending image as a successful result.

HTTP/1.1 200 OK
Content-Type: image/png
X-Width: 1600
X-Height: 1067
X-Credits-Charged: 1
X-Image-Id: YOUR_IMAGE_ID

Image dimensions, foreground bounds, charged images, and per-minute rate-limit information are included in response headers. Set Accept: application/json for base64 output:

{
  "data": {
    "result_b64": "BASE64_ENCODED_IMAGE",
    "foreground_top": 0,
    "foreground_left": 0,
    "foreground_width": 1600,
    "foreground_height": 1067
  }
}

Account and image submissions

GET /v1.0/account returns data.attributes.credits with the total, subscription, and payg balances, plus data.attributes.api.free_calls. These compatibility field names match existing clients. POST /v1.0/improve accepts an image source, optional image_filename and tag, and returns its submission ID. It stores your explicit submission for review for 24 hours; it does not train a model automatically.

Asynchronous direct-upload API

POST /api/v1/remove-bg uses size=full|preview and background=white|transparent, defaults to full and white, and returns PNG. Use a multipart image_file or JSON uploadId from the direct-upload flow above.

{
  "id": "YOUR_IMAGE_ID",
  "status": "pending",
  "statusUrl": "/api/uploads/YOUR_IMAGE_ID",
  "downloadUrl": "/api/uploads/YOUR_IMAGE_ID/download?size=full&background=white"
}

If that endpoint returns 202, follow Retry-After: 3 and poll statusUrl with your API key until completed or failed. Download from downloadUrl after completion. Large PNG downloads return 303; fetch the short-lived storage Location separately without your API key. Downloading the same completed image again does not spend another image. Save results within 24 hours.

Errors and limits

Errors return JSON. Check the HTTP status before saving the response as an image. The asynchronous direct-upload API uses its own {error:{code,message}} envelope and returns 401 for invalid API keys.

{
  "errors": [
    {
      "code": "insufficient_credits",
      "title": "Insufficient credits"
    }
  ]
}

The compatible endpoint allows 500 input megapixels per minute per account, rounded up per image. Rate-limit responses include Retry-After and X-RateLimit headers. The asynchronous direct-upload API allows 100 requests per account per hour. Use a queue for batches and space out retries.