---
title: Change Background of Images API
slug: change-image-background
url: https://apyhub.com/apyhub/service/change-image-background
provider: ApyHub
categories: [Media Kit]
tags: [background-replacement, image-background, image-editing, image-processing]
auth: api_key
version: 1.0.0
service_type: sync
endpoints: 4
atoms: 2000
mcp: true
alias: image-processor-change-background
---

# Change Background of Images API

Compose a subject image onto a new background using files or URLs. Returns PNG downloads or signed links for product shots and social assets.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| POST | `https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/download` | What it does Uploads a subject image and a background image, then returns the generated result as a… | 2000 |
| POST | `https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/link` | What it does Uploads a subject image and optional background settings as multipart form data, then… | 2000 |
| POST | `https://api.eu.apyhub.com/apyhub/change-image-background/url/download` | What it does Fetches a foreground image from a URL, removes its background, and composites it onto… | 2000 |
| POST | `https://api.eu.apyhub.com/apyhub/change-image-background/url/link` | What it does Fetches a foreground image from imageurl, removes its background, and composites it on… | 2000 |

## Endpoint reference

### Change image background

`POST https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/download` · 2000 atoms · accepts `multipart/form-data` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `image` | body | string (binary) | yes | Subject image (background removed server-side). Example: `sample.webp`. |
| `image_size` | body | string | no | Optional WidthxHeight for resized subject after background removal. Example: `140x140`. |
| `image_angle` | body | string | no | Rotation degrees 0–360 (string decimal). Example: `12`. |
| `image_opacity` | body | string | no | Subject opacity 0–1 (string decimal). Example: `0.9`. |
| `image_position` | body | string | no | One of: top_right, top_left, bottom_right, bottom_left, center. Example: `top_right`. |
| `background_size` | body | string | no | Optional WidthxHeight for background canvas or resize target. Example: `800x600`. |
| `background_color` | body | string | no | Hex color #000000 (use instead of background_image). Example: `#1E1E1E`. |
| `background_image` | body | string (binary) | yes | Background image file (use instead of background_color). Example: `background.jpg`. |
| `background_opacity` | body | string | no | Background layer opacity 0–1 (string decimal). Example: `0.35`. |
| `output` | query | string | no | Example: `my-invite`. |

#### Quickstart

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

```bash id="k9p1we"
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`.

### Change image background

`POST https://api.eu.apyhub.com/apyhub/change-image-background/multi-part/link` · 2000 atoms · accepts `multipart/form-data` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `image` | body | string (binary) | yes | Subject image (background removed server-side). Example: `sample.webp`. |
| `image_size` | body | string | no | Optional WidthxHeight for resized subject after background removal. Example: `140x140`. |
| `image_angle` | body | string | no | Rotation degrees 0–360 (string decimal). Example: `12`. |
| `image_opacity` | body | string | no | Subject opacity 0–1 (string decimal). Example: `0.9`. |
| `image_position` | body | string | no | One of: top_right, top_left, bottom_right, bottom_left, center. Example: `top_right`. |
| `background_size` | body | string | no | Optional WidthxHeight for background canvas or resize target. Example: `800x600`. |
| `background_color` | body | string | no | Hex color #000000 (use instead of background_image). Example: `#1E1E1E`. |
| `background_image` | body | string (binary) | no | Background image file (use instead of background_color). Example: `background.jpg`. |
| `background_opacity` | body | string | no | Background layer opacity 0–1 (string decimal). Example: `0.35`. |
| `output` | query | string | no | Example: `my-invite`. |

#### Quickstart

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

```bash
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.

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

### Change image background

`POST https://api.eu.apyhub.com/apyhub/change-image-background/url/download` · 2000 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `image_url` | body | string (uri) | yes | Foreground image URL (subject — background removed via rembg). Example: `https://assets.apyhub.com/samples/sample.webp`. |
| `image_size` | body | string | no | Optional WidthxHeight for resized subject after background removal. Example: `140x140`. |
| `image_angle` | body | string | no | Rotation degrees 0–360 (string decimal). Example: `12`. |
| `image_opacity` | body | string | no | Subject opacity 0–1 (string decimal). Example: `0.9`. |
| `image_position` | body | string | no | Placement of the subject on the background canvas. Defaults to center when omitted. One of: top_right, top_left, bottom_right, bottom_left, center. Example: `top_right`. |
| `background_size` | body | string | no | Optional WidthxHeight for background canvas or resize target. Example: `800x600`. |
| `background_color` | body | string | no | Hex color #000000 (six hex digits with leading #). Use instead of background_image_url — only one background field may be present per request. Example: `#1E1E1E`. |
| `background_opacity` | body | string | no | Background layer opacity 0–1 (string decimal). Example: `0.35`. |
| `background_image_url` | body | string (uri) | yes | Background image URL. Use instead of background_color — only one background field may be present per request. Example: `https://assets.apyhub.com/samples/sample.jpg`. |
| `output` | query | string | no | Example: `my-invite`. |

#### Quickstart

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

```bash
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.

### Change image background 

`POST https://api.eu.apyhub.com/apyhub/change-image-background/url/link` · 2000 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `image_url` | body | string (uri) | yes | Foreground image URL (subject — background removed via rembg). Example: `https://assets.apyhub.com/samples/sample.webp`. |
| `image_size` | body | string | no | Optional WidthxHeight for resized subject after background removal. Example: `140x140`. |
| `image_angle` | body | string | no | Rotation degrees 0–360 (string decimal). Example: `12`. |
| `image_opacity` | body | string | no | Subject opacity 0–1 (string decimal). Example: `0.9`. |
| `image_position` | body | string | no | Placement of the subject on the background canvas. Defaults to center when omitted. One of: top_right, top_left, bottom_right, bottom_left, center. Example: `top_right`. |
| `background_size` | body | string | no | Optional WidthxHeight for background canvas or resize target. Example: `800x600`. |
| `background_color` | body | 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. Example: `#1E1E1E`. |
| `background_opacity` | body | string | no | Background layer opacity 0–1 (string decimal). Example: `0.35`. |
| `background_image_url` | body | string (uri) | yes | Background image URL. Use instead of background_color — only one background field may be present per request. Example: `https://assets.apyhub.com/samples/sample.jpg`. |
| `output` | query | string | no | Example: `my-invite`. |

#### Quickstart

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

```bash
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.

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

## About

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

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/apyhub/service/change-image-background
