▣ FILE MANIPULATION

Change Background of Images API

Hosted on ApyHub

What it does

Change Image Background lets you place a subject image onto a new background and get back a PNG. Send either a multipart upload or image URLs, then choose a solid background color or a background image, along with optional sizing, rotation, opacity, and placement settings.

Use the multipart endpoints when you already have the files in hand, or the URL endpoints when your images live elsewhere. The request schemas support a foreground image plus either background_color or a background image input. You can also adjust image_size, image_angle, image_opacity, image_position, background_size, and background_opacity to control the final composition.

The service removes the subject background server-side before compositing, which makes it useful for product shots, profile images, marketplace listings, and social assets. If you want a direct file response, use the download endpoints, which return the generated PNG as binary data.

If you prefer a hosted result, use the signed-link endpoints. Those return a data field containing a time-limited pre-signed URL to the generated PNG, suitable for storage or immediate download.

▣ ENDPOINT 01 / 04

POST

Change image background

https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/download

QUICKSTART

GUIDE

Quickstart

Upload a subject image and a background image to generate a composited image download.

curl -X POST "https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/download?output=file" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/sample.webp" \
  -F "background_image=@/path/to/background.jpg" \
  -o composited-image.png

What you'll get back

Returns the generated image as a binary file response.

The example above saves the downloaded file locally as composited-image.png.

TRY ITLIVE · 2000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Uploads a subject image and a background image, then returns the generated result as a PNG binary download with the background changed. The request body accepts multipart file and option fields for sizing, rotation, opacity, placement, and background selection.

Request Body

Parameter	Type	Description
image	Binary	Subject image file (background removed server-side).
image_size	String	Optional `WidthxHeight` for resized subject after background removal.
image_angle	String	Rotation degrees 0–360 (string decimal).
image_opacity	String	Subject opacity 0–1 (string decimal).
image_position	ENUM	Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`.
background_size	String	Optional `WidthxHeight` for background canvas or resize target.
background_color	String	Hex color `#000000` (use instead of `background_image`).
background_image	Binary	Background image file (use instead of `background_color`).
background_opacity	String	Background layer opacity 0–1 (string decimal).

Response

Returns a binary file response containing the generated PNG image. The output schema is a single binary string, so there is no JSON wrapper or named response fields to read.

Attribute	Type	Description
value	String	Binary PNG data returned by the endpoint.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 02 / 04

POST

Change image background

https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/link

QUICKSTART

GUIDE

Quickstart

Upload a subject image and an optional background image to generate a new composite, returning a signed URL for the result.

curl -X POST "https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/link?output=my-invite" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/sample.webp" \
  -F "background_image=@/path/to/background.jpg"

What you'll get back

Returns a JSON object with a data string field containing a pre-signed URI to the generated PNG file.

{
  "data": "https://storage.example.com/change-background/my-invite.png?X-Amz-Signature=abc123&X-Amz-Expires=3600"
}

TRY ITLIVE · 2000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Uploads a subject image and optional background settings as multipart form data, then returns a pre-signed URL for the generated PNG file. The response contains the data field with the time-limited storage URL for the processed image.

Request Body

Parameter	Type	Description
image	Binary	Subject image file (background removed server-side).
image_size	String	Optional `WidthxHeight` for resized subject after background removal.
image_angle	String	Rotation degrees 0–360 (string decimal).
image_opacity	String	Subject opacity 0–1 (string decimal).
image_position	ENUM	Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`.
background_size	String	Optional `WidthxHeight` for background canvas or resize target.
background_color	String	Hex color `#000000` (use instead of `background_image`).
background_image	Binary	Background image file (use instead of `background_color`).
background_opacity	String	Background layer opacity 0–1 (string decimal).

Response

Returns a JSON object with a data string field containing a pre-signed URI to the generated PNG file. The URL is time-limited and signed, so it should be treated as an expiring download link rather than a stable public asset.

Attribute	Type	Description
data	String	Pre-signed URL to the stored PNG file. Always present on a 200 response. The URL is time-limited and signed — it is not a stable public asset link.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 03 / 04

POST

Change image background

https://api.eu.apyhub.com/apyhub/change-image-background/url/download

QUICKSTART

GUIDE

Quickstart

Generate a composed image from a foreground image URL and a background image URL, then optionally name the output with a query parameter.

