这篇适合谁
这篇适合想用 API 做文生图或参考图改图的开发者。读完后,你应该能跑通一次文生图和一次改图,会设置输出尺寸,也知道失败时接口会返回什么。
MiniMax-H3-Image 能做什么
MiniMax-H3-Image 支持文生图和图像编辑[1]。单张输出的面积最大可达 2000 万像素,宽高可以自定义,也可以只给宽高比和面积档位[1]。
两种模式对应两个接口。文生图是 POST /v1/images/generations,只需要提示词;图像编辑是 POST /v1/images/edits,需要提示词加 1 到 16 张参考图[1]。两个接口都是同步的,开启 stream 后,每张图生成完会立即推送[1]。
如果想用高速版,可以把 model 换成 MiniMax-H3-Image-Highspeed。它的参数和限制与标准版一致[1]。
准备
示例用 OpenAI SDK 调用,把 base_url 设为 https://api.minimax.io/v1,key 从环境变量 MINIMAX_API_KEY 读取[1]。下面的代码都基于这个写法。
第一张图:文生图
调用 client.images.generate,传入模型名、提示词、尺寸和 response_format="url"。返回的 url 可以直接下载。图片生成失败时,对应的 url 为空[1]:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key=os.environ.get("MINIMAX_API_KEY"),
timeout=600,
max_retries=0, # not idempotent: disable automatic retries to avoid duplicate generation and charges
)
result = client.images.generate(
model="MiniMax-H3-Image",
prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
size="2720x1536",
response_format="url",
)
for i, item in enumerate(result.data):
print(i, item.url) # url is None for images that failed代码里的 max_retries=0 是有意为之。这个接口不是幂等的,自动重试可能导致重复生成,也可能重复计费[1]。
控制输出尺寸
尺寸有两种设置方式,只能用一种。使用 size 写成 WIDTHxHEIGHT 时,再设置 aspect_ratio 或 area 会返回 400[1]。
第一种是宽高比加面积档位。area 可选 1K、2K 和 4K,默认是 4K,对应的目标面积分别是 1024×1024、2048×2048 和 4096×4096 像素。aspect_ratio 默认是 auto,也可以写成 X:Y,比例需要在 1:3 到 3:1 之间。服务器会根据比例算出实际宽高,比如 2K 配 16:9 会输出 2720×1536[1]。
第二种是直接写宽高。面积必须在 655,360 到 20,000,000 像素之间,比例同样限定在 1:3 到 3:1,边界值包含在内。超出范围会返回 400,尺寸也不会被偷偷缩放或取整[1]。
常用尺寸可以直接照抄。16:9 的 2K 是 2720x1536,4K 是 5472x3072;9:16 的 2K 是 1536x2720,4K 是 3072x5472[1]。
提示词增强和 revised_prompt
文生图默认开启提示词增强。如果关闭它(disable_prompt_enhanced: true),就必须给出宽高,或者固定的 X:Y 比例,否则返回 400[1]。改图则一直会做提示词增强[1]。
实际用于每张图的提示词会放在 data[].revised_prompt 里[1]。想微调的时候,可以把 revised_prompt 改一改,作为新的 prompt 发起文生图请求,并同时设置 disable_prompt_enhanced: true[1]。如果只想看增强后的提示词而不生成图片,可以调用 H3-Image-Context-IR 接口,它只支持 MiniMax-H3-Image[1]。
改图:参考图怎么传
改图时,参考图放在 images[].image_url 里。它可以是公网 URL,也可以是 mm_file://{file_id},表示先用 purpose 为 image_generation_input 的文件上传接口传好的文件,还可以是 data:image/<format>;base64,<Base64> 形式的 data URI[1]。
用 OpenAI SDK 时,也可以直接用 images.edit 以 multipart/form-data 上传图片文件。文件的顺序就是「Picture 编号」,也就是提示词里说的「图 1」「图 2」[1]:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimax.io/v1",
api_key=os.environ.get("MINIMAX_API_KEY"),
timeout=600,
max_retries=0, # not idempotent: disable automatic retries to avoid duplicate generation and charges
)
# Upload reference images as files; list order is the Picture number
result = client.images.edit(
model="MiniMax-H3-Image",
image=[open("cat.jpg", "rb"), open("dog.png", "rb")],
prompt="Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
size="auto",
response_format="url",
)
for i, item in enumerate(result.data):
print(i, item.url) # url is None for images that failed参考图的限制如下[1]:
- 格式:JPG、JPEG、PNG、WEBP、HEIC 和 HEIF。
- 单个文件不超过 64 MiB,宽和高都在 128 到 8192 像素之间,长边和短边的比例不超过 4:1。
- 数量为 1 到 16 张。
- 整个请求体不超过 64 MiB。Base64 数据大约是文件大小的 4/3,如果请求体会超限,就改用公网 URL 或
mm_file://。
失败怎么处理
只要有一张图成功,请求就返回 200。data 的长度等于 n,失败或被内容安全检查拦下的那一项只含 error,成功数量在 usage.generated_images 里[1]:
"data": [
{"url": "https://example.com/h3-image/output-0.jpg", "size": "2720x1536", "revised_prompt": "..."},
{"error": {"code": "1027", "message": "output image failed content safety check"}}
]如果全部失败,返回的是错误响应,并且仍然附带每张图的 data 和 usage。全部没通过内容安全检查时是 422,余额不足导致全部失败时是 402,其他情况是 500[1]。
流式输出
设置 stream: true 后,每张图完成就会通过 SSE 推送,并且只支持 response_format: "url"。事件按完成顺序到达,要用 image_index 来对应是哪一张[1]。
主要的事件有 <prefix>.partial_succeeded(一张成功)、<prefix>.partial_failed(一张失败)和 <prefix>.completed(全部结束,带有 usage)。error 事件表示没有任何一张成功,这种情况不计费,所有 usage 字段都是 0。前缀在文生图里是 image_generation,在改图里是 image_edit[1]。
限制
- 不支持预览图、遮罩编辑和透明背景[1]。
- 提示词最长 32000 个字符。关闭提示词增强时,大约只有前 4096 个 token 会生效[1]。
- 单次最多生成 10 张,默认 1 张。输出格式默认是 jpeg,也可以是 png 或 webp[1]。
下一步
官方的参考页面分别列出了文生图、图像编辑和流式事件的接口说明,字段细节以那里为准[1]。
来源
- 1Image Generation GuideMiniMax API docs
引用本页: MiniMax-H3-Image 文生图与改图 API 上手. TellWorld, https://www.tellworld.net/zh/practice/practice-minimax-h3-image-api. 更新于 2026-11-15