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

# MiniMax-H3-Image 图像生成

>  - 使用 minimax-h3-image 标准版模型，擅长写实摄影、海报、产品图和带文字的画面
- 异步处理模式，返回 task_id 用于后续查询
- 支持文生图与最多 16 张参考图的图像编辑
- 一次最多生成 10 张图片，内置提示词增强（可关闭）
- 支持 1K / 2K / 4K 档位 + 宽高比，或直接指定像素（最大 2000 万像素） 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "黄昏时分的海边咖啡馆，写实摄影风格，暖色调",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "minimax-h3-image",
        "prompt": "黄昏时分的海边咖啡馆，写实摄影风格，暖色调",
        "size": "16:9",
        "resolution": "2K",
        "n": 1,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "minimax-h3-image",
      prompt: "黄昏时分的海边咖啡馆，写实摄影风格，暖色调",
      size: "16:9",
      resolution: "2K",
      n: 1,
    }),
  },
);

console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "请求参数无效",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份验证失败，请检查您的 API 密钥",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "账户余额不足，请充值后再试",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "服务器内部错误，请稍后重试",
    "type": "server_error"
  }
}
```

## 认证

**Authorization** `string` *required*

所有接口均使用 Bearer Token 认证。访问 [API Key 管理页面](https://apimart.ai/keys) 获取密钥。

```
Authorization: Bearer YOUR_API_KEY
```

## 模型说明

| 模型 | 特点 | 适用场景 |
| - | - | - |
| `minimax-h3-image` | 标准版，单价更低 | 批量出图、写实摄影、海报、产品图、带文字的画面 |
| `minimax-h3-image-highspeed` | 极速版，出图更快，图片输入 / 输出单价为标准版的 2 倍 | 对响应速度敏感的场景，详见 [MiniMax-H3-Image-Highspeed](https://docs.apimart.ai/cn/api-reference/images/minimax-h3-image-highspeed/generation.md) |

MiniMax H3 Image 默认会先把提示词自动扩写成详细的画面描述再出图，扩写后的内容可在查询结果的 `revised_prompt` 中查看。如需严格按原文出图，可参考 [关闭提示词增强](#关闭提示词增强)。

> [!WARNING]
>
> 不传 `resolution` 时默认输出 **4K**（约 1600 万像素），单价约为 1K / 2K 的 3 倍。不需要 4K 时请显式传入 `"resolution": "2K"`。

## 请求参数

**model** `string` *required*

图像生成模型名称，固定为 `minimax-h3-image`。

**prompt** `string` *required*

图像生成或编辑的文本描述。

支持中英文，去掉首尾空白后长度为 `1` \~ `32,000` 个字符。

**image\_urls** `string[]`

参考图数组，最多 `16` 张。传入后自动进入编辑模式。

每一项可以是公网可访问的 `http(s)://` 直链，也可以是 `data:image/png;base64,...` 格式的内联 Base64（平台会先转成链接再交给模型）。

