minimax h3-image怎样通过api生成指定尺寸图片？先用minimax-h3-image向/v1/images/generations提交提示词和一种尺寸配置，再逐项读取返回的data。固定宽高不能与aspect_ratio、area混用；批量请求即使返回http 200，也要检查每张图是否成功。下面按首次接入、尺寸设置和异常处理说明具体用法。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
接入前先选清服务方式
H3-Image支持文生图、参考图生成和编辑。MiniMax API Platform、MiniMax Code与Hailuo AI提供使用入口，官方也开放模型权重。本文采用托管API，准备好有相应服务权限和余额的账户，以及自己的API Key；密钥通过环境变量MINIMAX_API_KEY读取，避免写进代码、网页或日志。
标准模型标识为MiniMax-H3-Image，高速版本为MiniMax-H3-Image-Highspeed。两者使用相同参数与限制，切换时修改model即可。官方公布的4096×4096生成时间属于厂商测试，不能把它当作自己网络、并发和所有请求的固定完成时间。
先生成一张固定尺寸图片
下面示例需要Python环境及requests包。配置MINIMAX_API_KEY后运行，向官方地址发送一次文生图请求。这里使用2720×1536横图、n=1，先确认鉴权和结果处理，再增加数量；本文未执行付费生成或性能测试。
import os
import requests
response = requests.post(
"https://api.minimax.io/v1/images/generations",
headers={"Authorization": "Bearer " + os.environ["MINIMAX_API_KEY"]},
json={
"model": "MiniMax-H3-Image",
"prompt": "一只橘猫躺在窗台上晒太阳，温暖的午后光线，胶片质感",
"size": "2720x1536",
"n": 1,
"response_format": "url"
},
timeout=600
)
response.raise_for_status()
result = response.json()
for index, item in enumerate(result["data"]):
if "error" in item:
print(index, item["error"])
else:
print(index, item["url"], item["size"])
成功项目会给出图片URL和实际size，失败项目包含error。拿到URL后应下载并自行保存所需图片，不要把接口响应当成已经落盘。一次请求允许生成1至10张，默认1张；输出格式支持JPEG、PNG和WebP，默认JPEG。
按版式选择尺寸，避免400错误
固定宽高适合已有设计尺寸的任务，例如示例的size。宽×高必须在655360至20000000像素之间，宽高比在1:3至3:1之间，均含边界。不符合时返回400，服务不会自动缩放或取整替你修正。
若更关心版式和清晰度档位，可删除size，改传aspect_ratio与area。例如aspect_ratio为16:9、area为4K时，文档给出的输出是5472×3072；1:1的4K才是4096×4096。area可选1K、2K、4K，表示目标面积档，最终以每张返回的size为准。
两种方式只能选一种：size写成固定宽高时，再传aspect_ratio或area会报400。文生图默认启用提示词增强；如果设置disable_prompt_enhanced为true，必须给出固定宽高或明确比例，不能继续只依赖自动比例。data中的revised_prompt可帮助检查实际采用的描述。
有参考图时改用编辑接口
编辑请求发往/v1/images/edits，通过images数组传入1至16张参考图，每项使用image_url。可用公开图片URL、已上传文件的mm_file引用或Base64数据URI；公开URL需要服务能够访问。提示词应明确各图的角色，例如保留第一张背景、以第二张替换主体，避免只写“合成一下”。这属于输入组织建议，并不保证所有细节都能准确保留。
参考图支持JPG、JPEG、PNG、WebP、HEIC和HEIF；单图不超过64 MiB，宽高各在128至8192像素之间，长短边比不超过4:1。整个请求体也不得超过64 MiB，Base64会增大体积，大图宜使用公开URL或文件引用。编辑始终启用提示词增强，目前不支持遮罩编辑、透明背景或预览图。
批量生成怎么判断成功，超时后怎么办
至少一张成功时，请求就可能返回200；因此业务层要检查所有data项目，并读取usage.generated_images统计成功数。全部失败时，内容安全检查可能对应422，余额不足对应402，其他失败对应500。不能用一个HTTP状态把整批标记为成功。
需要逐张尽早展示时可设stream=true，流式只支持URL响应；结果按完成顺序推送，要用image_index识别各张图，不能用到达顺序代替序号。若使用OpenAI SDK接入，将base_url设为https://api.minimax.io/v1，并参考官方示例设置max_retries=0：生成请求不具备幂等性，自动重试可能再次生成与收费。超时意味着结果未确定，不等于服务没有生成，业务上应避免直接整批重发。
付费与自行部署需要分别检查什么
首发公告中的五折只针对首发周4K及以上生成请求，不应扩展到所有尺寸；实际使用按所选入口当前价格结算。下载开放权重自行运行还涉及MiniMax-H3-Image社区许可证：适用地域排除欧盟、英国、韩国和美国；使用方及关联方年化收入超过100万美元，或向第三方提供托管服务，需要事先取得单独书面授权。接API与自行部署应分别核对服务规则和模型许可。
