Background

Background replacement and removal. Works on any image, generated or uploaded.

Both endpoints return a job_id with a matching GET …/status/{job_id} route, see Jobs.

Change background

POST /background/change/image/v1, replace the background of input_image, described by prompt. Commonly used mid-workflow, for example Generate → Background → Upscale to stage a product shot, then sharpen it.

cURL

curl -X POST https://api.imagepipeline.io/background/change/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_image": "https://.../product.webp",
  "prompt": "on a sunlit marble kitchen counter",
  "output_format": "webp"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/background/change/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "input_image": "https://.../product.webp",
  "prompt": "on a sunlit marble kitchen counter",
  "output_format": "webp"
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/background/change/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "input_image": "https://.../product.webp",
  "prompt": "on a sunlit marble kitchen counter",
  "output_format": "webp"
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/background/change/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "input_image": "https://.../product.webp",
  "prompt": "on a sunlit marble kitchen counter",
  "output_format": "webp"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
input_image	string	,	Required. Public URL of the image to restage.
prompt	string	,	Required. Describe the new background, e.g. beach at sunset.
use_segmentation	boolean	true	Isolate the subject via BiRefNet before compositing.
subject_description	string	,	Short description of the subject to preserve.
tone_correction	number	,	Blends the edited background tones (0.0 to 1.0).
has_text	boolean	,	Whether the image contains visible text or labels.
seed	integer	-1	-1 randomizes; set a value for reproducibility.
output_format	string	webp	webp, jpeg, or png.
callback_url	string	,	Receive a webhook on completion.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_2a6d9f81",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/2a6d9f81.webp",
  "processing_time_seconds": 31.5,
  "balance_remaining_usd": 187.52
}

Remove background

POST /background/remove/image/v1, cut the subject out of input_image. Leave the background transparent, or pass recolor to drop the subject on a solid colour with an optional grounding shadow.

cURL

curl -X POST https://api.imagepipeline.io/background/remove/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_image": "https://.../product.webp",
  "recolor": "#F0F0F0",
  "drop_shadow": true
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/background/remove/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "input_image": "https://.../product.webp",
  "recolor": "#F0F0F0",
  "drop_shadow": true
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/background/remove/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "input_image": "https://.../product.webp",
  "recolor": "#F0F0F0",
  "drop_shadow": True
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/background/remove/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "input_image": "https://.../product.webp",
  "recolor": "#F0F0F0",
  "drop_shadow": true
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
input_image	string	,	Required. Public URL of the image to process.
recolor	string	,	Hex colour for the new background, e.g. #FFFFFF. Omit for transparent.
drop_shadow	boolean	false	Add a soft drop shadow beneath the subject.
shadow_opacity	number	0.38	Shadow darkness (0 to 1).
shadow_blur	number	0.018	Blur radius as a fraction of image width.
shadow_dy	number	0.022	Vertical shadow offset as a fraction of height.
shadow_dx	number	0.004	Horizontal shadow offset as a fraction of width.
output_format	string	webp	webp, jpeg, or png.
callback_url	string	,	Receive a webhook on completion.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_e3b0f72c",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/e3b0f72c.webp",
  "processing_time_seconds": 12.8,
  "balance_remaining_usd": 187.52
}