Sign in
edit-workflow

Replace an image background

Replaces the background of one image from a text prompt while preserving the foreground subject. The foreground mask is detected automatically; callers do not provide a mask.

The request is processed asynchronously. Poll GET /v1/generations/{generation_id} with the returned generation_id until the generation is completed or failed.

Supply exactly one source transport: an existing AssetIdentifier in image_asset_identifier, or raw image bytes in a multipart request. Supplying both or neither is rejected with a 400.

post/v2/tool/replace-background

Request body

imagestring binary

Raw source-image bytes. JPEG, PNG, WEBP, HEIF, AVIF, GIF, BMP, TIFF, and MPO are supported, up to 50 MB. Multipart requests only.

promptstring required

Plain-language description of the desired new background.

quality'LOW' | 'MEDIUM' | 'HIGH'

The quality tier for the image edit. Higher tiers may improve detail and take longer to complete.

num_imagesinteger

The number of images to generate.

privateboolean

If true, the user is requesting private generation. If omitted, this defaults to the user's plan entitlement. Enterprise generations are always private.

webhook_urlstring uri

HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a JSON POST to this URL once all images for the request have finished generating. The body mirrors the synchronous generate response: request_id, created, and a data array containing every generated image (url, prompt, resolution, seed, is_image_safe). Each delivery is signed with Ed25519 and verifiable against the public keys at https://api.ideogram.ai/v1/.well-known/jwks.json. Must be HTTPS; private and loopback hosts and the cloud metadata service are rejected.

Example request

{
  "image_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  },
  "webhook_url": "https://api.example.com/webhooks/ideogram"
}

Response

Background replacement accepted for asynchronous processing.

generation_idstring required

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

Example response

{
  "generation_id": "generation_id"
}

Changes

Changed in 1 of the 17 revisions of this API.1