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

# H3-Image-Context-IR

> Run MiniMax-H3-Image prompt enhancement on its own and get the enhanced prompt synchronously, without generating images.

> [!WARNING]
>
> This endpoint only returns the enhanced prompt. It does not generate images.

This endpoint runs the same prompt enhancement that is built into [Text-to-Image](https://platform.minimax.io/docs/api-reference/image-generation-h3-generations.md) and [Image Edit](https://platform.minimax.io/docs/api-reference/image-generation-h3-edits.md): without `images`, the prompt is enhanced as text-to-image; with reference images, it is enhanced as an image edit. Use it to preview and revise the enhanced prompt, or to call enhancement as a separate step in your own workflow.

Supported model: `MiniMax-H3-Image`; `MiniMax-H3-Image-Highspeed` is not supported by this endpoint and returns 400. The server waits up to 600 seconds; set the client timeout to at least 600 seconds.

> [!NOTE]
>
> **Billing**: The input, output and thinking tokens consumed by the enhancement model are converted at their unit prices into equivalent input text tokens and counted in `usage.input_tokens`; no output tokens are billed separately. Failed requests (including those that fail the content safety check) are not billed.

> [!NOTE]
>
> **Two-step generation**: For text-to-image, send `revised_prompt` as the `prompt` of a [Text-to-Image](https://platform.minimax.io/docs/api-reference/image-generation-h3-generations.md) request with `disable_prompt_enhanced: true` and the `aspect_ratio` from the response (or your own `size` / `aspect_ratio`); the generation request is then not billed for prompt enhancement again. Image edits always apply prompt enhancement, so passing the result to Image Edit enhances and bills it again.


## OpenAPI

````yaml api-reference/image/generation/api/h3-image-context-ir.json POST /v1/h3_image_context_ir
openapi: 3.1.0
info:
  title: MiniMax H3-Image Context IR API
  description: MiniMax H3-Image API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.minimax.io
security:
  - bearerAuth: []
paths:
  /v1/h3_image_context_ir:
    post:
      tags:
        - Image
      summary: H3-Image-Context-IR
      description: >-
        Run MiniMax-H3-Image prompt enhancement on its own and get the enhanced
        prompt synchronously, without generating images.


        - Without `images`: enhanced as text-to-image

        - With `images` (1 to 16): enhanced as an image edit using the reference
        images


        Supported model: `MiniMax-H3-Image`; `MiniMax-H3-Image-Highspeed` is not
        supported by this endpoint and returns 400. Usually returns within a few
        seconds; the server waits up to 600 seconds, so set your client timeout
        to at least 600 seconds.
      operationId: h3ImageContextIR
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/H3ImageContextIRReq'
            examples:
              t2i:
                summary: Text-to-image enhancement
                value:
                  model: MiniMax-H3-Image
                  prompt: >-
                    A ginger cat sunbathing on a windowsill, warm afternoon
                    light, film look
              edit:
                summary: Image edit enhancement
                value:
                  model: MiniMax-H3-Image
                  prompt: >-
                    Replace the cat in Picture 1 with the Shiba Inu in Picture 2
                    and keep the background unchanged
                  images:
                    - image_url: https://example.com/cat.jpg
                    - image_url: https://example.com/dog.png
                  aspect_ratio: auto
      responses:
        '200':
          description: Enhancement succeeded; returns the enhanced prompt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/H3ImageContextIRResponse'
        '400':
          $ref: '#/components/responses/Err400'
        '401':
          $ref: '#/components/responses/Err401'
        '402':
          $ref: '#/components/responses/Err402'
          description: >-
            Insufficient balance or plan quota. The error code is in the
            parentheses at the end of `error.message`:


            - `1008`: insufficient balance

            - `2053`: insufficient credit

            - `2067`: usage limit reached and credit auto consumption is off

            - `2068`: the current plan tier does not support this model
        '422':
          $ref: '#/components/responses/Err422'
        '429':
          $ref: '#/components/responses/Err429'
          description: >-
            Rate limited. The error code is in the parentheses at the end of
            `error.message`:


            - `1002`: the requests-per-minute (RPM) limit is exceeded

            - `2056`: the M Plan usage limit is reached
        '500':
          $ref: '#/components/responses/Err500'
components:
  schemas:
    H3ImageContextIRReq:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: 'Model name. Supported value: `MiniMax-H3-Image`'
          enum:
            - MiniMax-H3-Image
        prompt:
          type: string
          maxLength: 32000
          description: >-
            Text description to enhance, up to 32000 characters (counted as
            Unicode characters, excluding leading and trailing whitespace); an
            empty or whitespace-only prompt returns 400.
        images:
          type: array
          minItems: 1
          maxItems: 16
          description: >-
            Reference images, 1 to 16. When provided, the prompt is enhanced as
            an image edit using the reference images; when omitted, it is
            enhanced as text-to-image.


            **Reference image limits** (total request body ≤ 64 MiB;
            Base64-encoded data is about 4/3 of the original file size; if the
            request body would exceed the limit, use public URLs or
            `mm_file://`)


            | Item | Limit |

            | :--- | :--- |

            | Format | JPG, JPEG, PNG, WEBP, HEIC, HEIF |

            | Single file size | ≤ 64 MiB |

            | Width/height range | [128, 8192] px |

            | Aspect ratio (long/short side) | ≤ 4:1 |

            | Count | 1 to 16 |
          items:
            $ref: '#/components/schemas/ImageInput'
        size:
          type: string
          default: auto
          description: >-
            Target output size, default `auto`. Same forms as the generation
            endpoints; use one of two forms; see [Output
            Size](/guides/image-generation#output-size).


            - `WIDTHxHEIGHT`: e.g. `2720x1536`; image-edit enhancement describes
            the scene in this width-to-height ratio. Area and aspect ratio
            limits are the same as the generation endpoints; otherwise 400 is
            returned. In this form, do not set `aspect_ratio` or `area` (not
            even to `auto`); otherwise 400 is returned

            - `auto` or omitted: the aspect ratio is determined by
            `aspect_ratio`


            Size parameters only affect image-edit enhancement; text-to-image
            enhancement does not read them.
        aspect_ratio:
          type: string
          default: auto
          example: '16:9'
          description: >-
            Target aspect ratio, default `auto`. Can only be set when `size` is
            omitted or `auto`; setting it while `size` is `WIDTHxHEIGHT` returns
            400.


            - `auto`: decided by prompt enhancement; see `aspect_ratio` in the
            response

            - `X:Y`: X and Y are integers from 1 to 300 and the ratio is between
            1:3 and 3:1 (bounds inclusive), e.g. `16:9`, `3:4`. Image-edit
            enhancement describes the scene in this ratio, and the response does
            not include `aspect_ratio`
        area:
          type: string
          enum:
            - 1K
            - 2K
            - 4K
          default: 4K
          description: >-
            Area level: `1K`, `2K` or `4K`, default `4K`. Can only be set when
            `size` is omitted or `auto`; setting it while `size` is
            `WIDTHxHEIGHT` returns 400. It does not affect the enhancement
            result and lets you reuse the same parameters as the generation
            request.
    H3ImageContextIRResponse:
      type: object
      properties:
        created:
          type: integer
          description: Time the response was generated, as a Unix timestamp in seconds.
        revised_prompt:
          type: string
          description: The enhanced prompt.
        aspect_ratio:
          type: string
          example: '3:2'
          description: >-
            Aspect ratio chosen by prompt enhancement, in `X:Y` format and
            between 1:3 and 3:1. Returned only when the ratio is decided by
            enhancement (`size` omitted or `auto`, and `aspect_ratio` omitted or
            `auto`).
        usage:
          $ref: '#/components/schemas/H3ImageContextIRUsage'
        request_id:
          type: string
          description: Request ID (the trace ID). Provide it when reporting an issue.
      example:
        created: 1794023743
        revised_prompt: >-
          A ginger tabby cat lounges lazily on a wooden windowsill, basking in
          the sun. Warm golden afternoon light slants in through the window,
          casting soft highlights on its fur and the sill. The curtains and room
          behind are slightly out of focus, and the whole image has a warm film
          look with fine grain and warm tones.
        aspect_ratio: '3:2'
        usage:
          total_tokens: 3489
          input_tokens: 3489
        request_id: 021792308678142a2c883cf675b9804d
    ImageInput:
      type: object
      description: A single reference image.
      required:
        - image_url
      properties:
        image_url:
          type: string
          description: >-
            Image location. Supported: a public URL; `mm_file://{file_id}`
            (reference an uploaded file, obtained by calling [File
            Upload](/api-reference/file-management-upload) with `purpose` set to
            `image_generation_input`); a `data:image/<format>;base64,<Base64>`
            data URI (`<format>` lowercase).
    H3ImageContextIRUsage:
      type: object
      description: >-
        Token usage of this request, used for billing. The cost of prompt
        enhancement is converted into input text tokens; no output tokens are
        billed separately.
      properties:
        total_tokens:
          type: integer
          description: Total tokens, equal to `input_tokens`.
        input_tokens:
          type: integer
          description: >-
            Input text tokens. The input, output and thinking tokens consumed by
            the enhancement model are converted at their unit prices into
            equivalent input text tokens, on the same basis as the prompt
            enhancement part of `usage.input_tokens_details.text_tokens` in the
            generation endpoints.
    OaiError:
      type: object
      description: >-
        Error response; the HTTP status code is the error code. Failed requests
        are not billed.
      properties:
        type:
          type: string
          description: Always `error`.
          example: error
        error:
          $ref: '#/components/schemas/OaiErrorDetail'
        request_id:
          type: string
          description: Request ID (the trace ID). Provide it when reporting an issue.
    OaiErrorDetail:
      type: object
      properties:
        type:
          type: string
          description: >-
            Error type: `bad_request_error` (400) / `authorized_error` (401) /
            `insufficient_balance_error` (402) / `unprocessable_entity_error`
            (422) / `rate_limit_error` (429) / `server_error` (500), etc.
        message:
          type: string
          description: >-
            Error detail; the trailing parenthesis holds the internal error code
            (e.g. `... (2013)`). See [Error Codes](/api-reference/errorcode).
        http_code:
          type: string
          description: HTTP status code as a string, e.g. `400`.
  responses:
    Err400:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OaiError'
          example:
            type: error
            error:
              type: bad_request_error
              message: invalid params, area must be one of 1K, 2K, 4K (2013)
              http_code: '400'
            request_id: 021792308678142a2c883cf675b9804d
    Err401:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OaiError'
          example:
            type: error
            error:
              type: authorized_error
              message: >-
                login fail: Please carry the API secret key in the
                'Authorization' field of the request header (1004)
              http_code: '401'
            request_id: 021792308678142a2c883cf675b9804d
    Err402:
      description: Insufficient balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OaiError'
          example:
            type: error
            error:
              type: insufficient_balance_error
              message: insufficient balance (1008)
              http_code: '402'
            request_id: 021792308678142a2c883cf675b9804d
    Err422:
      description: Input or enhanced prompt contains sensitive content
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OaiError'
          examples:
            input_sensitive:
              summary: Input contains sensitive content
              value:
                type: error
                error:
                  type: unprocessable_entity_error
                  message: 'input content failed safety check: prompt (1026)'
                  http_code: '422'
                request_id: 021792308678142a2c883cf675b9804d
            revised_prompt_sensitive:
              summary: Enhanced prompt failed content safety check
              value:
                type: error
                error:
                  type: unprocessable_entity_error
                  message: 'input content failed safety check: revised_prompt (1026)'
                  http_code: '422'
                request_id: 021792308678142a2c883cf675b9804d
    Err429:
      description: Rate limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OaiError'
          example:
            type: error
            error:
              type: rate_limit_error
              message: rate limit exceeded(RPM) (1002)
              http_code: '429'
            request_id: 021792308678142a2c883cf675b9804d
    Err500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OaiError'
          examples:
            timeout:
              summary: Prompt enhancement timed out
              value:
                type: error
                error:
                  type: server_error
                  message: request timeout, prompt rewrite timed out (1001)
                  http_code: '500'
                request_id: 021792308678142a2c883cf675b9804d
            server_error:
              summary: Server error
              value:
                type: error
                error:
                  type: server_error
                  message: system error, prompt rewrite failed (1033)
                  http_code: '500'
                request_id: 021792308678142a2c883cf675b9804d
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        `HTTP: Bearer Auth`

        - Security Scheme Type: http

        - HTTP Authorization Scheme: `Bearer API_key`, used to verify account
        information, can be found in [Account Management>API
        Keys](https://platform.minimax.io/user-center/basic-information/interface-key).

````