> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developer.ideogram.ai/v2/llms.txt
> - v1: https://developer.ideogram.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

# Precise edit with Ideogram 4.6

POST https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6
Content-Type: multipart/form-data

Edit an image with Ideogram 4.6 and get the result back at that image's
exact width and height. Upload the image as `image` using
`multipart/form-data`, with optional `reference_images` and a `mask`.
Returns results directly by default; set `async` or supply a
`webhook_url` to get a `generation_id` and poll
`GET /v2/generations/{generation_id}`.

Editing the whole image is bounded by 16777216 pixels (the area of a
4096x4096 square), so a larger image comes back scaled down to fit: an
8192x8192 image returns as 4096x4096.

To edit a 4K or 8K image at its full resolution, set `context_window`
to confine the edit to one region, either `auto` together with a
`mask`, or `y_min,x_min,y_max,x_max` to name the region yourself. Only
that region changes, the rest of the image comes back unchanged, and
the result keeps the image's own width and height at any input size.

```bash
curl -X POST https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6 \
  -H "Api-Key: $IDEOGRAM_API_KEY" \
  -F image=@photo_8k.png \
  -F mask=@mask_8k.png \
  -F context_window=auto \
  -F prompt="Add round black sunglasses."
```

Reference: https://developer.ideogram.ai/api-reference/images/precise-edit/ideogram-4-6

## Authentication

- `Api-Key` header (required) — API key for access control. Use in the header with the name \"Api-Key\"

## Request

### Query parameters

- `dry_run` (boolean, optional, default: false) — 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.

### Body (multipart/form-data)

This endpoint expects a multipart form with multiple files.

- `prompt` (string, required) — The edit instruction, in natural language or as a structured JSON prompt. Natural language is automatically converted into a structured prompt; valid structured JSON is used as is.
- `image` (file, required) — The image to edit, as raw bytes (max 50MB and 67108864 pixels, which 8192x8192 meets exactly; JPEG, PNG, or WEBP). Multipart requests only. The output always matches this image's width and height, and pixels the edit did not meaningfully change are copied exactly from it. Set `context_window` to keep the full resolution of an image over 16777216 pixels.
- `reference_images` (files, optional) — Optional images to guide the edit (max 4, max 50MB each; JPEG, PNG, or WEBP). They are never edited themselves; only `image` is. Multipart requests only. A request with a `mask` can include at most three, because the mask takes up one reference slot.
- `mask` (file, optional) — An optional mask that limits the edit to part of `image` (max 50MB; JPEG, PNG, or WEBP). Multipart requests only. Black marks the area to edit and white the area to keep; values in between are rounded to the nearer of the two. The mask must have the same width and height as the image being edited and contain both black and white areas. A masked request can include at most three reference images.
- `context_window` (string, optional) — Which region of the image to edit. Set this to keep the full resolution of an image larger than 16777216 pixels. `none` edits the whole image, which is bounded by 16777216 pixels (the area of a 4096x4096 square); a larger image comes back scaled down to fit. For example, an 8192x8192 image returns as 4096x4096. `auto`, the default, fits a region around the masked area when a `mask` is supplied. Without a mask, it behaves the same as `none`. If the mask selects more than 16777216 pixels no region fits it, and the request falls back to editing the whole image, scaled down as above. `y_min,x_min,y_max,x_max` names the region explicitly, by its corners. Rows come first, matching the `bbox` ordering used elsewhere in this API, and the values are the edited image's own pixels with the origin at its top-left corner. For example `512,1024,2048,3072` is the region 2048 pixels wide and 1536 tall whose top-left corner is 1024 across and 512 down. The maximum edges are exclusive, so the region measures `x_max - x_min` by `y_max - y_min`. It must lie inside the image, measure at least 256px on each side, have an aspect ratio between 1:6 and 6:1, and cover no more than 16777216 pixels. A `mask` may select only pixels inside it. When `auto` finds a region, or with an explicit region, only that region changes, the rest of the image comes back unchanged, and the output keeps the image's own width and height at any input size. With `quality` set to `very_low`, every 16777216-pixel bound above is 4194304 pixels (the area of a 2048x2048 square) instead, and no side may exceed 4608px.
- `quality` (enum, optional) — The rendering quality to use. `very_low` is the fastest and cheapest and renders up to 2K. `low` is faster and cheaper than `medium`. `medium` renders each image once. `high` renders several candidates for each image and returns the best one, so it takes longer and is priced higher. The price also depends on the size of the image you send: an image over 2048x2048 pixels is billed at the 4K price, except at `very_low`. Setting `context_window` does not lower it.
- `seed` (integer, optional) — Random seed. Set for reproducible generation.
- `num_images` (integer, optional) — The number of images to generate.
- `enable_copyright_detection` (boolean, optional) — Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with `is_image_safe: false`.
- `async` (boolean, optional) — When false (the default), the request waits until the images are ready and returns them in `data`. When true, the request returns as soon as it is accepted; poll `GET /v2/generations/{generation_id}` with the returned `generation_id` for the result.
- `webhook_url` (string, optional) — 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.

## Response

### 200

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

- `generation_kind` (enum, required) — The kind of generation identified by generation\_id. Both kinds can be polled through GET /v2/generations/\{generation\_id}.
  - Allowed values: `sampling`, `workflow`
- `generation_id` (string, optional) — URL-safe base64 ID of the generation. Use it to poll `GET /v2/generations/{generation_id}`.
- `data` (list of GeneratedImageObject, optional) — The edited images, in generation order. Present only for synchronous requests (`async` omitted or false).
- `seed` (integer, optional) — The seed that was used, including when you did not set one.

