▣ IMAGE PROCESSING

Change Image Background API

What it does

Change Image Background lets you replace the background behind a subject image and return a PNG with the new composition. Send either an image URL or a binary image, then choose a solid color background or a background image. You can also control subject size, rotation, opacity, placement, and background canvas size.

Use it when you need product shots on a clean color field, social cards with consistent branding, or quick mockups without editing in a design tool. The service removes the foreground background server-side, places the subject on the new background, and preserves the result as a PNG.

The URL endpoints accept image_url plus either background_color or background_image_url. The multipart endpoints accept image plus either background_color or background_image. Optional layout fields include image_size, image_angle, image_opacity, image_position, background_size, and background_opacity.

Depending on the endpoint, you get either a direct PNG download or a time-limited signed URL in data.

▣ ENDPOINT 01 / 04

POST

Change image background (fetch by URL, signed link)

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

QUICKSTART

GUIDE

Quickstart

Generate a background-changed image from a source image URL and a background image URL, and save the result under the given output name.

curl -X POST "https://api.eu.apyverse.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/sample.webp",
    "background_image_url": "https://assets.apyhub.com/samples/sample.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 · 30 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 `#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 a URL, removes its background, and composites it onto either a background image URL or a solid background color. The result is returned as a stored PNG accessible through a time-limited signed URL.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output filename / slug used for the generated asset URL.

Request Body

Parameter	Type	Mandatory	Description
image_url	String	Yes	Foreground image URL (subject — background removed via rembg). Must be a URI.
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	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 background canvas or resize target.
background_color	String	No	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	String	No	Background layer opacity 0–1 (string decimal).
background_image_url	String	No	Background image URL. Use instead of `background_color` — only one background field may be present per request. Must be a URI.

Response

Returns a JSON object with a data string field — a time-limited pre-signed URL to the generated PNG file. The URL is generated at request time and 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

▣ ENDPOINT 02 / 04

POST

Change image background (fetch foreground by URL, download PNG)

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

QUICKSTART

GUIDE

Quickstart

Create a background-change image from a foreground image URL and a background image URL.

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

What you'll get back

Returns binary image data as the generated output image.

TRY ITLIVE · 30 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 a URL, removes its background, and composites it onto either a solid-color background or a background image URL. The result is returned as a PNG download.

Request Body

Parameter	Type	Mandatory	Description
image_url	String	Yes	Foreground image URL (subject — background removed via rembg). Must be a URI.
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	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 background canvas or resize target.
background_color	String	No	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	String	No	Background layer opacity 0–1 (string decimal).
background_image_url	String	No	Background image URL. Use instead of `background_color` — only one background field may be present per request. Must be a URI.

Response

Returns a binary file download as the success response. The output schema is a binary string, so the response body is the PNG content itself.

Parameter	Type	Mandatory	Description
binary	String	Yes	Binary PNG content returned by the endpoint.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

Body

Name

Type

Description

bodyREQUIRED

object

▣ ENDPOINT 03 / 04

POST

Change image background (multipart, download PNG)

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

QUICKSTART

GUIDE

Quickstart

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

curl -X POST "https://api.eu.apyverse.com/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 a binary file containing the generated image.

TRY ITLIVE · 30 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 either a background image or a background color, then returns the composited result as a downloadable PNG file. Optional body fields let you resize, rotate, position, and adjust opacity for the subject and background layers.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Download name for the output file.

Request Body

Parameter	Type	Mandatory	Description
image	String	Yes	Subject image file to process. Background removal is performed server-side.
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	Subject placement on the canvas. Allowed values: `top_right`, `top_left`, `bottom_right`, `bottom_left`, `center`.
background_size	String	No	Optional `WidthxHeight` for the background canvas or resize target.
background_color	String	No	Hex color in `#RRGGBB` format. Use this instead of `background_image`.
background_image	String	Yes	Background image file. Use this instead of `background_color`.
background_opacity	String	No	Background layer opacity from 0 to 1, as a string decimal.

Response

Returns a binary file response containing the generated PNG image. The output schema is a binary string, so the response body is the file itself rather than a JSON object.

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 04 / 04

POST

Change image background (multipart, signed URL)

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

QUICKSTART

GUIDE

Quickstart

Upload a subject image and get back a signed PNG URL with a simple multipart request.

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

What you'll get back

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

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

TRY ITLIVE · 30 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

Changes an image’s background by sending a subject image plus optional background and composition settings. On success, it returns a JSON object containing a pre-signed URL to the generated PNG file.

Request Body

Parameter	Type	Mandatory	Description
image	String	Yes	Subject image (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	No	Hex color `#RRGGBB` (use instead of `background_image`).
background_image	String	No	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 formatted as a URI. The data value is a pre-signed URL to the stored PNG file, and it is time-limited rather than a stable public asset link.

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.

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