---
title: "Remove an image background"
method: POST
path: "/v2/tool/remove-background"
tags: ["tool"]
---

# Remove an image background

`POST /v2/tool/remove-background`

Remove the background from one image and return a foreground PNG with
transparency. Supply exactly one source: raw `image` bytes in a
multipart request, or an existing `image_asset_identifier` in JSON or
multipart form.

By default the request blocks until the foreground image is ready and
returns it in `data`. Set `async` to true to return immediately after
the request is accepted, then poll `GET /v1/generations/{generation_id}`.

API-key requests use the organization bound to the key. Firebase Bearer
requests use their selected organization, and Mini App context tokens
remain bound to the organization in the token. When `private` is omitted,
Bearer and Mini App callers inherit their plan's private-generation
default; Enterprise generations are always private.

## Request body

- RemoveBackgroundV2AssetRequest — JSON request shape for processing an existing upload or generated image. Raw image bytes are accepted only through multipart form data.
  - `image_asset_identifier` AssetIdentifier, required — An identifier for an ideogram asset.
    - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required
    - `asset_id` string, required
  - `private` boolean — Whether to keep the result out of the public gallery. Enterprise generations are always private.
  - `async` boolean — Return after acceptance and poll by generation ID when true.

## Response `200`

The foreground image (synchronous requests), or an acknowledgement to poll (`async` requests). If a synchronous failure occurs after heartbeat streaming begins, the HTTP status is already committed; the response instead contains `error` and `status_code`.

- RemoveBackgroundV2Response — Synchronous requests include exactly one foreground image in `data`. Async requests omit `data`; poll with `generation_id` for completion. A slow synchronous failure that occurs after heartbeat streaming starts contains `error` and `status_code` instead of `generation_id`.
  - `generation_id` string — URL-safe base64 ID accepted by the generation polling endpoint.
  - `data` BackgroundRemovedImageObject[] — The single foreground image. Present only for synchronous requests.
    - `url` string, uri, nullable — Direct link to the foreground PNG. Empty when the output fails safety checks.
    - `is_image_safe` boolean, required — Whether the foreground image passed safety checks.
  - `error` string — Error message for a failure after heartbeat streaming starts.
  - `status_code` integer — HTTP status that would have been returned before streaming began.

## Other responses

- `400` — Invalid input provided.
- `401` — Unauthorized.
- `402` — Insufficient credits or quota.
- `403` — The selected organization or Mini App scope is not authorized.
- `404` — A referenced source asset was not found or is not readable.
- `429` — Too many requests.
- `500` — The background-removal request failed.
- `503` — Background removal is temporarily unavailable.

---

[API](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/3eb3216eed39/schema)