详见 [参考图要求](#参考图要求)。

**size** `string` (default: auto)

输出图像的宽高比或精确像素尺寸。

支持：

* `auto`：由模型根据提示词决定构图和比例
* 宽高比：`X:Y` 格式，X、Y 为 `1` \~ `300` 的整数，比例在 `1:3` \~ `3:1` 之间（含边界），如 `1:1`、`4:3`、`16:9`、`9:16`、`3:1`
* 精确像素：`宽x高`，如 `2048x1152`（兼容 `X`、`×`、`*` 分隔符）

详见 [尺寸规则](#尺寸规则)。

**resolution** `string` (default: 4K)

分辨率档位，与宽高比配合决定实际输出像素。

* `1K`：约 100 万像素
* `2K`：约 420 万像素
* `4K`（默认）：约 1600 万像素

兼容小写写法。

> [!WARNING]
>
> `size` 使用精确像素格式时**不能**传 `resolution`，否则返回 400。

**n** `integer` (default: 1)

生成图片数量，取值范围为 `1` \~ `10`。

**prompt\_optimizer** `boolean` (default: true)

是否自动扩写提示词。

设为 `false` 仅对文生图生效，且必须明确指定尺寸，详见 [关闭提示词增强](#关闭提示词增强)。

**output\_format** `string` (default: jpeg)

输出文件格式。

* `jpeg`（默认，也可写作 `jpg`）
* `png`
* `webp`

**output\_compression** `integer` (default: 95)

压缩质量，范围为 `0` \~ `100`，对 `png` 不生效。

**watermark** `boolean` (default: false)

是否在图片上添加可见的 AI 生成水印。不影响图片元数据中的隐式标识。

> [!NOTE]
>
> 以下参数不支持，传入后会被忽略：`quality`、`style`、`seed`、`negative_prompt`、`background`、`mask_url`。
>
> 结果一律以 URL 返回，传入 `response_format: "b64_json"` 会返回 400。

## 尺寸规则

| 你想要 | 这样传 |
| - | - |
| 默认（4K、模型自选比例） | 不传尺寸参数 |
| 档位 + 宽高比 | `size: "16:9"`, `resolution: "2K"` |
| 只控制档位，比例由模型决定 | `resolution: "1K"`（`size` 不传或传 `auto`） |
| 精确控制到像素 | `size: "2048x1152"`（**不要再传 `resolution`**） |

### 档位 + 宽高比

档位决定总面积，宽高比决定形状：

| 档位 | 目标面积 | 实测输出示例 |
| - | - | - |
| `1K` | 约 1024×1024（约 100 万像素） | 自选比例 → 1184×880 |
| `2K` | 约 2048×2048（约 420 万像素） | `1:1` → 2048×2048 |
| `4K`（默认） | 约 4096×4096（约 1600 万像素） | 自选比例 → 3552×4736 |

实际输出像素由模型按比例和档位取整决定，以返回结果为准。如需精确尺寸，请使用像素写法。

### 精确像素

使用 `size: "宽x高"` 时需满足以下条件：

| 约束 | 取值 |
| - | - |
| 总像素（宽 × 高） | `655,360` \~ `20,000,000` |
| 宽高比 | `1:3` \~ `3:1` |
| 与 `resolution` | 不能同时传入 |

* ✅ `1024x1024`、`2048x1152`、`1536x1536`、`4000x5000`
* ❌ `512x512`（面积太小）、`4000x1000`（比例超过 3:1）、`5000x5000`（超过 2000 万像素）

## 参考图要求

| 项目 | 要求 |
| - | - |
| 张数 | 最多 16 张 |
| 格式 | JPG / JPEG / PNG / WebP / HEIC / HEIF（不支持 GIF） |
| 单张大小 | 不超过 64 MB |
| 单张尺寸 | 每条边 128 \~ 8192 像素，长边 ÷ 短边 ≤ 4 |

> [!WARNING]
>
> 使用 URL 时请确保链接**公网可访问**。链接无法访问时任务会在生成阶段失败（`status` 为 `failed`，费用全额退回）。
>
> 编辑模式下提示词增强始终开启，不能关闭。

## 关闭提示词增强

默认情况下模型会先扩写提示词再出图。如需严格按原文出图，可传入 `"prompt_optimizer": false`，前提是：

* 只能用于**文生图**，带有 `image_urls` 时会返回 400
* 必须**明确指定尺寸**：`size` 需为宽高比（如 `1:1`）或像素（如 `1024x1024`），不能为 `auto` 或不传

关闭后模型约只读取提示词的前 4096 个 token。

## Response

**code** `integer`

响应状态码，提交成功时为 200。

**data** `array`

提交响应数据。

**数组元素**

**status** `string`

初始状态为 `submitted`。

**task\_id** `string`

任务唯一标识符，用于查询任务状态和生成结果。

## 提交响应

提交成功后会立即返回异步任务 ID：

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## 查询任务结果

使用提交响应中的 `task_id` 调用 [任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md)：

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

实测单张 1K / 2K 约 10 \~ 20 秒、4K 约 20 秒，参考图编辑约 20 秒。建议每 3 \~ 5 秒轮询一次，直到状态变为 `completed` 或 `failed`。单个任务最长可运行 600 秒，客户端轮询超时建议设为 10 分钟。

### 任务成功

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "created": 1794450409,
    "completed": 1794450428,
    "actual_time": 19,
    "estimated_time": 60,
    "cost": 0.0493,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example_0.jpeg",
            "https://upload.apimart.ai/f/image/example_1.jpeg"
          ],
          "expires_at": 1794536828,
          "revised_prompt": "The image is a realistic, close-up still life photograph of ...",
          "revised_prompts": [
            "The image is a realistic ...",
            "The image is a professional ..."
          ]
        }
      ]
    }
  }
}
```

图片地址位于 `data.result.images[0].url[]`，`n` 张图都在这一个数组中，请在 `expires_at` 前下载转存。任务失败时 `status` 为 `failed`，原因见 `error.message`，费用会自动全额退回。

## 使用示例

### 文生图（默认 4K）

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "A cozy coffee shop by the sea at sunset, photorealistic, warm tones"
}
```

### 文生图（1K + 宽高比，一次 4 张）

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "极简风格的耳机产品图，白色背景，柔和阴影",
  "size": "1:1",
  "resolution": "1K",
  "n": 4
}
```

### 精确像素 + PNG

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "城市夜景海报，霓虹灯，赛博朋克风格，标题文字 NIGHT CITY",
  "size": "2048x1152",
  "output_format": "png"
}
```

### 参考图编辑

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "把第一张图里的人物换上第二张图的外套，保持背景不变",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/jacket.png"
  ],
  "resolution": "2K"
}
```

### 关闭提示词增强

```json theme={null}
{
  "model": "minimax-h3-image",
  "prompt": "a red apple on a wooden table, top view",
  "size": "1:1",
  "resolution": "1K",
  "prompt_optimizer": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.