MiniMax H3-Image API 通过两个 REST 端点提供图像生成与编辑能力:POST /v1/images/generations 用于文生图,POST /v1/images/edits 用于结合 1 到 16 张参考图的图像编辑。你只需发送 Bearer 密钥、模型 ID MiniMax-H3-Image(或 MiniMax-H3-Image-Highspeed)、提示词和尺寸,即可拿回图像 URL 或 base64 数据。它与 MiniMax M3 API 位于同一个 MiniMax 开发者平台上,无需超分放大器即可输出最高约 1600 万像素(16 MP)的图像。
下文将依次介绍:API 密钥获取、关键请求参数、多参考图编辑、包含首发折扣的定价计算,以及用 Apifox CLI 让 Agent 自动执行的接口测试。刚接触这个模型?可以先了解 MiniMax H3-Image 是什么。
AI Coding 交流群
如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。
什么是 MiniMax H3-Image API?
MiniMax H3-Image API 是 MiniMax 为其开放权重模型 H3-Image 提供的托管接口,在同一个模型权重(checkpoint)中同时支持文生图和多参考图编辑。服务地址为 https://api.minimax.io,接收 JSON 请求,并且兼容 OpenAI SDK 的 images.generate 和 images.edit 调用——因此大多数现有的图像生成代码只需替换 base URL 和模型名称即可直接迁移。
该模型的权重同样公开:Hugging Face 模型卡 列出了遵循 MiniMax-H3-Image 社区许可证的 33.1B 参数扩散 Transformer。由于自托管需要约 69 GB 的模型权重外加 66.7 GB 的文本编码器,对大多数团队来说,直接调用 API 是更务实的选择。
以下是托管 API 的核心参数(整理自 2026-11-11 的 MiniMax API 参考文档):
| 项目 | 值 |
|---|---|
| Base URL | https://api.minimax.io |
| 模型 ID | MiniMax-H3-Image、MiniMax-H3-Image-Highspeed(参数与限制相同) |
| 文生图端点 | POST /v1/images/generations |
| 图像编辑端点 | POST /v1/images/edits(支持 1 到 16 张参考图) |
| 单次请求生成张数 | n 取值 1 到 10 |
| 输出格式 | jpeg(默认)、png、webp |
| 返回类型 | url(默认)或 b64_json |
| 服务端最长等待时间 | 600 秒 |

