▣ 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

http://localhost:8080/apyhub/change-image-background/multi-part/download

QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/apyhub/change-image-background/multi-part/download" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/sample.webp" \
  -F "background_image=@/path/to/background.jpg"

What you'll get back

Returns the generated image as a binary file.

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	Mandatory	Description
image	String	Yes	Subject image file (background removed server-side).
image_size	String	No	Optional `WidthxHeight` for resized subject after background removal.
image_angle	String	No	Rotation degrees 0–360 (string decimal).
image_opacity	String	No	Subject opacity 0–1 (string decimal).
image_position	ENUM	No	Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`.
background_size	String	No	Optional `WidthxHeight` for background canvas or resize target.
background_color	String	Yes (if background_image not given)	Hex color `#000000` (use instead of `background_image`).
background_image	String	Yes (if background_color not given)	Background image file (use instead of `background_color`).
background_opacity	String	No	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	Mandatory	Description
value	String	Yes	Binary PNG data returned by the endpoint.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

Body

Name

Type

Description

bodyREQUIRED

object

—

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

http://localhost:8080/apyhub/change-image-background/multi-part/link

QUICKSTARTGUIDE

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 "http://localhost:8080/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	Mandatory	Description
image	String	Yes	Subject image file (background removed server-side).
image_size	String	No	Optional `WidthxHeight` for resized subject after background removal.
image_angle	String	No	Rotation degrees 0–360 (string decimal).
image_opacity	String	No	Subject opacity 0–1 (string decimal).
image_position	ENUM	No	Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`.
background_size	String	No	Optional `WidthxHeight` for background canvas or resize target.
background_color	String	Yes (if background_image not given)	Hex color `#000000` (use instead of `background_image`).
background_image	String	Yes (if background_color not given)	Background image file (use instead of `background_color`).
background_opacity	String	No	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	Mandatory	Description
data	String	Yes	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.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

Body

Name

Type

Description

bodyREQUIRED

object

—

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

http://localhost:8080/apyhub/change-image-background/url/download

QUICKSTARTGUIDE

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 "http://localhost:8080/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.

body*

URL mode for change-background. Requires `image_url`. Provide either `background_color` (`#RRGGBB`) **or** `background_image_url` (fetched as an image) — not both. Optional layout fields mirror multipart form names.

image_url*

Foreground image URL (subject — background removed via rembg).

image_size

Optional `WidthxHeight` for resized subject after background removal.

image_angle

Rotation degrees 0–360 (string decimal).

image_opacity

Subject opacity 0–1 (string decimal).

image_position

Placement of the subject on the background canvas. Defaults to `center` when omitted.

background_size

Optional `WidthxHeight` for background canvas or resize target.

background_color

Hex color `#000000` (six hex digits with leading `#`). Use instead of `background_image_url` — only one background field may be present per request.

background_opacity

Background layer opacity 0–1 (string decimal).

background_image_url*

Background image URL. Use instead of `background_color` — only one background field may be present per request.

output

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	Mandatory	Description
image_url	String	Yes	Foreground image URL. Required. Must be a URI.
image_size	String	No	Optional `WidthxHeight` for the resized subject after background removal.
image_angle	String	No	Rotation degrees from 0 to 360, as a string decimal.
image_opacity	String	No	Subject opacity from 0 to 1, as a string decimal.
image_position	ENUM	No	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	No	Optional `WidthxHeight` for the background canvas or resize target.
background_color	String	Yes (if background_image not given)	Hex color in `#RRGGBB` format. Use instead of `background_image_url`; only one background field may be present per request.
background_opacity	String	No	Background layer opacity from 0 to 1, as a string decimal.
background_image_url	String	Yes (if background_color not given)	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	Mandatory	Description
response body	String	Yes	Binary image data returned by the endpoint.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

Body

Name

Type

Description

bodyREQUIRED

object

▣ ENDPOINT 04 / 04

POST

Change image background

http://localhost:8080/apyhub/change-image-background/url/link

QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/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.

body*

image_url*

Foreground image URL (subject — background removed via rembg).

image_size

Optional `WidthxHeight` for resized subject after background removal.

image_angle

Rotation degrees 0–360 (string decimal).

image_opacity

Subject opacity 0–1 (string decimal).

image_position

Placement of the subject on the background canvas. Defaults to `center` when omitted.

background_size

Optional `WidthxHeight` for background canvas or resize target.

background_color

Hex color `#RRGGBB` (six hex digits with leading `#`). Use instead of `background_image_url` — only one background field may be present per request.

background_opacity

Background layer opacity 0–1 (string decimal).

background_image_url*

Background image URL. Use instead of `background_color` — only one background field may be present per request.

output

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	Mandatory	Description
output	String	No	Output file name base. The schema does not define a fixed format or default.

Request Body

Parameter	Type	Mandatory	Description
image_url	String	Yes	Foreground image URL to fetch and process. Must be a URI.
image_size	String	No	Optional `WidthxHeight` for the resized subject after background removal.
image_angle	String	No	Rotation degrees from `0` to `360`, provided as a string decimal.
image_opacity	String	No	Subject opacity from `0` to `1`, provided as a string decimal.
image_position	ENUM	No	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	No	Optional `WidthxHeight` for the background canvas or resize target.
background_color	String	Yes (if background_image not given)	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	No	Background layer opacity from `0` to `1`, provided as a string decimal.
background_image_url	String	Yes (if `background_color` is omitted)	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	Mandatory	Description
data	String	Yes	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.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

Body

Name

Type

Description

bodyREQUIRED

object

▣ 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.