---
title: "Media · Image · Replace image background"
method: POST
path: "/api/v1/tools/replace-image"
tags: ["background"]
---

# Media · Image · Replace image background

`POST /api/v1/tools/replace-image`

## Request

- Base URL: `https://api.simplified.com`
- URL: `https://api.simplified.com/api/v1/tools/replace-image`
- Auth: API key in header `Authorization`

Replace ONLY the background behind the detected subject — with a solid
color, another image, or transparency. Set `replace_type` to `color`
(needs `replace_color`), `image` (needs `replace_image`), or `transparent`.
To blur rather than replace use `blurBackground`; to cut the subject out
entirely use `removeBackground`. Async — returns a task_id (auto-polled).

## Request body

- object
  - `image_url` string, required: URL of the source image.
  - `replace_type` 'transparent' | 'image' | 'color', required: What to replace the background with.
  - `replace_color` string: Hex color for replacement (required when replace_type=color).
  - `replace_image` string: URL of background image (required when replace_type=image).

## Response `202`

Async task queued.

- AsyncTaskResponse
  - `task_id` string: Poll GET /api/v1/tasks/{task_id} until SUCCESS or FAILURE.

---

[API](https://skmtc.dev/simplified/apis/image-tools.md) - [All operations](https://skmtc.dev/simplified/apis/image-tools/llms.txt) - [OpenAPI document](https://skmtc.dev/simplified/apis/image-tools/revisions/7de7bf8f6707?raw)