curl -X POST "https://api.eu.apyhub.com/apyhub/change-image-background/url/download?output=my-invite" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://assets.apyhub.com/samples/background-sample.jpeg",
    "background_image_url": "https://assets.apyhub.com/samples/background-image.jpg"
  }'

What you'll get back

Returns a binary file (string with format: binary) containing the generated image. There is no JSON wrapper in the response.

TRY ITLIVE · 2000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Fetches a foreground image from a URL, removes its background, and composites it onto either a solid-color background or a background image. The result is returned as a binary file download.

Request Body

Parameter	Type	Description
image_url	String	Foreground image URL. Required. Must be a URI.
image_size	String	Optional `WidthxHeight` for the resized subject after background removal.
image_angle	String	Rotation degrees from 0 to 360, as a string decimal.
image_opacity	String	Subject opacity from 0 to 1, as a string decimal.
image_position	ENUM	Placement of the subject on the background canvas. Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`. Defaults to `center` when omitted.
background_size	String	Optional `WidthxHeight` for the background canvas or resize target.
background_color	String	Hex color in `#RRGGBB` format. Use instead of `background_image_url`; only one background field may be present per request.
background_opacity	String	Background layer opacity from 0 to 1, as a string decimal.
background_image_url	String	Background image URL. Must be a URI. Use instead of `background_color`; only one background field may be present per request.

Response

Returns a binary file containing the generated image. The output schema is a single binary string, so the response body is the file content itself.

Parameter	Type	Description
response body	String	Binary image data returned by the endpoint.

▣ ENDPOINT 04 / 04

POST

Change image background

https://api.eu.apyhub.com/apyhub/change-image-background/url/link

QUICKSTART

GUIDE

Quickstart

Generate a PNG from an image URL and place it on a background image.

curl -X POST "https://api.eu.apyhub.com/apyhub/change-image-background/url/link?output=my-invite" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://assets.apyhub.com/samples/background-sample.jpeg",
    "background_image_url": "https://assets.apyhub.com/samples/background-image.jpg"
  }'

What you'll get back

Returns a JSON object with a data string field containing a time-limited pre-signed URL to the generated PNG file.

{
  "data": "https://storage.example.com/change-background/my-invite.png?X-Amz-Signature=abc123&X-Amz-Expires=3600"
}

TRY ITLIVE · 2000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Fetches a foreground image from image_url, removes its background, and composites it onto either a background image or a solid background color. The result is returned as a time-limited signed URL to a PNG file.

Query Parameter(s)

Attribute	Type	Description
output	String	Output file name base. The schema does not define a fixed format or default.

Request Body

Parameter	Type	Description
image_url	String	Foreground image URL to fetch and process. Must be a URI.
image_size	String	Optional `WidthxHeight` for the resized subject after background removal.
image_angle	String	Rotation degrees from `0` to `360`, provided as a string decimal.
image_opacity	String	Subject opacity from `0` to `1`, provided as a string decimal.
image_position	ENUM	Placement of the subject on the background canvas. Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`. Defaults to `center` when omitted.
background_size	String	Optional `WidthxHeight` for the background canvas or resize target.
background_color	String	Background color as a hex value in `#000000` format. Use instead of `background_image_url`; only one background field may be present per request.
background_opacity	String	Background layer opacity from `0` to `1`, provided as a string decimal.
background_image_url	String	Background image URL to fetch and use as the background. Must be a URI. Use instead of `background_color`; only one background field may be present per request.

Response

Returns a JSON object with a data string field containing a time-limited pre-signed URI to the generated PNG file. The data URL is generated at request time and expires, so it is not a stable public asset link.

Parameter	Type	Description
data	String	Time-limited pre-signed URL to the stored PNG file. Always present on a 200 response. The URL is generated and signed at request time and will expire.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLRemove Background from Images APIApyHub CALLRemove Image Background with Advanced Controls APICallable Labs CALLGenerate Image Foreground Mask APICallable Labs CALLImage to PDF API: Convert JPG, PNG, and MoreApyHub

From the blog

Reads that touch this API.

Top Image Editing APIs for 2026Sep 18, 2026 Top Video Watermarking APIs You Should Explore in 2026Jul 30, 2026 PUT vs PATCH: The Difference in REST APIs, with ExamplesSep 29, 2026 Generating Video Thumbnails with ApyHub’s API (Go Guide)Aug 7, 2026