> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ideogram V4.6 Edit

> The Ideogram 4.6 Edit API edits one source image from a text prompt, with an optional mask, up to four reference images, regular or high-precision editing, and localized edits that keep the original resolution.

> [!TIP]
>
> 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
> 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint.

The Ideogram 4.6 Edit API is the image-editing model of the Ideogram 4.6 API. Send one source image and a prompt to replace a background, change the text on a sign, restyle a product shot, or repaint only the area you mark with a mask. Reference images guide the style or content, and high-precision editing restores every pixel you did not ask to change. To create images from a prompt alone, use the [Ideogram 4.6 API](https://docs.poyo.ai/api-manual/image-series/ideogram-v4-6.md) text-to-image model.

## Ideogram 4.6 API models

* **ideogram-v4.6-edit** — Edit exactly one source image, with an optional mask, reference images, and precision controls
* **ideogram-v4.6** — Text-to-image generation. See [Ideogram V4.6](https://docs.poyo.ai/api-manual/image-series/ideogram-v4-6.md)

## Ideogram 4.6 Edit API features

* **Prompt-based editing**: Describe the change in plain language. Put exact on-image text in quotes.
* **Masked edits**: Black areas of the mask are edited and white areas are kept.
* **Reference images**: Add up to four reference images, or three when a mask is set.
* **High-precision editing**: `edit_precision: high` makes a precise edit and restores unchanged pixels.
* **Localized edits at full resolution**: With `context_window: auto`, the Ideogram 4.6 Edit API edits only the region around the mask and keeps the source resolution.
* **Batches, backgrounds, and seeds**: Up to 8 results per request, transparent backgrounds for regular edits, and repeatable seeds.

## Edit modes

| Mode | Settings | What happens |
| - | - | - |
| Regular edit (default) | `edit_precision: regular` | The image is regenerated from the prompt. Without a mask, `size` can change the output size. `background` is supported. |
| High-precision edit | `edit_precision: high`, `context_window: none` | The whole image is edited precisely and unchanged pixels are restored. The output keeps the original resolution. |
| Localized edit | `edit_precision: high`, `context_window: auto`, `mask_url` | Only the region around the mask is edited. The original resolution and every pixel outside that region are kept. A mask that is too large falls back to whole-image editing. |

## Required parameters

* `prompt` (string): Description of the edit, 1–10,000 characters. Must contain non-whitespace text.
* `image_urls` (array of strings): Exactly one source image. Use a public HTTP(S) image URL or a base64 image data URI (`data:image/<type>;base64,...`). It must be an array, even for one image.

## Optional parameters

* `mask_url` (string): Mask image with the same dimensions as the source. Black areas are edited and white areas are kept; the mask must contain both. Public HTTP(S) URL or base64 image data URI. Requires `size` to be `auto`.
* `reference_image_urls` (array of strings): 0 to 4 reference images, or at most 3 when `mask_url` is set. Public HTTP(S) URLs or base64 image data URIs.
* `edit_precision` (string): `regular` or `high`. Default is `regular`. `regular` regenerates the image; `high` is a precise edit that restores unchanged pixels. `high` requires `size` to be `auto`.
* `context_window` (string): `none` or `auto`. Default is `none`. `auto` requires `edit_precision: high` and `mask_url`. See [Edit modes](#edit-modes).
* `size` (string): `auto`, `1:1`, `1:1 HD`, `4:3`, `3:4`, `16:9`, `9:16`, or a custom `WIDTHxHEIGHT`. Default is `auto`, which keeps the source geometry. See [Size](#size).
* `quality` (string): `very_low`, `low`, `medium`, or `high`. Default is `medium`. `very_low` is limited to outputs of at most 4,194,304 pixels.
* `background` (string): `transparent` or `opaque`. Regular edits only; rejected when `edit_precision` is `high`.
* `n` (integer): Number of results, `1` to `8`. Default is `1`.
* `seed` (integer): Random seed, `0` to `2147483647`. Omit it to pick one automatically.
* `callback_url` (string): Optional webhook URL for task completion notification. Send it at the top level of the request, not inside `input`.

The Ideogram 4.6 Edit API accepts only these fields in `input`. Any other field is rejected with an `unsupported fields` error.

## Size

* `auto` (default) keeps the source geometry. For the Ideogram 4.6 Edit API, it is the only value allowed with `mask_url` or `edit_precision: high`. Otherwise the request fails with "mask\_url or high edit\_precision requires size auto".
* For regular edits without a mask, you can also use the presets `1:1` (512×512), `1:1 HD` (1024×1024), `4:3` (1024×768), `3:4` (768×1024), `16:9` (1024×576), and `9:16` (576×1024).
* Custom `WIDTHxHEIGHT` sizes use a lowercase `x`. Both sides must be from `256` to `4096` pixels and multiples of `32`, and the aspect ratio must be within `1:6` and `6:1`.

## Output

When an Ideogram 4.6 Edit API task is `finished`, `files` contains one entry per edited image, each with `file_url` and `file_type: image`.

## Ideogram 4.6 Edit API examples

Send each Ideogram 4.6 Edit API request below to `POST /api/generate/submit` with your API key in the `Authorization` header.

### Edit Image

```json theme={"dark"}
{
  "model": "ideogram-v4.6-edit",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Replace the background with a blue photo studio",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}
```

### Localized Masked Edit

```json theme={"dark"}
{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change the sign text to \"OPEN LATE\"",
    "image_urls": [
      "https://example.com/storefront.png"
    ],
    "mask_url": "https://example.com/sign-mask.png",
    "edit_precision": "high",
    "context_window": "auto",
    "quality": "high"
  }
}
```

Only the area around the black part of the mask is edited, and the original resolution is kept.

### Restyle With A Reference Image

```json theme={"dark"}
{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Restyle the product shot to match the reference",
    "image_urls": [
      "https://example.com/product.png"
    ],
    "reference_image_urls": [
      "https://example.com/style.png"
    ],
    "size": "2048x2048",
    "quality": "low",
    "n": 2
  }
}
```

## Notes

* The Ideogram 4.6 Edit API requires exactly one source image in `image_urls`.
* `context_window: auto` without `edit_precision: high` and `mask_url` is rejected.
* `very_low` with a custom size above 4,194,304 pixels is rejected.
* The source image, mask, and reference images can be public HTTP(S) URLs or base64 image data URIs. To use local files, you can also upload them first with [File Management](https://docs.poyo.ai/api-manual/file-series/upload-url.md).
* Generated image files are accessible for 3 days after creation. Download and store them promptly.
* The response returns a `task_id`. Query the task status to get the edited images.


## OpenAPI

````yaml api-manual/image-series/ideogram-v4-6-edit.json POST /api/generate/submit
openapi: 3.1.0
info:
  title: PoYo AI - Ideogram V4.6 Edit API
  description: >-
    The Ideogram 4.6 Edit API edits one source image from a text prompt, with an
    optional mask, up to four reference images, regular or high-precision
    editing, and localized edits that keep the original resolution.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Ideogram V4.6 Edit
      summary: Submit Ideogram V4.6 Edit Task
      description: >-
        Ideogram 4.6 Edit API image editing with an optional mask, reference
        images, and regular, high-precision, or localized editing.
      operationId: submit_ideogram_v4_6_edit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              image-edit:
                summary: Edit Image
                value:
                  model: ideogram-v4.6-edit
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: Replace the background with a blue photo studio
                    image_urls:
                      - https://example.com/source.png
              localized-masked-edit:
                summary: Localized Masked Edit
                value:
                  model: ideogram-v4.6-edit
                  input:
                    prompt: Change the sign text to "OPEN LATE"
                    image_urls:
                      - https://example.com/storefront.png
                    mask_url: https://example.com/sign-mask.png
                    edit_precision: high
                    context_window: auto
                    quality: high
              reference-restyle:
                summary: Restyle With A Reference Image
                value:
                  model: ideogram-v4.6-edit
                  input:
                    prompt: Restyle the product shot to match the reference
                    image_urls:
                      - https://example.com/product.png
                    reference_image_urls:
                      - https://example.com/style.png
                    size: 2048x2048
                    quality: low
                    'n': 2
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - ideogram-v4.6-edit
          description: Ideogram 4.6 Edit model identifier.
        callback_url:
          type: string
          format: uri
          description: Optional webhook URL for task completion or failure.
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
            - image_urls
          description: Edit exactly one source image.
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 10000
              pattern: \S
              description: >-
                Required. Description of the edit, 1-10,000 characters. Must
                contain non-whitespace text.
            image_urls:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
                pattern: ^(https?://\S+|data:image/[A-Za-z0-9.+-]+;base64,\S+)$
                description: Public HTTP(S) image URL or base64 image data URI.
              description: >-
                Required. Exactly one source image to edit, as a public HTTP(S)
                image URL or base64 image data URI. Must be an array.
            mask_url:
              type: string
              pattern: ^(https?://\S+|data:image/[A-Za-z0-9.+-]+;base64,\S+)$
              description: >-
                Optional mask with the same dimensions as the source. Black
                areas are edited, white areas are kept; it must contain both.
                Public HTTP(S) URL or base64 image data URI. Requires size auto.
            reference_image_urls:
              type: array
              minItems: 0
              maxItems: 4
              items:
                type: string
                pattern: ^(https?://\S+|data:image/[A-Za-z0-9.+-]+;base64,\S+)$
                description: Public HTTP(S) image URL or base64 image data URI.
              description: >-
                Optional reference images: 0-4, or at most 3 when mask_url is
                set. Public HTTP(S) URLs or base64 image data URIs.
            edit_precision:
              type: string
              enum:
                - regular
                - high
              default: regular
              description: >-
                regular (default) regenerates the image; high makes a precise
                edit, restores unchanged pixels, and requires size auto.
            context_window:
              type: string
              enum:
                - none
                - auto
              default: none
              description: >-
                none (default) or auto. With edit_precision high, none edits the
                whole image and keeps its original resolution. auto requires
                mask_url and edit_precision high, edits only the region around
                the mask, and keeps the original resolution.
            size:
              type: string
              default: auto
              pattern: ^(auto|1:1|1:1 HD|4:3|3:4|16:9|9:16|[0-9]+x[0-9]+)$
              examples:
                - auto
                - 1:1 HD
                - '16:9'
                - 2048x2048
              description: >-
                auto (default) keeps the source geometry. 1:1, 1:1 HD, 4:3, 3:4,
                16:9, 9:16, or a custom WIDTHxHEIGHT (sides of 256-4096 pixels,
                multiples of 32, aspect ratio within 1:6 and 6:1) are only
                allowed for regular edits without mask_url. Outputs above
                4,194,304 pixels do not support very_low.
            quality:
              type: string
              enum:
                - very_low
                - low
                - medium
                - high
              default: medium
              description: >-
                Output quality. Defaults to medium. very_low is only available
                for outputs up to 4,194,304 pixels (2048x2048 in area).
            background:
              type: string
              enum:
                - transparent
                - opaque
              description: >-
                Optional, regular edits only (rejected when edit_precision is
                high). transparent returns an image with an alpha channel;
                opaque forces a solid background.
            'n':
              type: integer
              minimum: 1
              maximum: 8
              default: 1
              description: Number of output images, 1-8. Defaults to 1. Must be an integer.
            seed:
              type: integer
              minimum: 0
              maximum: 2147483647
              description: >-
                Optional random seed, 0-2147483647. Omit to pick one
                automatically.
          allOf:
            - if:
                required:
                  - mask_url
              then:
                properties:
                  reference_image_urls:
                    maxItems: 3
                  size:
                    const: auto
            - if:
                required:
                  - edit_precision
                properties:
                  edit_precision:
                    const: high
              then:
                properties:
                  size:
                    const: auto
                not:
                  required:
                    - background
            - if:
                required:
                  - context_window
                properties:
                  context_window:
                    const: auto
              then:
                required:
                  - mask_url
                  - edit_precision
                properties:
                  edit_precision:
                    const: high
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                Task status. Always `not_started` right after submission. Use
                [Query Task Status](/api-manual/task-management/status) or
                `callback_url` to get later states.


                - `not_started`: Queued, waiting to be processed

                - `running`: Being generated

                - `finished`: Completed; results are in `files` or `output`

                - `failed`: Failed; details are in `error_message`
            created_time:
              type: string
              format: date-time
              example: '2026-10-13T10:30:00+08:00'
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        All API endpoints require Bearer Token authentication.


        Create an API key: sign in to PoYo, open **Dashboard → API Key** at
        [poyo.ai/dashboard/api-key](https://poyo.ai/dashboard/api-key), and
        click to create a key.


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.