# MiniMax H3 Text-to-Image

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /api/v1/jobs/createTask:
    post:
      summary: MiniMax H3 Text-to-Image
      deprecated: false
      description: >
        Generate an image from a text prompt with MiniMax-H3-Image.


        Prompt expansion is on by default; we recommend keeping it on for better
        image quality.


        ## Output size


        **Tier + ratio** — `resolution` (default `2K`) sets the size tier and
        `aspect_ratio` sets the shape. `auto` lets the prompt rewriter choose
        the ratio based on your content (falls back to `1:1` when
        `expand_prompt` is `false`).


        | Aspect ratio | 1K | 2K | 4K |

        |---|---|---|---|

        | 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |

        | 5:4 / 4:5 | 1152×912 / 912×1152 | 2304×1824 / 1824×2304 | 4576×3648 /
        3648×4576 |

        | 4:3 / 3:4 | 1184×880 / 880×1184 | 2368×1760 / 1760×2368 | 4736×3552 /
        3552×4736 |

        | 3:2 / 2:3 | 1248×832 / 832×1248 | 2496×1664 / 1664×2496 | 5024×3360 /
        3360×5024 |

        | 16:9 / 9:16 | 1360×768 / 768×1360 | 2720×1536 / 1536×2720 | 5472×3072
        / 3072×5472 |

        | 21:9 | 1568×672 | 3136×1344 | 6272×2688 |


        **Custom size** — `width` and `height` in pixels (1–8192 each), e.g.
        `width: 1920, height: 1080`. Total pixels 655,360–20,000,000, width :
        height between 1:3 and 3:1; the output is exactly this size. When using
        them, do not pass `resolution` or `aspect_ratio` — this combination is
        not accepted.


        **Which one applies**


        | You pass | Output size and billing tier |

        |---|---|

        | Both `width` and `height` (and no `resolution` / `aspect_ratio`) |
        Output is `width` × `height`, billed by total pixels (≤ 1.2 MP → `1K`, ≤
        4.5 MP → `2K`, otherwise `4K`) |

        | Only one of them | Not allowed: `width` and `height` must be set
        together |

        | Neither | `resolution` (default `2K`) and `aspect_ratio` (default
        `auto`) apply |

        | `width`/`height` together with `resolution` or `aspect_ratio` | Not
        allowed: the request is rejected |


        - One image per task, PNG (default) or JPEG

        - Billed per image by tier (`1K` / `2K` / `4K`): from `width` × `height`
        when both are set, otherwise from `resolution`; the tier does not depend
        on the ratio chosen by `auto`. For current prices, see
        [kie.ai/pricing](https://kie.ai/pricing)

        - Result URLs expire after about 14 days — download and store them if
        you need them longer


        ## Query Task Status


        After submitting a task with `model=minimax-h3/text-to-image`, use the
        unified query endpoint to check progress and retrieve results:


        <Card title="Get Task Details" icon="lucide-search"
        href="/market/common/get-task-detail">
          Learn how to query task status and retrieve generation results
        </Card>


        ::: tip[]

        For production use, we recommend using the `callBackUrl` parameter to
        receive automatic notifications when generation completes, rather than
        polling the status endpoint.

        :::


        ## Related Resources


        <CardGroup cols={2}>
          <Card title="Market Overview" icon="lucide-store" href="/market/quickstart">
            Explore all available models
          </Card>
          <Card title="Common API" icon="lucide-cog" href="/common-api/get-account-credits">
            Check credits and account usage
          </Card>
        </CardGroup>
      operationId: minimax-h3-text-to-image
      tags:
        - docs/en/Market/Image    Models/MiniMax H3
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                model:
                  default: minimax-h3/text-to-image
                  description: |-
                    The model name to use for generation. Required field.

                    - Must be `minimax-h3/text-to-image` for this endpoint
                  enum:
                    - minimax-h3/text-to-image
                  examples:
                    - minimax-h3/text-to-image
                  type: string
                  x-apidog-enum:
                    - value: minimax-h3/text-to-image
                      name: ''
                      description: ''
                callBackUrl:
                  description: >-
                    The URL to receive generation task completion updates.
                    Optional but recommended for production use.


                    - System will POST task status and results to this URL when
                    generation completes

                    - Callback includes generated content URLs and task
                    information

                    - Your callback endpoint should accept POST requests with
                    JSON payload containing results

                    - Alternatively, use the Get Task Details endpoint to poll
                    task status

                    - To ensure callback security, see [Webhook Verification
                    Guide](/common-api/webhook-verification) for signature
                    verification implementation
                  examples:
                    - https://your-domain.com/api/callback
                  format: uri
                  type: string
                input:
                  description: Input parameters for the generation task
                  properties:
                    prompt:
                      type: string
                      minLength: 1
                      maxLength: 5000
                      examples:
                        - >-
                          A cozy bookstore cafe on a rainy evening, warm lights
                          glowing through the window, a ginger cat sleeping on a
                          stack of books
                      description: >-
                        Required. Text prompt, 1–5000 characters; Chinese and
                        English are both supported.
                    aspect_ratio:
                      type: string
                      enum:
                        - auto
                        - '1:1'
                        - '5:4'
                        - '4:3'
                        - '3:2'
                        - '16:9'
                        - '21:9'
                        - '4:5'
                        - '3:4'
                        - '2:3'
                        - '9:16'
                      examples:
                        - auto
                      x-apidog-enum:
                        - value: auto
                          name: ''
                          description: Automatic
                        - value: '1:1'
                          name: ''
                          description: ''
                        - value: '5:4'
                          name: ''
                          description: ''
                        - value: '4:3'
                          name: ''
                          description: ''
                        - value: '3:2'
                          name: ''
                          description: ''
                        - value: '16:9'
                          name: ''
                          description: ''
                        - value: '21:9'
                          name: ''
                          description: ''
                        - value: '4:5'
                          name: ''
                          description: ''
                        - value: '3:4'
                          name: ''
                          description: ''
                        - value: '2:3'
                          name: ''
                          description: ''
                        - value: '9:16'
                          name: ''
                          description: ''
                      description: >-
                        Aspect ratio of the output image. Optional, defaults to
                        `auto`.


                        - `auto`: the prompt rewriter chooses a ratio based on
                        the content; when `expand_prompt` is `false`, `auto`
                        uses `1:1`

                        - Output sizes for each ratio and tier are listed in the
                        description above

                        - Do not pass together with `width`/`height`
                    resolution:
                      type: string
                      enum:
                        - 1K
                        - 2K
                        - 4K
                      default: 2K
                      examples:
                        - 2K
                      x-apidog-enum:
                        - value: 1K
                          name: ''
                          description: About 1 MP
                        - value: 2K
                          name: ''
                          description: About 4 MP
                        - value: 4K
                          name: ''
                          description: About 16 MP
                      description: >-
                        Output size tier. Optional, default `2K`;
                        case-insensitive.


                        - `1K`: about 1 MP

                        - `2K`: about 4 MP

                        - `4K`: about 16 MP, the officially recommended quality
                        tier

                        - Each image is billed by this tier

                        - Do not pass together with `width`/`height`; with a
                        custom size, billing follows its total pixels
                    seed:
                      type: integer
                      minimum: 0
                      maximum: 2147483647
                      examples:
                        - 7
                      description: >-
                        Random seed, 0–2147483647. Optional; a random seed is
                        used when omitted, and the actual seed is returned with
                        the result. With prompt expansion on, the rewritten
                        prompt differs each time, so results are only
                        reproducible when `expand_prompt` is `false`.
                    expand_prompt:
                      type: boolean
                      default: true
                      examples:
                        - true
                      description: >-
                        Whether to rewrite the prompt into a detailed English
                        description before generating. Optional. Prompt
                        expansion is on by default; we recommend keeping it on
                        for better image quality.


                        - `true` (default, recommended): the prompt is rewritten
                        into a detailed English description; with `aspect_ratio:
                        auto`, the rewriter also chooses the ratio

                        - `false`: the prompt is used as-is
                    output_format:
                      type: string
                      enum:
                        - png
                        - jpeg
                      default: png
                      examples:
                        - png
                      x-apidog-enum:
                        - value: png
                          name: ''
                          description: ''
                        - value: jpeg
                          name: ''
                          description: ''
                      description: >-
                        Output image format. Optional, default `png`. JPEG uses
                        quality 95 and is much smaller; 4K PNG files are very
                        large, so use JPEG when you need smaller files.
                    width:
                      type: integer
                      minimum: 1
                      maximum: 8192
                      examples:
                        - 1920
                      description: >-
                        Custom output width in pixels, 1–8192. Optional.
                        **`width` and `height` must be set together** (if one is
                        set, the other is required). When they are set, **do not
                        pass `resolution` or `aspect_ratio`** — this combination
                        is not accepted.


                        - Total pixels (width × height) must be between 655,360
                        and 20,000,000, and width : height between 1:3 and 3:1

                        - The output is exactly this size

                        - Billing tier by total pixels: up to 1,200,000 → `1K`,
                        up to 4,500,000 → `2K`, above → `4K` (e.g. 1920 × 1080 →
                        `2K`, 3840 × 2160 → `4K`)
                    height:
                      type: integer
                      minimum: 1
                      maximum: 8192
                      examples:
                        - 1080
                      description: >-
                        Custom output height in pixels, 1–8192. Optional, but
                        must be set together with `width`. See `width` for
                        limits, priority and billing.
                  required:
                    - prompt
                  type: object
                  x-apidog-orders:
                    - prompt
                    - aspect_ratio
                    - resolution
                    - seed
                    - expand_prompt
                    - output_format
                    - width
                    - height
                  x-apidog-ignore-properties: []
              required:
                - model
                - input
              type: object
              x-apidog-orders:
                - model
                - callBackUrl
                - input
              x-apidog-ignore-properties: []
            example:
              model: minimax-h3/text-to-image
              callBackUrl: https://your-domain.com/api/callback
              input:
                prompt: >-
                  A cozy bookstore cafe on a rainy evening, warm lights glowing
                  through the window, a ginger cat sleeping on a stack of books
                aspect_ratio: '16:9'
                resolution: 2K
                output_format: png
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponseWithRecordId'
          headers: {}
          x-apidog-name: Success
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: >-
                      Response status code


                      - **200**: Success - Request has been processed
                      successfully

                      - **401**: Unauthorized - Authentication credentials are
                      missing or invalid

                      - **402**: Insufficient Credits - Account does not have
                      enough credits to perform the operation

                      - **404**: Not Found - The requested resource or endpoint
                      does not exist

                      - **408**: Timeout - No result has been returned for over
                      10 minutes.

                      - **422**: Validation Error - The request parameters
                      failed validation checks

                      - **429**: Rate Limited - Request limit has been exceeded
                      for this resource

                      - **455**: Service Unavailable - System is currently
                      undergoing maintenance

                      - **500**: Server Error - An unexpected error occurred
                      while processing the request

                      - **501**: Generation Failed - Content generation task
                      failed

                      - **505**: Feature Disabled - The requested feature is
                      currently disabled
                  msg:
                    type: string
                    description: Response message, error description when failed
                  data:
                    type: object
                    properties: {}
                    x-apidog-orders: []
                    x-apidog-ignore-properties: []
                x-apidog-orders:
                  - code
                  - msg
                  - data
                required:
                  - code
                  - msg
                  - data
                x-apidog-ignore-properties: []
              example:
                code: 500
                msg: >-
                  Server Error - An unexpected error occurred while processing
                  the request
                data: null
          headers: {}
          x-apidog-name: Error
      security: []
      callbacks:
        onImageGenerated:
          '{$request.body#/callBackUrl}':
            post:
              summary: Image Generation Callback
              description: Sent when the task succeeds or fails.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        code:
                          type: integer
                          description: >-
                            200 indicates success; any other value indicates
                            failure (e.g., 501).
                          enum:
                            - 200
                            - 501
                        msg:
                          type: string
                          description: Status message
                          example: Playground task completed successfully.
                        data:
                          type: object
                          properties:
                            completeTime:
                              type: integer
                              format: int64
                              description: >-
                                Task completion time, represented as a Unix
                                timestamp in milliseconds
                              example: 1786417135000
                            costTime:
                              type: integer
                              description: >-
                                Processing time in seconds. Present on both
                                success and failure callbacks.
                              example: 165
                            createTime:
                              type: integer
                              format: int64
                              description: >-
                                Task creation time, represented as a Unix
                                timestamp in milliseconds
                              example: 1786416968000
                            creditsConsumed:
                              type: number
                              format: double
                              description: >-
                                Credits consumed by the task; 0 for failed
                                tasks.
                            model:
                              type: string
                              description: Image generation model used for the task
                              example: minimax-h3/text-to-image
                            param:
                              type: string
                              description: >-
                                Parameters submitted when creating the task, in
                                JSON string format
                              example: >-
                                {"input": "{\"prompt\": \"A cozy bookstore cafe
                                on a rainy evening, warm lights glowing through
                                the window, a ginger cat sleeping on a stack of
                                books\", \"aspect_ratio\": \"16:9\",
                                \"resolution\": \"2K\", \"output_format\":
                                \"png\"}", "callBackUrl":
                                "https://your-domain.com/api/callback", "model":
                                "minimax-h3/text-to-image"}
                            resultJson:
                              type: string
                              description: >-
                                Image generation result in JSON string format.
                                resultUrls contains the list of generated image
                                URLs. Present only when state is success.
                              example: >-
                                {"resultUrls":
                                ["https://tempfile.aiquickdraw.com/js/y1/9ef89580655a9e961ad0adb2.png"]}
                            state:
                              type: string
                              description: Task status
                              enum:
                                - success
                                - fail
                              example: success
                            taskId:
                              type: string
                              description: Task ID
                              example: b0e3febbf194d27a345de523d3321555
                            updateTime:
                              type: integer
                              format: int64
                              description: >-
                                Use completeTime as the completion time;
                                updateTime may equal createTime.
                              example: 1786417135000
                            failCode:
                              type: string
                              description: >-
                                Failure code, a numeric string such as "400" or
                                "500". Present only when state is fail.
                              example: '500'
                            failMsg:
                              type: string
                              description: Failure reason. Present only when state is fail.
                              example: <error detail>
                    examples:
                      success:
                        summary: Success
                        value:
                          code: 200
                          msg: Playground task completed successfully.
                          data:
                            taskId: b0e3febbf194d27a345de523d3321555
                            model: minimax-h3/text-to-image
                            state: success
                            param: >-
                              {"input": "{\"prompt\": \"A cozy bookstore cafe on
                              a rainy evening, warm lights glowing through the
                              window, a ginger cat sleeping on a stack of
                              books\", \"aspect_ratio\": \"16:9\",
                              \"resolution\": \"2K\", \"output_format\":
                              \"png\"}", "callBackUrl":
                              "https://your-domain.com/api/callback", "model":
                              "minimax-h3/text-to-image"}
                            resultJson: >-
                              {"resultUrls":
                              ["https://tempfile.aiquickdraw.com/js/y1/9ef89580655a9e961ad0adb2.png"]}
                            completeTime: 1786417135000
                            createTime: 1786416968000
                            costTime: 165
                            updateTime: 1786417135000
                      failure:
                        summary: Failure
                        value:
                          code: 501
                          msg: Playground task failed.
                          data:
                            taskId: b0e3febbf194d27a345de523d3321555
                            model: minimax-h3/text-to-image
                            state: fail
                            param: >-
                              {"input": "{\"prompt\": \"A cozy bookstore cafe on
                              a rainy evening, warm lights glowing through the
                              window, a ginger cat sleeping on a stack of
                              books\", \"aspect_ratio\": \"16:9\",
                              \"resolution\": \"2K\", \"output_format\":
                              \"png\"}", "callBackUrl":
                              "https://your-domain.com/api/callback", "model":
                              "minimax-h3/text-to-image"}
                            failCode: '500'
                            failMsg: <error detail>
                            completeTime: 1786417135000
                            createTime: 1786416968000
                            costTime: 165
                            updateTime: 1786417135000
              responses:
                '200':
                  description: Callback received successfully
      x-apidog-folder: docs/en/Market/Image    Models/MiniMax H3
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1184766/apis/api-46861885-run
components:
  schemas:
    ApiResponseWithRecordId:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: >-
            Status code of the request. The HTTP status is 200 even when the
            request fails, so always check this field: 200 means success; any
            other value means the request failed and msg describes the reason.
            Common values: 401 invalid or missing API key; 402 insufficient
            credits; 429 rate limit exceeded; 422 or 500 the request could not
            be processed (read msg and check your parameters before retrying).
        msg:
          type: string
          description: Response message, error description when failed
          examples:
            - success
        data:
          type: object
          properties:
            taskId:
              type: string
              description: >-
                Task ID, can be used with Get Task Details endpoint to query
                task status
            recordId:
              type: string
              description: Record ID, can be used to get the record details
          x-apidog-orders:
            - taskId
            - recordId
          x-apidog-ignore-properties: []
      x-apidog-orders:
        - code
        - msg
        - data
      title: response with recordId
      required:
        - data
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes:
    BearerAuth:
      type: bearer
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API requests require a Bearer Token. Add the header `Authorization:
        Bearer YOUR_API_KEY` to authenticate requests.
    BearerAuth1:
      type: bearer
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 请求都需要 Bearer Token。请在请求头中添加 `Authorization: Bearer YOUR_API_KEY`
        进行身份验证。
servers:
  - url: https://api.kie.ai
    description: 正式环境
security:
  - BearerAuth: []
    x-apidog:
      schemeGroups:
        - id: kn8M4YUlc5i0A0179ezwx
          schemeIds:
            - BearerAuth
      required: true
      use:
        id: kn8M4YUlc5i0A0179ezwx
      scopes:
        kn8M4YUlc5i0A0179ezwx:
          BearerAuth: []

```