## Errors

### 400 Bad Request Error

Invalid input provided.

- `any`

### 401 Unauthorized Error

Unauthorized.

- `any`

### 402 Payment Required Error

Insufficient credits or quota.

- `error` (string, required) — A message describing why the generation request was rejected.
- `reject_reason` (enum, required) — The account or usage limit that rejected a generation request.
  - Allowed values: `insufficient_funds`, `subscription_required`, `daily_limit`, `priority_credit_required`, `inflight_limit`, `feature_limit`, `app_user_limit`
- `max_inflight_requests` (integer, optional) — How many generations the account may have in progress at once on the queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
- `task_completion_speed` (enum, optional) — The queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
  - Allowed values: `fast`, `slow`

### 422 Unprocessable Entity Error

The prompt did not pass safety checks.

- `any`

### 429 Too Many Requests Error

Too many requests.

- `error` (string, required) — A message describing why the generation request was rejected.
- `reject_reason` (enum, required) — The account or usage limit that rejected a generation request.
  - Allowed values: `insufficient_funds`, `subscription_required`, `daily_limit`, `priority_credit_required`, `inflight_limit`, `feature_limit`, `app_user_limit`
- `max_inflight_requests` (integer, optional) — How many generations the account may have in progress at once on the queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
- `task_completion_speed` (enum, optional) — The queue this request resolved to. Present when `reject_reason` is `inflight_limit`.
  - Allowed values: `fast`, `slow`

### 500 Internal Server Error

Internal server error.

- `any`

### 503 Service Unavailable Error

The endpoint is temporarily unavailable.

- `any`

## Types

### GeneratedImageObject

One generated output image.

- `prompt` (string, required) — The final prompt the image was generated from.
- `resolution` (string, required) — The resolution of the generated image, formatted as "WIDTHxHEIGHT".
- `is_image_safe` (boolean, required) — Whether the image passed safety checks. If false, `url` is empty.
- `seed` (integer, required) — Random seed. Set for reproducible generation.
- `url` (string, optional, nullable) — The direct link to the generated image. Empty when the image did not pass safety checks.

## Examples

**Request**

```json
{
  "image": "<file: image.png>",
  "mask": "<file: <file1>>",
  "prompt": "Change the jacket to red leather",
  "reference_images": []
}
```

**Response**

```json
{
  "generation_kind": "sampling",
  "generation_id": "generation_id",
  "data": [
    {
      "prompt": "prompt",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://openapi-generator.tech"
    },
    {
      "prompt": "prompt",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://openapi-generator.tech"
    }
  ],
  "seed": 0
}
```

**SDK Code**

```python images-precise-edit_post_precise_edit_image_v2_ideogram46_example
import requests

response = requests.post(
    "https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6",
    headers={"Api-Key": "<apiKey>"},
    data={"prompt": "Change the jacket to red leather"},
    files={"image": open("image.png", "rb")},
)
print(response.json())

```

```javascript images-precise-edit_post_precise_edit_image_v2_ideogram46_example
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("prompt", "Change the jacket to red leather");
form.append("image", new Blob([await readFile("image.png")]), "image.png");

const response = await fetch("https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6", {
  method: "POST",
  headers: { "Api-Key": "<apiKey>" },
  body: form,
});
console.log(await response.json());

```

```go images-precise-edit_post_precise_edit_image_v2_ideogram46_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"context_window\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the jacket to red leather\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Api-Key", "<apiKey>")
	req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby images-precise-edit_post_precise_edit_image_v2_ideogram46_example
require 'uri'
require 'net/http'

url = URI("https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Api-Key"] = '<apiKey>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"context_window\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the jacket to red leather\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java images-precise-edit_post_precise_edit_image_v2_ideogram46_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6")
  .header("Api-Key", "<apiKey>")
  .header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"context_window\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the jacket to red leather\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php images-precise-edit_post_precise_edit_image_v2_ideogram46_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6', [
  'multipart' => [
    [
        'name' => 'image',
        'filename' => 'image.png',
        'contents' => null
    ],
    [
        'name' => 'mask',
        'filename' => '<file1>',
        'contents' => null
    ],
    [
        'name' => 'prompt',
        'contents' => 'Change the jacket to red leather'
    ]
  ]
  'headers' => [
    'Api-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp images-precise-edit_post_precise_edit_image_v2_ideogram46_example
using RestSharp;

var client = new RestClient("https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6");
var request = new RestRequest(Method.POST);
request.AddHeader("Api-Key", "<apiKey>");
request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"async\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"context_window\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"enable_copyright_detection\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"image.png\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"<file1>\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"num_images\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the jacket to red leather\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"quality\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"seed\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift images-precise-edit_post_precise_edit_image_v2_ideogram46_example
import Foundation

let headers = [
  "Api-Key": "<apiKey>",
  "Content-Type": "multipart/form-data; boundary=---011000010111000001101001"
]
let parameters = [
  [
    "name": "async",
    "value": 
  ],
  [
    "name": "context_window",
    "value": 
  ],
  [
    "name": "enable_copyright_detection",
    "value": 
  ],
  [
    "name": "image",
    "fileName": "image.png"
  ],
  [
    "name": "mask",
    "fileName": "<file1>"
  ],
  [
    "name": "num_images",
    "value": 
  ],
  [
    "name": "prompt",
    "value": "Change the jacket to red leather"
  ],
  [
    "name": "quality",
    "value": 
  ],
  [
    "name": "seed",
    "value": 
  ],
  [
    "name": "webhook_url",
    "value": 
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ideogram.ai/v2/image/precise-edit/ideogram-4-6")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```