# MiniMax-H3-Image Image Generation

> Image Generation

Generate one or more images with the `MiniMax-H3-Image` model.

## Endpoint

`POST https://api.modelverse.cn/v1/images/generations`

## Request Body

## Responses

- **200** — Image generation response. Non-stream requests return JSON; stream requests return SSE.
- **400** — 
- **default** — 

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse MiniMax-H3-Image API",
    "version": "1.0.0",
    "description": "Self-contained OpenAPI 3.1 schema for the ModelVerse `MiniMax-H3-Image`\nimage generation and image edit APIs.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "Mainland China"
    },
    {
      "url": "https://api.umodelverse.ai",
      "description": "Global"
    },
    {
      "url": "https://api-us-ca.umodelverse.ai",
      "description": "Los Angeles, US"
    },
    {
      "url": "https://api-sg.umodelverse.ai",
      "description": "Singapore"
    },
    {
      "url": "https://api-ge-fra.umodelverse.ai",
      "description": "Frankfurt"
    }
  ],
  "tags": [
    {
      "name": "MiniMax-H3-Image",
      "description": "OpenAI-compatible image generation and image edit APIs for `MiniMax-H3-Image`."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/images/generations": {
      "post": {
        "tags": [
          "MiniMax-H3-Image"
        ],
        "operationId": "createMiniMaxH3ImageGeneration",
        "summary": "MiniMax-H3-Image Image Generation",
        "description": "Generate one or more images with the `MiniMax-H3-Image` model.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MiniMaxH3ImageGenerateRequest"
              },
              "examples": {
                "text_to_image": {
                  "summary": "Text-to-image generation",
                  "value": {
                    "model": "minimax-h3-image",
                    "prompt": "A cute orange cat basking in the sun on a windowsill",
                    "n": 1,
                    "size": "auto",
                    "aspect_ratio": "16:9",
                    "area": "4K"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Image generation response. Non-stream requests return JSON; stream requests return SSE.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ImageResponse"
                },
                "examples": {
                  "url_image": {
                    "summary": "Generated image returned as URL",
                    "value": {
                      "created": 1792308678,
                      "data": [
                        {
                          "url": "https://example.com/generated-image.jpg",
                          "size": "2720x1536",
                          "revised_prompt": "A cute orange cat basking in the sun..."
                        }
                      ],
                      "output_format": "jpeg",
                      "usage": {
                        "generated_images": 1,
                        "total_tokens": 7254,
                        "input_tokens": 3174,
                        "output_tokens": 4080,
                        "input_tokens_details": {
                          "text_tokens": 3174,
                          "image_tokens": 0
                        },
                        "output_tokens_details": {
                          "image_tokens": 4080
                        }
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ImageStreamEvent"
                },
                "examples": {
                  "sseExample": {
                    "summary": "SSE events",
                    "value": "event: image_generation.partial_succeeded\ndata: {\"type\":\"image_generation.partial_succeeded\",\"created\":1792308690,\"model\":\"MiniMax-H3-Image\",\"image_index\":1,\"url\":\"https://example.com/h3-image/output-1.jpg\",\"size\":\"2720x1536\",\"output_format\":\"jpeg\",\"revised_prompt\":\"一只橘猫蜷在洒满阳光的窗台上打盹，窗外是模糊的城市街景，暖色调，胶片质感\"}\n\nevent: image_generation.partial_failed\ndata: {\"type\":\"image_generation.partial_failed\",\"created\":1792308691,\"model\":\"MiniMax-H3-Image\",\"image_index\":2,\"code\":\"1027\",\"message\":\"output image failed content safety check\"}\n\nevent: image_generation.partial_succeeded\ndata: {\"type\":\"image_generation.partial_succeeded\",\"created\":1792308695,\"model\":\"MiniMax-H3-Image\",\"image_index\":0,\"url\":\"https://example.com/h3-image/output-0.jpg\",\"size\":\"2720x1536\",\"output_format\":\"jpeg\",\"revised_prompt\":\"午后的暖光透过木质窗框洒在窗台上，一只橘猫侧身趴着晒太阳，眯着眼睛，胶片颗粒质感\"}\n\nevent: image_generation.completed\ndata: {\"type\":\"image_generation.completed\",\"created\":1792308695,\"model\":\"MiniMax-H3-Image\",\"usage\":{\"generated_images\":2,\"total_tokens\":13022,\"input_tokens\":4862,\"output_tokens\":8160,\"input_tokens_details\":{\"text_tokens\":4862,\"image_tokens\":0},\"output_tokens_details\":{\"image_tokens\":8160}},\"request_id\":\"021792308678142a2c883cf675b9804d\"}\n"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "tags": [
          "MiniMax-H3-Image"
        ],
        "operationId": "createMiniMaxH3ImageEdit",
        "summary": "MiniMax-H3-Image Image Editing",
        "description": "Edit an image with the `MiniMax-H3-Image` model.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MiniMaxH3ImageEditRequest"
              },
              "examples": {
                "image_edit": {
                  "summary": "Image editing with reference images",
                  "value": {
                    "model": "minimax-h3-image",
                    "prompt": "Replace the cat with a Shiba Inu, keep the background",
                    "image": "https://example.com/cat.jpg",
                    "n": 1,
                    "size": "auto"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Image edit response. Non-stream requests return JSON; stream requests return SSE.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ImageResponse"
                },
                "examples": {
                  "url_image": {
                    "summary": "Edited image returned as URL",
                    "value": {
                      "created": 1792308678,
                      "data": [
                        {
                          "url": "https://example.com/edited-image.jpg",
                          "size": "2720x1536",
                          "revised_prompt": "Replace the cat with a Shiba Inu..."
                        }
                      ],
                      "output_format": "jpeg",
                      "usage": {
                        "generated_images": 1,
                        "total_tokens": 22836,
                        "input_tokens": 6536,
                        "output_tokens": 16300,
                        "input_tokens_details": {
                          "text_tokens": 3206,
                          "image_tokens": 3330
                        },
                        "output_tokens_details": {
                          "image_tokens": 16300
                        }
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ImageStreamEvent"
                },
                "examples": {
                  "sseExample": {
                    "summary": "SSE events",
                    "value": "event: image_edit.partial_succeeded\ndata: {\"type\":\"image_edit.partial_succeeded\",\"created\":1792308690,\"model\":\"MiniMax-H3-Image\",\"image_index\":1,\"url\":\"https://example.com/h3-image/edit-1.jpg\",\"size\":\"5440x3072\",\"output_format\":\"jpeg\",\"revised_prompt\":\"将图1中的橘猫替换为图2中的柴犬，柴犬坐在窗台上望向窗外，保持原有光线与背景\"}\n\nevent: image_edit.partial_failed\ndata: {\"type\":\"image_edit.partial_failed\",\"created\":1792308691,\"model\":\"MiniMax-H3-Image\",\"image_index\":2,\"code\":\"1027\",\"message\":\"output image failed content safety check\"}\n\nevent: image_edit.partial_succeeded\ndata: {\"type\":\"image_edit.partial_succeeded\",\"created\":1792308695,\"model\":\"MiniMax-H3-Image\",\"image_index\":0,\"url\":\"https://example.com/h3-image/edit-0.jpg\",\"size\":\"5440x3072\",\"output_format\":\"jpeg\",\"revised_prompt\":\"将图1中趴在窗台上的橘猫替换为图2中的柴犬，姿态改为趴卧，窗台、光线与背景保持不变\"}\n\nevent: image_edit.completed\ndata: {\"type\":\"image_edit.completed\",\"created\":1792308695,\"model\":\"MiniMax-H3-Image\",\"usage\":{\"generated_images\":2,\"total_tokens\":80450,\"input_tokens\":47810,\"output_tokens\":32640,\"input_tokens_details\":{\"text_tokens\":24186,\"image_tokens\":23624},\"output_tokens_details\":{\"image_tokens\":32640}},\"request_id\":\"021792308678142a2c883cf675b9804d\"}\n"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "documented_error": {
                "summary": "Error response",
                "value": {
                  "error": {
                    "message": "error_message",
                    "type": "error_type",
                    "param": "request_id",
                    "code": "error_code"
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "description": "Error response.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "documented_error": {
                "summary": "Error response",
                "value": {
                  "error": {
                    "message": "error_message",
                    "type": "error_type",
                    "param": "request_id",
                    "code": "error_code"
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "MiniMaxH3ImageGenerateRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "minimax-h3-image",
            "description": "Model name. This API is pinned to `minimax-h3-image`."
          },
          "prompt": {
            "type": "string",
            "description": "Text prompt describing the image to generate. Maximum 32000 characters."
          },
          "n": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "Number of images to generate."
          },
          "size": {
            "type": "string",
            "default": "auto",
            "description": "Output image size. Use `auto` or specify width x height, e.g. `2720x1536`."
          },
          "aspect_ratio": {
            "type": "string",
            "default": "auto",
            "description": "Aspect ratio. Use `auto` or specify `X:Y`, e.g. `16:9`, `3:4`."
          },
          "area": {
            "type": "string",
            "default": "4K",
            "enum": [
              "1K",
              "2K",
              "4K"
            ],
            "description": "Area tier for output resolution."
          },
          "output_format": {
            "type": "string",
            "default": "jpeg",
            "enum": [
              "png",
              "jpeg",
              "jpg",
              "webp"
            ],
            "description": "Output image format."
          },
          "response_format": {
            "type": "string",
            "default": "url",
            "enum": [
              "url",
              "b64_json"
            ],
            "description": "Response format. `b64_json` is not supported when `stream: true`."
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Whether to use SSE streaming. When `stream: true`, `response_format` must be `url`."
          },
          "output_compression": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 95,
            "description": "Output compression quality. `0` disables compression and `100` is maximum quality."
          },
          "aigc_watermark": {
            "type": "boolean",
            "default": false,
            "description": "Whether to add an AIGC watermark."
          },
          "disable_prompt_enhanced": {
            "type": "boolean",
            "default": false,
            "description": "Whether to disable prompt enhancement. Enabled by default."
          }
        }
      },
      "MiniMaxH3ImageEditRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "prompt",
          "image"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "minimax-h3-image",
            "description": "Model name. This API is pinned to `minimax-h3-image`."
          },
          "prompt": {
            "type": "string",
            "description": "Text prompt describing the edit to apply. Maximum 32000 characters."
          },
          "image": {
            "type": "string",
            "description": "Single reference image URL for editing."
          },
          "images": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "description": "Multiple reference image URLs for editing. When provided, `image` is ignored.",
            "items": {
              "type": "string"
            }
          },
          "n": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "Number of edited images to generate."
          },
          "size": {
            "type": "string",
            "default": "auto",
            "description": "Output image size."
          },
          "aspect_ratio": {
            "type": "string",
            "default": "auto",
            "description": "Aspect ratio."
          },
          "area": {
            "type": "string",
            "default": "4K",
            "enum": [
              "1K",
              "2K",
              "4K"
            ],
            "description": "Area tier for output resolution."
          },
          "output_format": {
            "type": "string",
            "default": "jpeg",
            "enum": [
              "png",
              "jpeg",
              "jpg",
              "webp"
            ],
            "description": "Output image format."
          },
          "response_format": {
            "type": "string",
            "default": "url",
            "enum": [
              "url",
              "b64_json"
            ],
            "description": "Response format."
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "Whether to use SSE streaming."
          },
          "output_compression": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 95,
            "description": "Output compression quality."
          },
          "aigc_watermark": {
            "type": "boolean",
            "default": false,
            "description": "Whether to add an AIGC watermark."
          }
        }
      },
      "MiniMaxH3ImageResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "created",
          "data"
        ],
        "properties": {
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp, in seconds, when the request was created."
          },
          "data": {
            "type": "array",
            "description": "Image results. Each item contains either a `url` or an `error`.",
            "items": {
              "$ref": "#/components/schemas/MiniMaxH3ImageData"
            }
          },
          "output_format": {
            "type": "string",
            "description": "Output image format."
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3ImageUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MiniMaxH3ImageData": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Generated or edited image URL. Expires in 24 hours."
          },
          "b64_json": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Base64-encoded image data. Only present when `response_format` is `b64_json`."
          },
          "size": {
            "type": "string",
            "description": "Image size in `width x height` format."
          },
          "revised_prompt": {
            "type": "string",
            "description": "The enhanced prompt used for generation."
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Error code."
              },
              "message": {
                "type": "string",
                "description": "Error message."
              }
            }
          }
        }
      },
      "MiniMaxH3ImageUsage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "generated_images": {
            "type": "integer",
            "description": "Number of successfully generated images."
          },
          "total_tokens": {
            "type": "integer",
            "description": "Total tokens used by the request."
          },
          "input_tokens": {
            "type": "integer",
            "description": "Input tokens used by the request."
          },
          "output_tokens": {
            "type": "integer",
            "description": "Output tokens used by the request."
          },
          "input_tokens_details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "text_tokens": {
                "type": "integer",
                "description": "Text input tokens."
              },
              "image_tokens": {
                "type": "integer",
                "description": "Image input tokens (only for image editing)."
              }
            }
          },
          "output_tokens_details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "image_tokens": {
                "type": "integer",
                "description": "Image output tokens."
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorObject"
          }
        }
      },
      "ErrorObject": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type."
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Request ID or parameter related to the error."
          },
          "code": null
        }
      },
      "MiniMaxH3ImageStreamEvent": {
        "description": "Server-Sent Events stream data payload. Each SSE `data` payload is one\nof `image_generation.partial_succeeded`, `image_generation.partial_failed`,\n`image_generation.completed`, or `error`. For image editing, the event prefix\nis `image_edit` instead of `image_generation`.\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/MiniMaxH3PartialSucceededEvent"
          },
          {
            "$ref": "#/components/schemas/MiniMaxH3PartialFailedEvent"
          },
          {
            "$ref": "#/components/schemas/MiniMaxH3CompletedEvent"
          },
          {
            "$ref": "#/components/schemas/MiniMaxH3StreamErrorEvent"
          }
        ],
        "discriminator": {
          "propertyName": "type"
        }
      },
      "MiniMaxH3PartialSucceededEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "created",
          "model",
          "image_index"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image_generation.partial_succeeded",
              "image_edit.partial_succeeded"
            ],
            "description": "Event type."
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds for when the request was created."
          },
          "model": {
            "type": "string",
            "description": "Model ID used for this request."
          },
          "image_index": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based image index for this request."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Generated or edited image URL. Expires in 24 hours."
          },
          "size": {
            "type": "string",
            "description": "Image size in `width x height` format."
          },
          "output_format": {
            "type": "string",
            "description": "Output image format."
          },
          "revised_prompt": {
            "type": "string",
            "description": "The enhanced prompt used for generation."
          }
        }
      },
      "MiniMaxH3PartialFailedEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "created",
          "model",
          "image_index"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image_generation.partial_failed",
              "image_edit.partial_failed"
            ],
            "description": "Event type."
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds for when the request was created."
          },
          "model": {
            "type": "string",
            "description": "Model ID used for this request."
          },
          "image_index": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based image index for this request."
          },
          "code": {
            "type": "string",
            "description": "Error code."
          },
          "message": {
            "type": "string",
            "description": "Error message."
          }
        }
      },
      "MiniMaxH3CompletedEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "created",
          "model",
          "usage"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image_generation.completed",
              "image_edit.completed"
            ],
            "description": "Event type."
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp in seconds for when the request was created."
          },
          "model": {
            "type": "string",
            "description": "Model ID used for this request."
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3ImageUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "MiniMaxH3StreamErrorEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "error"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "error",
            "description": "Event type."
          },
          "error": {
            "$ref": "#/components/schemas/ErrorObject"
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3ImageUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      }
    }
  }
}
```