Image background removal

POST https://tools.yukai.uk/api/v1/image/remove-background

Remove the background of an image. Cuts out the main subject (people, products, animals, logos; hair and fur edges kept) with an AI segmentation model (BiRefNet on Cloudflare Images). The result is a transparent PNG (default) or WebP, or, with bg, the subject on a solid color (any format, including JPEG). crop=true trims the empty margin around the subject (keep some with cropMargin). Not made for screenshots and text documents: their white background is removed and text becomes semi-transparent. Typical time 2-8 seconds (10 seconds for a 20+ megapixel photo). Send an image URL (GET or POST), a base64 image (POST JSON), a file upload (POST multipart/form-data, field image) or the raw image bytes (POST with Content-Type: image/*, options in the query string). The answer is the image itself by default (response=json for metadata + base64). One call = one image. The same image with the same options is answered from a 24-hour cache.

Cost

Credits: 45 ($0.0045) per successful call. Failed calls are free. Source price: ai-image-toolkit/background-removed.

Input

Send a JSON body (POST) or the same fields as a query string (GET).

No field is required.

Field	Type	Default	Description
`url`	string		Public image URL (JPEG, PNG, WebP or GIF, up to 10 MB, 50 megapixels and 12,000 px per side). Private, local and cloud-metadata addresses are refused on every redirect. Alias: `imageUrl`. For POST you can send `image` (base64) or upload the file instead.
`format`	string	`"png"`	Result format. `png` and `webp` keep transparency; `jpeg` needs `bg`.
`bg`	string		Color for the removed background, e.g. `ffffff`, `#f5f5f5`, `rgb(0,0,0)` or `white`. Without it the background is transparent. Alias: `background`.
`crop`	boolean	`false`	Crop the result to the subject (trims the transparent margin).
`cropMargin`	integer	`0`	With crop=true: pixels of margin kept around the subject.
`maxSize`	integer		Longest side of the result in pixels; larger images are scaled down (never up), keeping the aspect ratio.
`quality`	integer	`90`	Quality for JPEG, WebP and AVIF (ignored for PNG, which is lossless). Default 90.
`response`	string	`"image"`	`image` (default): the response body is the image itself (`Content-Type: image/...`, metadata in `x-*` headers). `json`: JSON with the metadata and the image as base64 in `image` (results up to 15 MB).
`image`	string		The image itself as base64 or a data URL (`data:image/png;base64,...`), up to 10 MB decoded. POST only. Aliases: `imageBase64`, `base64`.

Examples

Replace tt_live_XXXX with your key from the pricing page.

curl

curl -i -X POST "https://tools.yukai.uk/api/v1/image/remove-background" \
  -H "Authorization: Bearer tt_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://upload.wikimedia.org/wikipedia/commons/thumb/2/28/Canon_EOS_5D_Mark_II_with_50mm_1.4_edit1.jpg/960px-Canon_EOS_5D_Mark_II_with_50mm_1.4_edit1.jpg","crop":true,"response":"json"}'

JavaScript (fetch)

const res = await fetch("https://tools.yukai.uk/api/v1/image/remove-background", {
  method: "POST",
  headers: { "Authorization": "Bearer tt_live_XXXX", "Content-Type": "application/json" },
  body: JSON.stringify({"url":"https://upload.wikimedia.org/wikipedia/commons/thumb/2/28/Canon_EOS_5D_Mark_II_with_50mm_1.4_edit1.jpg/960px-Canon_EOS_5D_Mark_II_with_50mm_1.4_edit1.jpg","crop":true,"response":"json"}),
});
console.log(res.status, res.headers.get("x-credits-charged"), res.headers.get("x-credits-balance"));
console.log(await res.json());

Python (requests)

import requests

r = requests.post(
    "https://tools.yukai.uk/api/v1/image/remove-background",
    headers={"Authorization": "Bearer tt_live_XXXX"},
    json={"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/2/28/Canon_EOS_5D_Mark_II_with_50mm_1.4_edit1.jpg/960px-Canon_EOS_5D_Mark_II_with_50mm_1.4_edit1.jpg", "crop": True, "response": "json"},
    timeout=120,
)
print(r.status_code, r.headers.get("x-credits-charged"), r.headers.get("x-credits-balance"))
print(r.json())

Response

JSON with "success": true and the result fields; on failure {"success": false, "error": {"code", "message", "retryable"}} and no credits are used. Every answer carries x-credits-charged (credits used) and x-credits-balance (balance after the call); check the balance any time with GET https://tools.yukai.uk/v1/billing/balance.

Full field list and response schema: OpenAPI spec image-tools (its servers entry is the marketplace gateway; call https://tools.yukai.uk with your key).

← All routes · Pricing