获取你的 MiniMax API 密钥
- 登录 MiniMax 开发者平台。
- 打开 Account Management(账户管理)下的 API Keys,创建一个新密钥。
- 充值账户余额。无余额的请求会以 HTTP 402 和错误码
1008(insufficient balance,余额不足)失败。 - 将密钥导出到环境变量中,让你的代码和 Agent 从环境读取,切勿写进会提交到仓库的文件:
export MINIMAX_API_KEY="your-key-here"
每次调用都通过请求头 Authorization: Bearer $MINIMAX_API_KEY 发送该密钥。
发出第一个文生图请求
最小可用的调用只需提供 model、prompt 以及精确尺寸或像素档位之一:
curl https://api.minimax.io/v1/images/generations \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
--max-time 600 \
-d '{
"model": "MiniMax-H3-Image",
"prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
"aspect_ratio": "16:9",
"area": "2K",
"n": 1,
"response_format": "url"
}'
如果使用 OpenAI Python SDK,只需将 base_url 指向 MiniMax 并关闭自动重试:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key=os.environ["MINIMAX_API_KEY"],
timeout=600,
max_retries=0,
)
result = client.images.generate(
model="MiniMax-H3-Image",
prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
size="2720x1536",
response_format="url",
)
for item in result.data:
print(item.url) # 失败的图像项此处为 None
max_retries=0 这一行非常关键。该端点不是幂等的:即使客户端超时断开,服务端仍会完成生成任务并照常扣费,因此自动重试会导致重复计费。请改用设置 600 秒超时时间来应对长耗时请求。
关键请求参数详解
你可以通过两种方式控制输出尺寸,但两者不能混用。
方式一:精确像素(Exact pixels)。 将 size 设为 WIDTHxHEIGHT(例如 4096x4096)。总像素面积必须在 655,360 到 20,000,000 之间,宽高比在 1:3 到 3:1 之间。在此模式下不要传 aspect_ratio 或 area(哪怕传 auto 也不行),否则会返回 400 错误。
方式二:档位加宽高比(Tier plus ratio)。 将 size 保持为 auto,同时设置 area(1K、2K 或 4K,默认 4K)和 aspect_ratio(1:3 到 3:1 之间的任意 X:Y)。服务端会自动换算像素尺寸;例如 2K 搭配 16:9 会返回 2720 x 1536。
其他常用字段如下:
| 字段 | 默认值 | 作用说明 |
|---|---|---|
prompt |
必填 | 最长 32,000 个字符 |
disable_prompt_enhanced |
false |
提示词增强会将简短提示词改写为细节丰富的描述;改写结果会在响应的 revised_prompt 中返回 |
n |
1 | 生成 1 到 10 张图像 |
output_format |
jpeg |
可选 png、jpeg 或 webp |
output_compression |
95 | 取值 0 到 100,仅对 JPEG 和 WebP 生效 |
response_format |
url |
可选 url 或 b64_json |
stream |
false |
服务端推送事件(SSE),每生成完一张推送一次,仅支持 url 模式 |
有两条规则容易踩坑:第一,如果你关闭了提示词增强(disable_prompt_enhanced: true),就必须传入精确的 size 或显式的 aspect_ratio,此时传 auto 会返回 400。第二,b64_json 限制了单次响应的总输出像素面积:PNG 上限为 20,000,000 像素(任意尺寸的单张图像),JPEG 或 WebP 上限为 80,000,000 像素(四张 4K 图像或十张 2K 图像)。如果需要更大批量的返回结果,请使用 URL 模式。
模型卡指出 H3-Image 在 16 MP 左右效果最佳:例如 4096x4096(1:1)、5472x3072(16:9)或 6272x2688(21:9)。
使用最多 16 张参考图编辑图像
图像编辑使用相同的参数字段,并额外增加一个 images 数组。在提示词中按顺序位置引用输入图片(如“image 1”、“image 2”):
import os, requests
resp = requests.post(
"https://api.minimax.io/v1/images/edits",
headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
json={
"model": "MiniMax-H3-Image",
"prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
"images": [
{"image_url": "https://example.com/cat.jpg"},
{"image_url": "https://example.com/dog.png"},
],
"size": "auto",
"response_format": "url",
},
timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])
该端点同样接受 multipart/form-data,这也是你使用 OpenAI SDK 的 images.edit 上传本地文件时发送的格式。根据 图像编辑参考文档,输入限制如下:
- 支持 1 到 16 张图像,格式可为 JPG、PNG、WebP、HEIC 或 HEIF
- 单边像素在 128 到 8,192 之间,长短边比例不超过 4:1
- 整个请求体最大 64 MiB;由于 base64 编码会使体积膨胀约三分之一,处理大图时建议改用公开 URL
解析响应与错误处理
调用成功后,响应会按顺序为每张请求的图像返回一个 data 元素:
{
"data": [
{"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
{"error": {"code": "1027", "message": "output image failed content safety check"}}
],
"output_format": "jpeg",
"usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
"request_id": "0217..."
}
养成以下三个习惯可以让你的接入更加稳健:
- 逐项检查
error字段。 只要有至少一张图像生成成功,HTTP 状态码就是 200,因此收到 200 并不代表请求的n张图像全部成功返回。如果所有图像均失败,则会返回 402、422 或 500。 - 立即下载返回的 URL。 MiniMax 表示不保证结果 URL 长期有效,因此请及时将图片转存到你自己的存储服务中。
- 记录
request_id。 这是联系技术支持排查问题时必需的追踪 ID。
触发速率限制时会返回 429。错误码 1002 表示你超过了每分钟生成张数上限,而且单次请求会按 n 张图像计入配额,因此一次请求生成 10 张会瞬间消耗 10 张配额。
MiniMax H3-Image 定价与首发折扣
API 按 token 计费,且只对生成成功的图像收费。以下是 2026-11-11 从 MiniMax 定价页面 读取的费率:
| 模型 | 输入文本 / 1M tokens | 输入图像 / 1M tokens | 输出图像 / 1M tokens |
|---|---|---|---|
| MiniMax-H3-Image | $2.30 | $1.50 | $3.80 |
| MiniMax-H3-Image-Highspeed | $2.30 | $3.00 | $7.60 |
MiniMax 同时公布了标准版模型的单张图像估算成本:
| 任务 | 输出规格 | 单张图像示例成本 |
|---|---|---|
| 文生图 | 1K (1024 x 1024) | $0.02179 |
| 文生图 | 2K (2048 x 2048) | $0.02333 |
| 文生图 | 4K (4096 x 4096) | $0.06879(首发优惠期间为 $0.03439) |
Highspeed 高速版的单张成本大约是标准版的 1.6 到 2 倍(4K 下为 $0.13001,折后 $0.06501)。提示词长度会影响输入侧的 token 消耗,因此请将这些数字视为估算值。
首发优惠: 在 2026 年 11 月 17 日 16:00 UTC 之前,当交付图像的像素数达到至少 16,600,000 时,MiniMax 会对两款模型的整次请求总费用减免 50%。4096x4096 的图像(16,777,216 像素)符合条件;2K 图像则不符合。如果你想寻找 $0 的免费使用方式,可以参考免费使用 MiniMax H3-Image 的方法。
让编码 Agent 用 Apifox CLI 测试接口
图像 API 很容易“静默失败”:返回了 200 但少了一半图片,或者不小心违反了某条尺寸互斥规则。你可以让编码 Agent(Claude Code、Codex、Cursor)配合 Apifox CLI 构建可重复运行的自动化测试,而不必每次手动检查响应体。

先安装 CLI 并完成登录与分类查询:
npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_APIFOX_TOKEN>
apifox test-case category --project <PROJECT_ID>
然后给你的 Agent 一条提示词:
In Apifox project <PROJECT_ID>, configure an environment "MiniMax Global" with base URL
https://api.minimax.io and Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case for POST /v1/images/generations that sends model MiniMax-H3-Image,
area 1K, aspect_ratio 1:1, n 1, and asserts HTTP 200, data[0].url exists,
and no item in data has an error field.
Validate the payload against the CLI schema, run it and summarize any failures.
Agent 会读取 payload schema、校验 JSON、创建测试用例并执行运行(命令参数均对照 Apifox CLI 2.2.12):
apifox cli-schema get test-case-create
apifox cli-schema validate test-case-create --file case.json
apifox test-case create --project <PROJECT_ID> --file case.json
apifox test-case run <CASE_ID> --project <PROJECT_ID> -e <ENV_ID> -r cli,json
将 API 密钥保存在项目的私有环境变量中,避免写进版本库文件。cli 报告器会逐条打印断言的通过或失败状态;json 报告器则会写出结构化报告供 Agent 读取。建议将日常回归测试保持在 1K 档位,因为每次运行都会产生真实的生成计费。同一条命令加上 -r junit 即可直接放入 CI 流水线中运行。
标准版还是 Highspeed:该选哪个模型 ID?
两个模型 ID 接收完全一致的参数,因此切换模型只需改一个字符串。最终交付素材和对成本敏感的批量任务建议使用 MiniMax-H3-Image;而对延迟比单价更敏感的交互式预览场景则可使用 MiniMax-H3-Image-Highspeed。API 参考文档没有列出具体的延迟秒数,建议用你自己的提示词实测计时。正在评估其他备选方案?可以对比阅读 MiniMax H3-Image 与 Nano Banana 2.1、Nano Banana 2.1 API 指南或 GPT Image 2.6 API 指南。
常见问题
MiniMax H3-Image 的模型 ID 是什么? 标准版模型使用 MiniMax-H3-Image,速度更快、价格更高的版本使用 MiniMax-H3-Image-Highspeed。两者在 /v1/images/generations 和 /v1/images/edits 上均可使用,且参数完全一致。
MiniMax H3-Image API 兼容 OpenAI SDK 吗? 兼容。只需设置 base_url="https://api.minimax.io/v1" 并调用 images.generate 或 images.edit 即可。请务必设置 max_retries=0,因为自动重试会触发新的计费生成任务。
图像编辑最多可以使用多少张参考图? 单次请求支持 1 到 16 张参考图,每张图片单边像素在 128 到 8,192 之间,整个请求体不超过 64 MiB。
生成一张 MiniMax H3-Image 图像需要多少钱? 根据 MiniMax 官方示例,标准版文生图调用在 1K 下约为 $0.022,在 4K 下约为 $0.069;在 2026 年 11 月 17 日 16:00 UTC 之前,4K 图像可享半价优惠(约 $0.034)。
为什么返回了 HTTP 200,但生成的图片数量比请求的少? 部分成功时接口也会返回 200。生成失败的条目(包括被内容安全检查拦截的图像)会携带 error 对象而不是 url,并且失败的图像不会向你收费。