Python怎么批量保存MiniMax H3-Image图片并处理部分失败

月亮慢半拍

发布时间：2026-11-13| 6人浏览过

原创

用Python区分H3-Image的生成失败和下载失败，保存返回结果与成功图片，说明尺寸配置、参考图限制及非幂等请求的重试边界。

用Python批量调用MiniMax H3-Image时，怎样避免漏掉失败图片或重复生成？关键是把“发起生成”和“保存结果”分开处理：生成只发一次，遍历data逐项识别error，再下载成功图片，并记录实际尺寸与成功数。HTTP 200只表示至少有一张成功，不能直接把整批标为完成。

MiniMax H3-Image开放权重模型封面

先明确一批图片有哪些结果

H3-Image的文生图端点为/v1/images/generations，编辑端点为/v1/images/edits。每次可请求1至10张图片，默认1张；标准模型使用MiniMax-H3-Image，Highspeed版本使用MiniMax-H3-Image-Highspeed，两者参数和限制一致。

至少一张生成成功，服务就可能返回HTTP 200。data中成功项包含url、size等结果，失败项包含error；usage.generated_images记录成功张数。因此，Python程序既要处理HTTP错误，也要处理HTTP成功响应里的单图失败。

MiniMax H3-Image生成与编辑接口及输入输出规格

用一次请求保存成功结果和失败记录

准备有服务权限和余额的MiniMax账户、API Key，以及安装了requests的Python环境。把密钥设置在MINIMAX_API_KEY环境变量中。示例请求两张2K横图，使用当前官方接口；这段代码展示接入方法，本文未执行付费生成。

import json
import os
from pathlib import Path
import requests

folder = Path("h3-output")
folder.mkdir(exist_ok=True)
response = requests.post(
    "https://api.minimax.io/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["MINIMAX_API_KEY"]},
    json={
        "model": "MiniMax-H3-Image",
        "prompt": "玻璃花瓶中的白色鲜花，柔和自然光，浅色背景",
        "aspect_ratio": "16:9",
        "area": "2K",
        "n": 2,
        "response_format": "url"
    },
    timeout=600
)
response.raise_for_status()
result = response.json()
(folder / "response.json").write_text(
    json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
)
for index, item in enumerate(result["data"]):
    if "error" in item:
        print("生成失败", index, item["error"])
        continue
    try:
        image = requests.get(item["url"], timeout=60)
        image.raise_for_status()
        target = folder / f"image-{index}.{result['output_format']}"
        target.write_bytes(image.content)
        print("已保存", target, item["size"])
    except requests.RequestException as error:
        print("下载失败，保留生成结果", index, type(error).__name__)
print("生成成功数", result["usage"]["generated_images"])

运行后，response.json保留本次结果，成功下载的文件写入h3-output目录。下载失败与生成失败是两种状态：已经有成功URL时，优先依据保存的结果处理下载，不要为了重新下载而再次调用生成接口。结果文件可能包含访问地址和提示词，按自己的数据管理要求保管。

为什么不能直接重试整个生成函数

生成请求不具备幂等性。网络超时或连接中断后，客户端可能没拿到结果，但服务端是否生成仍不确定；再次提交可能产生另一批图片和费用。使用OpenAI SDK时，官方示例把max_retries设为0，并将base_url设为https://api.minimax.io/v1。自己的任务队列也应区分未提交、结果未知、部分成功和已保存，避免把所有异常统一放回自动重试队列。

全部图片失败时，服务会返回错误：全部被内容安全检查拦截可能是422，全部余额不足是402，其他原因是500，并包含相应data与usage。上例的raise_for_status会先抛出HTTP异常；正式业务若要保存此类详情，应在异常分支读取并记录脱敏的错误响应，再按原因处理。不要记录Authorization头或密钥。

输出尺寸应该怎样写

示例用aspect_ratio配合area，不传固定size。area可选1K、2K、4K，宽高比限制为1:3至3:1；16:9的2K示例输出2720×1536，4K则为5472×3072。4K表示面积档，并非所有图片的两边都是4096像素，最终检查每项size。

如果业务需要精确宽高，可改用size，例如2720x1536，同时删除aspect_ratio与area。自定义面积须在655360至20000000像素之间，比例仍在1:3至3:1之间，均包含边界；越界返回400，不会自动缩放或取整。固定size与比例、面积档混传也会返回400。

文生图默认开启提示词增强。关闭时设置disable_prompt_enhanced=true，并提供固定宽高或明确比例；可通过revised_prompt了解每张图实际使用的描述。需要边完成边展示时可启用stream，流式只支持URL响应，并按完成顺序送达，要使用image_index关联结果。

改成参考图编辑时要检查什么

编辑接口通过images中的image_url接收1至16张参考图，支持公开URL、mm_file文件引用和Base64数据URI。格式可为JPG、JPEG、PNG、WebP、HEIC、HEIF；单图最大64 MiB，宽高各128至8192像素，长短边比不超过4:1，整个请求体也不得超过64 MiB。Base64会增加体积，较大的输入宜使用URL或文件引用。

编辑始终开启提示词增强；当前不支持预览图、遮罩编辑和透明背景。多参考图能力不保证每个主体细节都保持正确，应该先用少量真实任务检查效果，再决定批量规模。官方公布的速度属于厂商测试，不能当成自己的超时或性能承诺。

托管调用和下载权重怎样选择

只想调用服务，可使用MiniMax API Platform、MiniMax Code或Hailuo AI等入口，无需先下载权重。首发周五折仅覆盖4K及以上生成请求，实际费用按所选入口当前规则确认。自行部署还要遵守MiniMax-H3-Image社区许可证：适用地域排除欧盟、英国、韩国和美国；使用方及关联方年化收入超过100万美元，或向第三方提供托管服务，需要事先取得单独书面授权。开放权重不能直接理解为任意商业场景都无需额外许可。