Ideogram Images Precise Edit API

openapi: 3.2.0
info:
  title: Ideogram API v2 Images Precise Edit API
  version: 1.0.0
servers:
- url: https://api.ideogram.ai
  description: https://api.ideogram.ai
tags:
- name: images-precise-edit
paths:
  /v2/image/precise-edit/ideogram-4-5:
    post:
      operationId: imagesPreciseEdit_post_precise_edit_image_v2_ideogram45
      summary: Precise edit with Ideogram 4.5
      description: 'Edit an image with Ideogram 4.5 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}`.


        `context_window` confines the edit to one region of the image, so a

        large image keeps its detail: pass `y_min,x_min,y_max,x_max`, or `auto`

        together with a `mask`. The result always keeps the image''s own width

        and height.'
      tags:
      - images-precise-edit
      parameters:
      - name: dry_run
        in: query
        description: '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.

          '
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The edited images (synchronous requests), or an acknowledgement to poll with `GET /v2/generations/{generation_id}` (`async` requests).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreciseEditImageIdeogram45Response'
        '400':
          description: Invalid input provided.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                description: Any type
        '402':
          description: Insufficient credits or quota.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationErrorResponse'
        '422':
          description: The prompt did not pass safety checks.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                description: Any type
        '503':
          description: The endpoint is temporarily unavailable.
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: A request to edit an image with Ideogram 4.5 at that image's own size. Send it as `multipart/form-data` with the `image` to edit and any `reference_images` and `mask`.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: '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:
                  type: string
                  format: binary
                  description: The image to edit, as raw bytes (max 50MB; JPEG, PNG, or WEBP). Multipart requests only; ignored if `image_asset_identifier` is also supplied. The output always matches this image's width and height, and pixels the edit did not meaningfully change are copied exactly from it.
                reference_images:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: 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; ignored if `reference_image_asset_identifiers` is also supplied. A request with a `mask` can include at most three, because the mask takes up one reference slot.
                mask:
                  type: string
                  format: binary
                  description: 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:
                  type: string
                  pattern: ^(none|auto|[0-9]+,[0-9]+,[0-9]+,[0-9]+)$
                  default: none
                  description: 'Which region of the image to edit.

                    `none`, the default, edits the whole image. A large image may come back smaller than it was sent.

                    `auto` requires a `mask` and automatically selects an appropriate context region around the masked area.

                    `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 4194304 pixels. A `mask` may select only pixels inside it.

                    With `auto` or an explicit region, only that region changes and the output keeps the image''s own width and height.'
                quality:
                  $ref: '#/components/schemas/V2ImagePreciseEditIdeogram45PostRequestBodyContentMultipartFormDataSchemaQuality'
                  default: medium
                  description: The rendering quality to use. `very_low` is the fastest and cheapest, and `high` takes longer and is priced higher.
                seed:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Random seed. Set for reproducible generation.
                num_images:
                  type: integer
                  minimum: 1
                  maximum: 8
                  default: 1
                  description: The number of images to generate.
                enable_copyright_detection:
                  type:
                  - boolean
                  - 'null'
                  description: 'Optional. Run copyright detection on the generated images. Adds latency; flagged images are returned with `is_image_safe: false`.'
                async:
                  type: boolean
                  default: false
                  description: 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:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: '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.

                    '
              required:
              - prompt
              - image
      security:
      - ApiKeyAuth: []
components:
  schemas:
    V2ImagePreciseEditIdeogram45PostRequestBodyContentMultipartFormDataSchemaQuality:
      type: string
      enum:
      - very_low
      - low
      - medium
      - high
      default: medium
      description: The rendering quality to use. `very_low` is the fastest and cheapest, and `high` takes longer and is priced higher.
      title: V2ImagePreciseEditIdeogram45PostRequestBodyContentMultipartFormDataSchemaQuality
    GeneratedImageObject:
      type: object
      properties:
        url:
          type:
          - string
          - 'null'
          format: uri
          description: The direct link to the generated image. Empty when the image did not pass safety checks.
        prompt:
          type: string
          description: The final prompt the image was generated from.
        resolution:
          type: string
          description: The resolution of the generated image, formatted as "WIDTHxHEIGHT".
        is_image_safe:
          type: boolean
          description: Whether the image passed safety checks. If false, `url` is empty.
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Random seed. Set for reproducible generation.
      required:
      - prompt
      - resolution
      - is_image_safe
      - seed
      description: One generated output image.
      title: GeneratedImageObject
    GenerationErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A message describing why the generation request was rejected.
        reject_reason:
          $ref: '#/components/schemas/GenerationRejectReason'
        max_inflight_requests:
          type: integer
          minimum: 1
          description: '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:
          $ref: '#/components/schemas/GenerationErrorResponseTaskCompletionSpeed'
          description: 'The queue this request resolved to. Present when `reject_reason`

            is `inflight_limit`.

            '
      required:
      - error
      - reject_reason
      description: A generation request rejected by an account or usage limit.
      title: GenerationErrorResponse
    GenerationRejectReason:
      type: string
      enum:
      - insufficient_funds
      - subscription_required
      - daily_limit
      - priority_credit_required
      - inflight_limit
      - feature_limit
      description: The account or usage limit that rejected a generation request.
      title: GenerationRejectReason
    PreciseEditImageIdeogram45Response:
      type: object
      properties:
        generation_kind:
          $ref: '#/components/schemas/GenerationKind'
        generation_id:
          type: string
          description: 'URL-safe base64 ID of the generation. Use it to poll

            `GET /v2/generations/{generation_id}`.

            '
        data:
          type: array
          items:
            $ref: '#/components/schemas/GeneratedImageObject'
          description: The edited images, in generation order. Present only for synchronous requests (`async` omitted or false).
        seed:
          type: integer
          description: The seed that was used, including when you did not set one.
      required:
      - generation_kind
      description: 'Response returned by `POST /v2/image/precise-edit/ideogram-4-5`.

        Synchronous requests (the default) include the edited images in `data`.

        Asynchronous requests omit `data`; poll

        `GET /v2/generations/{generation_id}` with the returned

        `generation_id`.

        '
      title: PreciseEditImageIdeogram45Response
    GenerationKind:
      type: string
      enum:
      - sampling
      - workflow
      description: The kind of generation identified by generation_id. Both kinds can be polled through GET /v2/generations/{generation_id}.
      title: GenerationKind
    GenerationErrorResponseTaskCompletionSpeed:
      type: string
      enum:
      - fast
      - slow
      description: 'The queue this request resolved to. Present when `reject_reason`

        is `inflight_limit`.

        '
      title: GenerationErrorResponseTaskCompletionSpeed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: API key for access control. Use in the header with the name \"Api-Key\"