Sign in
tool

Remove an image 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.

post/v2/tool/remove-background

Request body

privateboolean

Whether to keep the result out of the public gallery. Enterprise generations are always private.

asyncboolean

Return after acceptance and poll by generation ID when true.

Example request

{
  "image_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  }
}

Response

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.

generation_idstring

URL-safe base64 ID accepted by the generation polling endpoint.

errorstring

Error message for a failure after heartbeat streaming starts.

status_codeinteger

HTTP status that would have been returned before streaming began.

Example response

{
  "generation_id": "zm6IqQd4RPGnwA8gQYEL5Q",
  "data": [
    {
      "url": "https://ideogram.ai/assets/foreground.png",
      "is_image_safe": true
    }
  ]
}

Changes