Sign in
latestOpenAPI 3.0.22026-08-21134292561.4 KB

898026c78d68

edit-workflow

Edit an image using a mask

Applies an instruction using a supplied mask. Optional reference images can guide the requested appearance. Set preserve_unmasked_pixels to keep decoded pixels outside the 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

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 what to change inside the mask.

seedinteger

Optional seed for repeatable results.

num_imagesinteger

Number of edited images to create.

privateboolean

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

preserve_unmasked_pixelsboolean

When true, decoded pixels outside the mask are copied from the source image into the final result. 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"
}