MiniMax Image
请求域名(国际站): tokenhub-intl.tencentcloudmaas.com(新加坡) 端点: POST /v1/wand/minimax-image/generation(文生图)、POST /v1/wand/minimax-image/edits(图片编辑) 认证: Tokenhub API Key / Bearer
MiniMax H3-Image 是 MiniMax 推出的图片生成模型系列,以 OpenAI Images 风格的协议提交请求,支持文本生图、多图参考编辑(1~16 张)、自定义尺寸 / 宽高比 / 面积档位、输出格式控制等能力。
同步调用
本接口为同步调用:一次请求直接返回生成结果,无需提交任务与轮询。服务端在内部完成异步推理并等到终态,再把原厂最终图像原样返回。因此单次请求耗时会明显长于普通接口,请为客户端留足请求超时时间。
前提条件
- 已注册腾讯云账号并开通 TokenHub 服务。
- 已获取 API Key,操作方法见 API Key 获取。
- 已在控制台【在线推理 - 视觉模型】中搜索
minimax-image-h3/minimax-image-h3-highspeed,开启对应模型的后付费。
下文所有示例中的 YOUR_API_KEY 均需替换为您自己的 API Key,鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。
基本信息
| 项目 | 取值 |
|---|---|
| 调用路径 | Tokenhub API |
| 请求域名(国际站) | tokenhub-intl.tencentcloudmaas.com(新加坡) |
| 鉴权 | Authorization: Bearer <API_KEY> |
| 结果返回 | 同步,结果包含在响应正文中 |
| 支持任务 | 文生图、图片编辑(单图 / 多图参考) |
| 参考图数量 | 编辑接口 1~16 张 |
单次出图数 n | 1~10 |
面积档位 area | 1K / 2K / 4K,默认 4K |
| 输出格式 | jpeg(默认)/ png / webp |
模型列表
| 模型名称 | model 参数值 | 支持能力 | 说明 |
|---|---|---|---|
| MiniMax H3-Image | minimax-image-h3 | 文生图 / 图片编辑(同步) | 标准质量,支持文本生图与多图参考编辑,综合效果均衡 |
| MiniMax H3-Image Highspeed | minimax-image-h3-highspeed | 文生图 / 图片编辑(同步) | 高速版本,生成速度更快,适合对延迟敏感的场景 |
两个模型共用同一组端点与参数,仅 model 取值不同。
文生图
1. 接口描述
以文本 prompt 描述目标图像,同步生成图片。支持指定输出尺寸、宽高比、输出格式等参数。
接口: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation
2. 输入参数
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
model | 是 | string | 模型 ID,取值 minimax-image-h3 或 minimax-image-h3-highspeed,不可为空 |
prompt | 否 | string | 图片的文本描述,最长 32000 个字符(按 Unicode 字符计,不含首尾空白)。为空或只含空白时返回 400。关闭 Prompt 增强(disable_prompt_enhanced=true)时,模型只读取约前 4096 个 token,超出部分不生效 |
n | 否 | integer | 生成图片数量,取值范围 [1, 10],默认 1 |
size | 否 | string | 生成尺寸,格式 ${宽}x${高}(如 2720x1536),宽、高为正整数。面积(宽 × 高)在 655,360 ~ 20,000,000 像素之间、宽高比在 1:3 ~ 3:1 之间(均含边界),不满足时返回 400,不会自动缩放或取整。传具体宽高时不能再传 aspect_ratio 或 area。也可传 auto,由模型根据 prompt 语义自动选择尺寸;不传时同样由模型自主决定 |
aspect_ratio | 否 | string | 输出宽高比,默认 auto。只能在 size 不传或为 auto 时传入。auto:由 Prompt 增强结合参考图与内容决定;X:Y:X、Y 为 1 ~ 300 的整数,宽高比在 1:3 ~ 3:1 之间(含边界),如 16:9、3:4、21:9、3:1 |
area | 否 | string | 输出面积档位:1K / 2K / 4K,默认 4K。只能在 size 不传或为 auto 时传入,size 为具体宽高时传入返回 400。三档目标面积分别为 1024×1024、2048×2048、4096×4096 像素,宽高由服务端按宽高比计算,如 2K 搭配 16:9 输出 2720×1536。每张的实际宽高见响应中的 data[].size |
output_format | 否 | string | 输出图片格式:jpeg / png / webp,默认 jpeg |
response_format | 否 | string | 图片返回形式:url(返回图片 URL,默认)或 b64_json(返回 Base64 编码) |
output_compression | 否 | integer | 输出压缩质量,范围 [0, 100],默认 95,值越大质量越高。仅对 jpeg / webp 有效 |
aigc_watermark | 否 | boolean | 是否叠加 AIGC 可见水印。false:不加(默认);true:加水印 |
disable_prompt_enhanced | 否 | boolean | 是否关闭 Prompt 增强(模型侧自动优化 prompt)。false:开启增强(默认);true:关闭增强,严格按原始 prompt 生图 |
三种尺寸控制方式只能二选一
- 精确尺寸:只传
size(如2720x1536),此时不能再传aspect_ratio/area。 - 比例 + 面积档位:
size不传(或传auto),用aspect_ratio+area组合,由服务端换算宽高。 - 全自动:三者都不传,由模型结合 prompt 自行决定。
3. 请求示例
文生图(基础)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-image-h3",
"prompt": "一只橘猫趴在窗台上晒太阳,背景是模糊的城市街景,暖色调,写实风格"
}'文生图(指定尺寸与格式)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-image-h3",
"prompt": "赛博朋克风格的城市夜景,霓虹灯倒映在雨后的街道上",
"size": "2720x1536",
"output_format": "jpeg",
"response_format": "url"
}'文生图(高速版,指定宽高比)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-image-h3-highspeed",
"prompt": "极简风格的产品海报,白色背景,中央放置一瓶香水",
"aspect_ratio": "9:16",
"output_format": "png"
}'图片编辑
1. 接口描述
以文本 prompt 描述编辑意图,并提供一张或多张参考图,同步生成编辑后的图片。支持换背景、换风格、局部修改、多图融合等场景。
接口: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/edits
2. 输入参数
在文生图参数基础上,额外支持以下参数:
| 参数名 | 必选 | 类型 | 描述 |
|---|---|---|---|
images | 否 | array[object] | 参考图列表,1~16 张。每个元素为 {"image_url": "..."} 或 {"url": "..."}(两种字段名均兼容)。支持 http(s) 公网 URL 或 data:image/...;base64,... 形态。多图场景下模型会综合所有参考图进行编辑 |
其余参数(model、prompt、n、size、aspect_ratio、area、output_format 等)与文生图接口完全一致,见上方参数表。
3. 请求示例
单图参考编辑
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-image/edits' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "minimax-image-h3",
"prompt": "保持人物不变,将背景替换为日落时分的海滩",
"images": [
{"image_url": "https://your-domain/portrait.jpg"}
],
"response_format": "url"
}'输出参数
文生图与图片编辑接口的响应结构相同,均为 MiniMax 原厂回包直接透传。
| 参数名 | 类型 | 描述 |
|---|---|---|
created | integer | Unix 秒级时间戳 |
data | array | 生成结果列表。每个元素包含 url(response_format=url 时)或 b64_json(response_format=b64_json 时),以及实际宽高 size、经 Prompt 增强后的 revised_prompt |
output_format | string | 实际输出的图片格式 |
tokenhub_usage | object | 用量,tokenhub_usage.total_tokens 为本次任务消耗的 token 数,用于计费 / 对账 |
request_id | string | 请求 ID,排查问题时请携带 |
响应示例
成功响应
{
"created": 1794385455,
"data": [
{
"revised_prompt": "The image is a realistic ......",
"size": "3552x4736",
"url": "https://xxx.png"
}
],
"output_format": "jpeg",
"request_id": "6e44b701-e024-426a-bb00-839553cb58c9",
"tokenhub_usage": {
"total_tokens": 44547
}
}错误码
请求失败时会返回错误码,常见错误码请参考 附录:统一错误码。参数校验类错误(如 size 越界、size 与 aspect_ratio / area 同时传入、prompt 为空)返回 HTTP 400。
FAQ
1. 生成结果的图片链接会过期吗?
会。生成结果为临时地址,请在生成成功后及时下载并保存到自有存储,不要长期引用该链接。如需避免下载环节,可设 response_format=b64_json 直接取 Base64。
2. 标准版和 Highspeed 怎么选?
两者参数与端点完全一致。追求综合效果选 minimax-image-h3;对延迟敏感(交互式预览、批量草稿)选 minimax-image-h3-highspeed。
3. 为什么传了 size 又传 aspect_ratio 会报 400?
size 为具体宽高时已经确定了输出尺寸,aspect_ratio 与 area 只在 size 不传或为 auto 时生效,二者同时传入视为冲突。
相关文档
| 文档 | 说明 |
|---|---|
| API Key 获取 | TokenHub API Key 的申请与管理 |
| MiniMax 视频生成(Tokenhub) | 同一厂商的视频生成接口 |