Sign in
edit-workflow

Edit an image, optionally using a mask

Applies an instruction to an image. When a mask is supplied, it identifies the primary edit region. Without a mask, the model edits the full image. Optional reference images can guide the requested appearance. Set preserve_unmasked_pixels to keep decoded pixels outside a supplied mask unchanged in the final image.

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

post/v2/workflow/precise-masked-edit

Request body

model'gpt-image-2' | 'ideogram-4-5'

The model used to apply the edit. For Ideogram 4.5, an optional mask is sent as one of the model's five image inputs and therefore reduces the reference-image limit by one.

quality'low' | 'medium' | 'high'

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

source_imagestring binary

Raw source image bytes. Supported formats and the 50 MB limit match the image upload API. Available only with multipart/form-data.

instructionstring required

Plain-language description of the desired change.

seedinteger

Optional seed for repeatable results.

num_imagesinteger

Number of edited images to create.

target_collection_idstring

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

privateboolean

When true or omitted, the output is kept private to your account. Set to false to publish the output to the public feed. Enterprise accounts always generate privately.

preserve_unmasked_pixelsboolean

When true, decoded pixels outside the mask are copied from the source image into the final result. Requires mask_asset_identifier. When false, the final result is the model's full edited image.

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

{
  "source_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  },
  "mask_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  },
  "reference_asset_identifiers": [
    {
      "asset_type": "RESPONSE",
      "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
    }
  ],
  "webhook_url": "https://api.example.com/webhooks/ideogram"
}

Response

Precise masked edit accepted for asynchronous processing.

generation_idstring required

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

Example response

{
  "generation_id": "generation_id"
}

Changes