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/image/remove-background/ideogram-1

Query parameters

dry_runboolean

When true, the request is validated and priced but not run: nothing is generated, stored, or billed, and no safety review is performed. The response is a PriceQuote object instead of the usual response for this endpoint. Send exactly the request you would send to generate, so the quote reflects the same options.

Request body

target_collection_idstring

A collection you can write to, by its URL-safe base64 collection id. Completed outputs are added to it automatically.

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

Changed in 3 of the 34 revisions of this API.7

  • 987f73fc82de4See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 5eb8666ebeff2See the full diff
    • ○

      added the new optional request property (media type: multipart/form-data)

      new-optional-request-property

    • ○

      added the new optional request property (media type: application/json)

      new-optional-request-property

  • 9d3ff2d98e271See the full diff
    • ○

      endpoint added

      endpoint-added