Edit Image
Apply one or more image editing operations, with optional background removal
Edit Image
Applies an ordered list of editing operations to an image — resize, rotate, flip, adjust blur/brightness/contrast/saturation, fill transparent areas with a color, remove the background, and trim — in a single request.
Endpoint
POST /images/editAuthentication
Every request requires your API key using the X-Api-Key header.
curl -X POST https://api.bgbuster.com/images/edit \
-H "X-Api-Key: your-api-key" \
-F "input=@photo.jpg" \
-F 'operations=[{"resize":{"width":800}},{"removeBackground":true},{"background":"white"}]'Request Body
| Field | Type | Required | Description |
|---|---|---|---|
input | File or string | Yes | Image file or public URL |
operations | JSON-encoded array (see below) | Yes | Ordered list of edit operations, 1-20 entries |
output | "url" or "raw" | No | Return URL or raw image (default: url) |
format | "png", "webp", "jpeg", "gif", or "avif" | No | Output format (default: png) |
quality | number (1-100) | No | Compression quality. Only applies to jpeg/webp; ignored for other formats |
anim | boolean | No | Preserve all frames of an animated gif/webp input. When false, only the first frame is used |
operations is a JSON-encoded string in the multipart form body, for example: operations='[{"resize":{"width":800}},{"removeBackground":true}]'.
Operations
Each entry in operations is an object with exactly one of the following keys. Array order is execution order — operations run in the sequence you provide them, including where removeBackground falls relative to the others.
| Key | Value | Description |
|---|---|---|
resize | { width?: number; height?: number; fit?: "contain" | "cover" | "scale-down" | "crop" } | Resize the image. Provide width and/or height (max 10000px each). fit controls how they're applied. |
rotate | 90, 180, or 270 | Rotates the image clockwise by this many degrees. |
flip | "h", "v", or "hv" | Flips the image horizontally, vertically, or both. |
blur | number (0-250) | Approximate Gaussian blur radius. 0 = no blur, 250 = maximum. |
brightness | number (≥0) | Brightness multiplier. 1.0 = no change, 0.5 = half brightness, 2.0 = twice as bright. |
contrast | number (≥0) | Contrast multiplier. 1.0 = no change. |
saturation | number (≥0) | Saturation multiplier. 1.0 = no change, 0 = grayscale, 2.0 = high saturation. |
background | string (CSS color) | Fills transparent areas of the image at this point in the pipeline. Accepts hex (#RGB/#RRGGBB/#RRGGBBAA), rgb()/rgba(), hsl()/hsla(), hwb(), or a named color (e.g. "red", "transparent"). Has no effect on an opaque image. |
removeBackground | true | AI background removal: sets every pixel outside the detected foreground subject to transparent, at this point in the pipeline. Skipped automatically if the image is already transparent. At most one removeBackground entry is allowed per request. |
trim | true | Automatically detects and trims a uniform-color border around the image, at this point in the pipeline. |
[!IMPORTANT]
Images transformed using URL output are available for download for up to 24 hours after they are created. These URLs are intended for temporary access only. You should not rely on them for persistent storage. Instead, download the transformed image and store it in your own storage system.
Response
When output is "url":
{
"id": "image-id",
"url": "https://..."
}When output is "raw", returns the image file directly.
Example
import fs from "node:fs";
const form = new FormData();
form.append("input", fs.createReadStream("photo.jpg"));
form.append("output", "url");
form.append(
"operations",
JSON.stringify([{ resize: { width: 800 } }, { removeBackground: true }, { background: "white" }])
);
const res = await fetch("https://api.bgbuster.com/images/edit", {
method: "POST",
headers: {
"X-Api-Key": process.env.API_KEY!,
},
body: form,
});
const data = await res.json();
console.log("Result:", data.url);Or using the SDK:
import { createClient } from "@bgbuster/sdk";
const client = createClient("your-api-key");
const result = await client.edit({
input: "https://example.com/photo.jpg",
output: "url",
operations: [{ resize: { width: 800 } }, { removeBackground: true }, { background: "white" }]
});
console.log(result.url);