images-precise-edit

Edit an image with Ideogram 4.5, keeping the source's exact geometry

Edit an image with Ideogram 4.5, returning output at that image's exact width and height. An image too large for the model is scaled down to fit while keeping its exact proportion, and one whose aspect ratio is outside 1:6 to 6:1 is rejected — this endpoint never reshapes, so there is no size to reshape it to. Unlike POST /v2/image/generate/ideogram-4-5, this endpoint takes no size: the output always matches the image being edited, so the edit drops back into whatever it came from without reframing.

Pixels the edit did not meaningfully change are restored exactly from the image being edited, with the edited region blended smoothly into its surroundings — untouched areas stay identical across repeated edits.

Supply the image to edit as an image_asset_identifier reference or as raw image bytes (multipart requests only); if both are supplied, the reference wins and the bytes are ignored. Add up to four more images via reference_image_asset_identifiers or reference_images to guide the edit — those are never edited themselves.

Supply a mask to confine the edit to part of the image being edited. The mask is optional — without one the prompt is applied to the whole image. Masks are read as an additional reference image, so a masked request may carry at most three reference_images.

The prompt is the edit instruction. It accepts either natural language or a structured JSON prompt; the server detects which was supplied. A natural-language instruction is automatically rewritten into the model's structured edit contract, while a prompt that is already valid structured JSON is consumed directly.

By default the request blocks until the images are ready and returns them in data. Set async to true to return immediately after the request is accepted, then poll for completion and results with GET /v1/generations/{generation_id} using the returned generation_id.

Supplying a webhook_url makes the request asynchronous whatever async says: the response returns as soon as the request is accepted, and the finished result is POSTed to that URL.

post/v2/image/precise-edit/ideogram-4-5

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

promptstring required

The edit instruction to apply to the sources. Accepts either natural language or a structured JSON prompt; the server detects which was supplied. Natural language is automatically rewritten into the model's structured edit contract, while structured JSON is consumed directly.

imagestring binary

The image to edit, as raw bytes (max size 25MB; JPEG, PNG, or WEBP only). Multipart requests only; ignored if image_asset_identifier is also supplied. Required when supplying a mask.

reference_imagesstring[]

Optional additional images to guide the edit (max 4, max size 25MB each), as raw bytes; only JPEG, PNG, and WEBP formats are supported. These are never edited themselves; only image is. Multipart requests only; ignored if reference_image_asset_identifiers is also supplied. A masked request may carry at most three, because the mask occupies one of the model's reference slots.

maskstring binary

An optional mask confining the edit to part of image, as raw bytes (multipart requests only; JPEG, PNG, or WEBP, max 25MB). Black marks the area to edit and white the area to preserve; values in between are rounded to whichever is nearer. The mask must have the same width and height as image, and must contain both black and white areas. Requires the image being edited to be uploaded as raw image bytes in the same request; masks cannot be combined with asset references. The mask is supplied to the model as an additional reference image, so a masked request may carry at most three reference_images.

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

The rendering quality to use. very_high renders multiple candidate edits internally and returns the one that best applies the instruction; it takes longer than high, is priced higher, and supports at most 4 images per request.

seedinteger

Random seed. Set for reproducible generation.

num_imagesinteger

The number of images to generate.

enable_copyright_detectionboolean nullable

Optional. Opt this request into post-generation copyright detection. Adds detection latency; flagged images come back with is_image_safe: false.

asyncboolean

When false (the default), the request blocks until the images are ready and returns them in data. When true, the request returns as soon as it is accepted; poll for completion and results with GET /v1/generations/{generation_id} using the returned generation_id.

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.

privateboolean nullable

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.

target_collection_idstring

A collection you can write to, by its URL-safe base64 collection id. The output images are added to it when the request completes.

Example request

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

Response

The edited images (synchronous requests), or an acknowledgement to poll with GET /v1/generations/{generation_id} (async requests).

generation_idstring

URL-safe base64 ID of the accepted generation. Accepted by the GET /v1/generations/{generation_id} polling endpoint.