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 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"
  }'

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.

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 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
  }'

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.