apyhub
Back
▣ 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
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.
Foreground image URL (subject — background removed via rembg).
Background image URL. Use instead of `background_color` — only one background field may be present per request.
Optional `WidthxHeight` for resized subject after background removal.
Rotation degrees 0–360 (string decimal).
Subject opacity 0–1 (string decimal).

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)

AttributeTypeMandatoryDescription
outputStringNoOutput filename / slug used for the generated asset URL.

Request Body

ParameterTypeMandatoryDescription
image_urlStringYesForeground image URL (subject — background removed via rembg). Must be a URI.
image_sizeStringNoOptional WidthxHeight for resized subject after background removal.
image_angleStringNoRotation degrees 0–360 (string decimal).
image_opacityStringNoSubject opacity 0–1 (string decimal).
image_positionENUMNoPlacement of the subject on the background canvas. Allowed values: top_right, top_left, bottom_right, bottom_left, center. Defaults to center when omitted.
background_sizeStringNoOptional WidthxHeight for background canvas or resize target.
background_colorStringNoHex color #RRGGBB (six hex digits with leading #). Use instead of background_image_url — only one background field may be present per request.
background_opacityStringNoBackground layer opacity 0–1 (string decimal).
background_image_urlStringNoBackground 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.

ParameterTypeMandatoryDescription
dataStringYesTime-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
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.
▣ 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
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.
Foreground image URL (subject — background removed via rembg).
Background image URL. Use instead of `background_color` — only one background field may be present per request.
Optional `WidthxHeight` for resized subject after background removal.
Rotation degrees 0–360 (string decimal).
Subject opacity 0–1 (string decimal).

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

ParameterTypeMandatoryDescription
image_urlStringYesForeground image URL (subject — background removed via rembg). Must be a URI.
image_sizeStringNoOptional WidthxHeight for resized subject after background removal.
image_angleStringNoRotation degrees 0–360 (string decimal).
image_opacityStringNoSubject opacity 0–1 (string decimal).
image_positionENUMNoPlacement of the subject on the background canvas. Allowed values: top_right, top_left, bottom_right, bottom_left, center. Defaults to center when omitted.
background_sizeStringNoOptional WidthxHeight for background canvas or resize target.
background_colorStringNoHex color #RRGGBB (six hex digits with leading #). Use instead of background_image_url — only one background field may be present per request.
background_opacityStringNoBackground layer opacity 0–1 (string decimal).
background_image_urlStringNoBackground 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.

ParameterTypeMandatoryDescription
binaryStringYesBinary PNG content returned by the endpoint.

Query parameters

Name
Type
Description
outputOPTIONAL
string
—

Body

Name
Type
Description
bodyREQUIRED
object
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.
▣ 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
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.
body*
Subject image (background removed server-side).
Background image file (use instead of `background_color`).
Optional `WidthxHeight` for resized subject after background removal.
Rotation degrees 0–360 (string decimal).
Subject opacity 0–1 (string decimal).

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)

AttributeTypeMandatoryDescription
outputStringNoDownload name for the output file.

Request Body

ParameterTypeMandatoryDescription
imageStringYesSubject image file to process. Background removal is performed server-side.
image_sizeStringNoOptional WidthxHeight for the resized subject after background removal.
image_angleStringNoRotation degrees from 0 to 360, as a string decimal.
image_opacityStringNoSubject opacity from 0 to 1, as a string decimal.
image_positionENUMNoSubject placement on the canvas. Allowed values: top_right, top_left, bottom_right, bottom_left, center.
background_sizeStringNoOptional WidthxHeight for the background canvas or resize target.
background_colorStringNoHex color in #RRGGBB format. Use this instead of background_image.
background_imageStringYesBackground image file. Use this instead of background_color.
background_opacityStringNoBackground 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
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.
body*
Subject image (background removed server-side).
Optional `WidthxHeight` for resized subject after background removal.
Rotation degrees 0–360 (string decimal).
Subject opacity 0–1 (string decimal).

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

ParameterTypeMandatoryDescription
imageStringYesSubject image (background removed server-side).
image_sizeStringNoOptional WidthxHeight for resized subject after background removal.
image_angleStringNoRotation degrees 0–360 (string decimal).
image_opacityStringNoSubject opacity 0–1 (string decimal).
image_positionENUMNoAllowed values: top_right, top_left, bottom_right, bottom_left, center.
background_sizeStringNoOptional WidthxHeight for background canvas or resize target.
background_colorStringNoHex color #RRGGBB (use instead of background_image).
background_imageStringNoBackground image file (use instead of background_color).
background_opacityStringNoBackground 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.

AttributeTypeMandatoryDescription
dataStringYesPre-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.

You might also like

Closest matches in the catalog based on this service.

CALLBackground RemoverApyHubCALLResize Images APIApyHubCALLApply Watermark on Images APIApyHubCALLImage Filters APIApyHub