MiniMax H3 Image 图像生成 | ToAPIs Documentation

POST

/v1/images/generations

中国大陆用户请使用 https://toapis.cn 作为接口地址. 可用性和价格以当前站点及账户的控制台展示为准.

使用 minimax-h3-image 生成图片, 或传入参考图进行编辑. 接口先返回任务 id, 再通过图片任务状态获取结果. 模型概览和计费说明见接入说明.

Authorizations

Authorizationstring请求头必填

使用平台访问令牌, 请求头格式为 Authorization: Bearer <token>. 令牌可在所在站点的控制台管理.

Body

请求类型为 application/json. 以下模型选项均可在请求体顶层传入.

modelstring请求体必填默认值: minimax-h3-image

固定为 minimax-h3-image.

promptstring请求体必填

文字描述或编辑指令. 去除首尾空白后须包含 1-32000 个 Unicode 字符, 不能仅包含空白.

ninteger请求体默认值: 1

请求生成的图片数量, 范围为 1-10. 实际成功数量可能小于请求数量.

sizestring请求体默认值: auto

省略或设为 auto 时, 使用 resolution 和 aspect_ratio 决定尺寸. 也可传 1024x1024 等显式像素尺寸, 宽高为正整数, 总像素范围为 655360-20000000, 宽高比须在 1:3 到 3:1 之间.

显式像素尺寸不能同时传 resolution 或 aspect_ratio, 即使后者为 auto 也不允许. 此时不补默认 4K.

兼容 16:9 等比例写法, 等价于 aspect_ratio. 若两个字段都填写比例, 必须一致. 分辨率档位请使用 resolution, 不要填写 size: "4K".

aspect_ratiostring请求体默认值: auto

支持 auto 或 宽:高 比例, 如 1:1, 4:3, 16:9. 宽高分量分别为 1-300 的整数, 比例须在 1:3 到 3:1 之间. 不能与显式像素 size 同时使用.

resolutionstring请求体默认值: 4K

仅支持大写 1K, 2K, 4K. 这是分辨率档位, 不是固定宽高, 实际尺寸以结果的 size 为准. 不能与显式像素 size 同时使用.

image_urlsstring[]请求体

可选的参考图 URL 列表, 最多 16 张. 使用可访问的 HTTP(S) URL, 不允许 URL 内嵌用户名或密码, 不支持 Base64 或 data URI. 传入参考图时按编辑处理, 始终开启提示词增强.

地址须可由图片处理服务访问, 不能依赖本地网络或浏览器登录状态. 浏览器中能打开图片不代表编辑一定成功; 提交后仍须检查最终任务状态和错误信息.

output_formatstring请求体默认值: jpeg

支持 jpeg, jpg, png, webp. jpg 等价于 jpeg.

response_formatstring请求体默认值: url

仅支持 url. 结果中的图片 URL 在任务完成后返回, 不在提交响应中返回图片内容.

output_compressioninteger请求体默认值: 95

范围为 0-100, 数值越大画质越高, 文件通常越大. 仅对 JPEG 和 WebP 生效, PNG 忽略此选项.

disable_prompt_enhancedboolean请求体默认值: false

是否关闭提示词增强. 仅纯文生图可以设为 true, 且必须同时提供显式像素 size 或固定比例. 传入参考图时不能设为 true.

aigc_watermarkboolean请求体默认值: false

是否添加可见 AIGC 水印. 此开关不控制图片文件元数据中的标识.

webhookstring请求体

可选的任务完成回调地址, 详见任务 Webhook.

不支持的参数

不要传入 area, mask, mask_url, background, quality, partial_images, preview, previous_task_id, image_size, seed, watermark, prompt_extend, 包括同名 metadata 字段. 分辨率使用 resolution, 可见水印使用 aigc_watermark.

不支持 stream=true, Base64 输入或输出及 multipart 文件上传. 请勿套用其他图片模型的参数或默认值.

请求示例

curl --request POST \
  --url 'https://toapis.com/v1/images/generations' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image",
    "prompt": "一座临海的小屋, 水彩插画风格",
    "n": 1,
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "response_format": "url"
  }'

显式像素尺寸示例, 不再传分辨率或比例:

{
  "model": "minimax-h3-image",
  "prompt": "一座临海的小屋, 水彩插画风格",
  "size": "1536x1024",
  "n": 1,
  "output_format": "webp",
  "output_compression": 90
}

提交响应

以下仅为响应结构示例:

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "minimax-h3-image",
  "status": "queued",
  "progress": 0,
  "created_at": 1794355200
}

保存 id, 通过 GET /v1/images/generations/{task_id} 查询; 也可使用 GET /v1/tasks/{task_id}. 轮询至少间隔 5-10 秒并加入抖动, 遇到 429 时遵循 Retry-After. 本地停止等待不代表任务已取消, 请继续查询原任务, 避免重复提交.

结果与计费

result.data 只包含成功图片, 每项的 image_index 是从 0 开始的原始张序, 不是成功数组的下标. size, output_format, revised_prompt 描述该图片的实际结果.
部分成功时, result.failed_images 包含失败项的 image_index 和 error; 全部成功时省略该字段. completed 不保证请求的所有图片都成功.
result.request_id 是结果追踪标识, 不能替代任务 id 查询.
usage.generated_images 表示实际成功图片数量, 在有效的已结算用量中返回. 费用按实际文本输入, 图片输入和图片输出 tokens 分别计算, 不按请求 n 乘固定单价.
当前售价通过控制台报价查询, 最终金额以 billing.status=settled 时的 billing 为准. 不要把预扣金额或缺失用量当成最终消费.

完整响应和结算字段见图片任务状态, 三项费率单位见接入说明.