# MiniMax-H3-Image 图像生成

> 图像生成

使用 `MiniMax-H3-Image` 模型生成一张或多张图像。

## 请求地址

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

## 请求体

## 响应

- **200** — 图像生成响应。非流式请求返回 JSON；流式请求返回 SSE。
- **400** — 
- **default** — 

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "ModelVerse MiniMax-H3-Image API",
    "version": "1.0.0",
    "description": "ModelVerse `MiniMax-H3-Image` 图像生成与图像编辑 API 的 OpenAPI 3.1 规范文档。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "中国大陆"
    },
    {
      "url": "https://api.umodelverse.ai",
      "description": "海外"
    },
    {
      "url": "https://api-us-ca.umodelverse.ai",
      "description": "美国洛杉矶"
    },
    {
      "url": "https://api-sg.umodelverse.ai",
      "description": "新加坡"
    },
    {
      "url": "https://api-ge-fra.umodelverse.ai",
      "description": "法兰克福"
    }
  ],
  "tags": [
    {
      "name": "MiniMax-H3-Image",
      "description": "`MiniMax-H3-Image` 的 OpenAI 兼容图像生成与图像编辑 API。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/images/generations": {
      "post": {
        "tags": [
          "MiniMax-H3-Image"
        ],
        "operationId": "createMiniMaxH3ImageGeneration",
        "summary": "MiniMax-H3-Image 图像生成",
        "description": "使用 `MiniMax-H3-Image` 模型生成一张或多张图像。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MiniMaxH3ImageGenerateRequest"
              },
              "examples": {
                "text_to_image": {
                  "summary": "文生图",
                  "value": {
                    "model": "minimax-h3-image",
                    "prompt": "一只可爱的橘猫趴在窗台上晒太阳",
                    "n": 1,
                    "size": "auto",
                    "aspect_ratio": "16:9",
                    "area": "4K"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "图像生成响应。非流式请求返回 JSON；流式请求返回 SSE。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ImageResponse"
                },
                "examples": {
                  "url_image": {
                    "summary": "返回 URL 格式的生成图像",
                    "value": {
                      "created": 1792308678,
                      "data": [
                        {
                          "url": "https://example.com/generated-image.jpg",
                          "size": "2720x1536",
                          "revised_prompt": "一只可爱的橘猫趴在窗台上晒太阳..."
                        }
                      ],
                      "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 事件",
                    "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 图像编辑",
        "description": "使用 `MiniMax-H3-Image` 模型编辑图像。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MiniMaxH3ImageEditRequest"
              },
              "examples": {
                "image_edit": {
                  "summary": "使用参考图进行图像编辑",
                  "value": {
                    "model": "minimax-h3-image",
                    "prompt": "把猫换成柴犬，保持背景不变",
                    "image": "https://example.com/cat.jpg",
                    "n": 1,
                    "size": "auto"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "图像编辑响应。非流式请求返回 JSON；流式请求返回 SSE。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniMaxH3ImageResponse"
                },
                "examples": {
                  "url_image": {
                    "summary": "返回 URL 格式的编辑后图像",
                    "value": {
                      "created": 1792308678,
                      "data": [
                        {
                          "url": "https://example.com/edited-image.jpg",
                          "size": "2720x1536",
                          "revised_prompt": "把猫换成柴犬，保持背景不变..."
                        }
                      ],
                      "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 事件",
                    "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": "请求参数无效。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "documented_error": {
                "summary": "错误响应",
                "value": {
                  "error": {
                    "message": "error_message",
                    "type": "error_type",
                    "param": "request_id",
                    "code": "error_code"
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "description": "错误响应。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "documented_error": {
                "summary": "错误响应",
                "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": "模型名称。该 API 固定为 `minimax-h3-image`。"
          },
          "prompt": {
            "type": "string",
            "description": "描述待生成图像的文本提示词。最长 32000 字符。"
          },
          "n": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "生成图像数量。"
          },
          "size": {
            "type": "string",
            "default": "auto",
            "description": "输出图像尺寸。使用 `auto` 或指定 `宽x高`，如 `2720x1536`。"
          },
          "aspect_ratio": {
            "type": "string",
            "default": "auto",
            "description": "宽高比。使用 `auto` 或指定 `X:Y`，如 `16:9`、`3:4`。"
          },
          "area": {
            "type": "string",
            "default": "4K",
            "enum": [
              "1K",
              "2K",
              "4K"
            ],
            "description": "输出分辨率面积档位。"
          },
          "output_format": {
            "type": "string",
            "default": "jpeg",
            "enum": [
              "png",
              "jpeg",
              "jpg",
              "webp"
            ],
            "description": "输出图像格式。"
          },
          "response_format": {
            "type": "string",
            "default": "url",
            "enum": [
              "url",
              "b64_json"
            ],
            "description": "返回格式。`stream: true` 时不支持 `b64_json`。"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否使用 SSE 流式返回。`stream: true` 时 `response_format` 必须为 `url`。"
          },
          "output_compression": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 95,
            "description": "输出压缩质量。`0` 表示禁用压缩，`100` 为最高质量。"
          },
          "aigc_watermark": {
            "type": "boolean",
            "default": false,
            "description": "是否添加 AIGC 水印。"
          },
          "disable_prompt_enhanced": {
            "type": "boolean",
            "default": false,
            "description": "是否关闭提示词增强。默认开启。"
          }
        }
      },
      "MiniMaxH3ImageEditRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "prompt",
          "image"
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "minimax-h3-image",
            "description": "模型名称。该 API 固定为 `minimax-h3-image`。"
          },
          "prompt": {
            "type": "string",
            "description": "描述待应用编辑的文本提示词。最长 32000 字符。"
          },
          "image": {
            "type": "string",
            "description": "用于编辑的单张参考图 URL。"
          },
          "images": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "description": "用于编辑的多张参考图 URL 列表。提供时 `image` 字段被忽略。",
            "items": {
              "type": "string"
            }
          },
          "n": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "编辑后图像数量。"
          },
          "size": {
            "type": "string",
            "default": "auto",
            "description": "输出图像尺寸。"
          },
          "aspect_ratio": {
            "type": "string",
            "default": "auto",
            "description": "宽高比。"
          },
          "area": {
            "type": "string",
            "default": "4K",
            "enum": [
              "1K",
              "2K",
              "4K"
            ],
            "description": "输出分辨率面积档位。"
          },
          "output_format": {
            "type": "string",
            "default": "jpeg",
            "enum": [
              "png",
              "jpeg",
              "jpg",
              "webp"
            ],
            "description": "输出图像格式。"
          },
          "response_format": {
            "type": "string",
            "default": "url",
            "enum": [
              "url",
              "b64_json"
            ],
            "description": "返回格式。"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否使用 SSE 流式返回。"
          },
          "output_compression": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 95,
            "description": "输出压缩质量。"
          },
          "aigc_watermark": {
            "type": "boolean",
            "default": false,
            "description": "是否添加 AIGC 水印。"
          }
        }
      },
      "MiniMaxH3ImageResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "created",
          "data"
        ],
        "properties": {
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "请求创建时的 Unix 时间戳（秒）。"
          },
          "data": {
            "type": "array",
            "description": "图像结果。每项包含 `url` 或 `error`。",
            "items": {
              "$ref": "#/components/schemas/MiniMaxH3ImageData"
            }
          },
          "output_format": {
            "type": "string",
            "description": "输出图像格式。"
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3ImageUsage"
          },
          "request_id": {
            "type": "string",
            "description": "唯一请求标识。"
          }
        }
      },
      "MiniMaxH3ImageData": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "生成或编辑后的图像 URL。有效期 24 小时。"
          },
          "b64_json": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "Base64 编码的图像数据。仅在 `response_format` 为 `b64_json` 时存在。"
          },
          "size": {
            "type": "string",
            "description": "图像尺寸，格式为 `宽 x 高`。"
          },
          "revised_prompt": {
            "type": "string",
            "description": "用于生成的增强后提示词。"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "错误码。"
              },
              "message": {
                "type": "string",
                "description": "错误信息。"
              }
            }
          }
        }
      },
      "MiniMaxH3ImageUsage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "generated_images": {
            "type": "integer",
            "description": "成功生成的图像数量。"
          },
          "total_tokens": {
            "type": "integer",
            "description": "请求消耗的总 Token 数。"
          },
          "input_tokens": {
            "type": "integer",
            "description": "输入 Token 数。"
          },
          "output_tokens": {
            "type": "integer",
            "description": "输出 Token 数。"
          },
          "input_tokens_details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "text_tokens": {
                "type": "integer",
                "description": "文本输入 Token 数。"
              },
              "image_tokens": {
                "type": "integer",
                "description": "图像输入 Token 数（仅图像编辑时存在）。"
              }
            }
          },
          "output_tokens_details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "image_tokens": {
                "type": "integer",
                "description": "图像输出 Token 数。"
              }
            }
          }
        }
      },
      "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": "错误信息。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。"
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "与错误相关的请求 ID 或参数。"
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "机器可读的错误码。"
          }
        }
      },
      "MiniMaxH3ImageStreamEvent": {
        "description": "Server-Sent Events 流数据载荷。每个 SSE `data` 载荷为以下之一：\n`image_generation.partial_succeeded`、`image_generation.partial_failed`、\n`image_generation.completed`、`error`。图像编辑时事件前缀为 `image_edit`。\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": "事件类型。"
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "请求创建时的 Unix 时间戳（秒）。"
          },
          "model": {
            "type": "string",
            "description": "本次请求使用的模型 ID。"
          },
          "image_index": {
            "type": "integer",
            "minimum": 0,
            "description": "本次请求中图像的零基索引。"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "生成或编辑后的图像 URL。有效期 24 小时。"
          },
          "size": {
            "type": "string",
            "description": "图像尺寸，格式为 `宽 x 高`。"
          },
          "output_format": {
            "type": "string",
            "description": "输出图像格式。"
          },
          "revised_prompt": {
            "type": "string",
            "description": "用于生成的增强后提示词。"
          }
        }
      },
      "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": "事件类型。"
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "请求创建时的 Unix 时间戳（秒）。"
          },
          "model": {
            "type": "string",
            "description": "本次请求使用的模型 ID。"
          },
          "image_index": {
            "type": "integer",
            "minimum": 0,
            "description": "本次请求中图像的零基索引。"
          },
          "code": {
            "type": "string",
            "description": "错误码。"
          },
          "message": {
            "type": "string",
            "description": "错误信息。"
          }
        }
      },
      "MiniMaxH3CompletedEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "created",
          "model",
          "usage"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image_generation.completed",
              "image_edit.completed"
            ],
            "description": "事件类型。"
          },
          "created": {
            "type": "integer",
            "format": "int64",
            "description": "请求创建时的 Unix 时间戳（秒）。"
          },
          "model": {
            "type": "string",
            "description": "本次请求使用的模型 ID。"
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3ImageUsage"
          },
          "request_id": {
            "type": "string",
            "description": "唯一请求标识。"
          }
        }
      },
      "MiniMaxH3StreamErrorEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "error"
        ],
        "properties": {
          "type": {
            "type": "string",
            "const": "error",
            "description": "事件类型。"
          },
          "error": {
            "$ref": "#/components/schemas/ErrorObject"
          },
          "usage": {
            "$ref": "#/components/schemas/MiniMaxH3ImageUsage"
          },
          "request_id": {
            "type": "string",
            "description": "唯一请求标识。"
          }
        }
      }
    }
  }
}
```