MAI Image 2.7 API reference (2.7 / Flash)
微软 MAI Image 2.7 图像模型 API(微软公开预览版),两档:mai-image-2.7 和 mai-image-2.7-flash。同一个接口做文生图和改图:只传提示词,或再带 1–5 张图;每次 1 张,七种比例配 1K / 2K,或精确尺寸(最大 2048×2048);支持透明背景(PNG / WebP)。两档请求写法完全一样,只差 token 单价。
认证
所有请求在 Header 携带 API Key:
Authorization: Bearer YOUR_API_KEY价格
| 项目 | mai-image-2.7 | mai-image-2.7-flash |
|---|---|---|
| 文本输入,每百万 token | $7.15 | $2.50 |
| 图像输入,每百万 token | $11.44 | $3.58 |
| 图像输出,每百万 token | $48.62 | $14.30 |
| 参考:1K 文生图一张 | 约 $0.05 | 约 $0.015 |
| 参考:2K 一张 | 约 $0.20 | 约 $0.059 |
| 参考:带一张图的 1K 改图 | 约 $0.06 | 约 $0.018 |
按每个请求实际用掉的 token 扣费,所以没有固定单价:一张 1K(约 100 万像素)图大约 1,024 个输出 token,2K 约 4,096 个;每张输入图按图像输入计,提示词按文本输入计。上面的「参考」是典型花费,实际以查询结果里的 credits 为准。失败的请求不扣费。
文生图
/v1/images/generations缺省异步:创建返回 taskId,轮询 GET ?task_id= 到 completed,从 resultUrls 取图,或用 callback_url 接 webhook。不传尺寸时是 1:1 的 1K。我们 2026 年 11 月 18 日只实测过一单:Flash 1K 16:9 文生图,拿到 1360×768 的 PNG,全程约 16 秒,这一单扣 $0.0148 —— 只是一个例子,不代表典型耗时;2.7、2K 和改图还没有实测数据。
# Text-to-image — create returns a taskId, then poll for the result.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "A minimalist product photo of a matte white ceramic teapot on a light oak table beside a sunlit window, soft shadows, realistic photography",
"aspect_ratio": "16:9",
"resolution": "1K"
}'
# → { "code": 200, "data": { "taskId": "...", "state": "pending", "model": "mai-image-2.7" } }
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# → { "code": 200, "data": { "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."] } }改图 · 多图合成
带 image(单张)或 images(最多 5 张)就是改图,模型名不变。提示词里写清改什么、保留什么;多张图时按图里的内容指代(「第二张图里的茶壶」)。输入图可以是公网网址或 data URI。改图不给尺寸时,模型会按原图选一个接近的尺寸;给了 aspect_ratio 或 size 就按你给的出。微软主打的是精细修改:换某个物体的颜色、材质或位置,其余部分保持不变,而且多轮修改时画面保持一致。
# Edit one picture — say what to change and what to keep.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "Make the teapot glossy cobalt blue. Keep the table, the window light, the shadows and the framing exactly the same.",
"image": "https://example.com/teapot.jpg"
}'
# Combine up to 5 pictures — refer to them by what they show.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "Place the teapot from the second image on the kitchen counter in the first image. Keep the kitchen and its lighting unchanged.",
"images": ["https://example.com/kitchen.jpg", "https://example.com/teapot.png"],
"aspect_ratio": "4:3"
}'2K 与精确尺寸
resolution 选 2K 时每边翻倍(1:1 为 2048×2048,约 4 倍 token,2.7 一张约 $0.20)。也可以传「宽x高」形式的 size:每边至少 768 像素,总像素不超过 4,194,304(2048×2048),会向下取到 16 的倍数;没有 4K。传精确 size 且不带 callback_url 时,请求会等到出图,同一个响应直接返回 { created, data: [{ url }] },OpenAI SDK 的 images.generate 拿到的就是这种响应。
# 2K preset: each side doubled (16:9 → about 2720x1536).
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "A wide hero banner of a quiet mountain lake at dawn, mist over the water, a small wooden dock",
"aspect_ratio": "16:9",
"resolution": "2K"
}'
# Exact size + no callback_url: the image comes back in this same response (OpenAI shape).
# Each side >= 768 px, at most 4,194,304 pixels (2048x2048), rounded down to a multiple of 16.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7-flash",
"prompt": "A square app icon of a paper plane on a soft gradient, flat illustration",
"size": "2048x2048",
"response_format": "url"
}'
# → { "created": ..., "data": [{ "url": "https://r2.apimodels.app/..." }] }透明背景
background 传 transparent,output_format 选 png 或 webp,文生图和改图都能用,适合商品图、Logo、图标和贴纸,省掉抠图这一步。JPEG 没有透明通道,不能和透明背景一起用。
# Transparent background: background "transparent" + png or webp (JPEG has no alpha channel).
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"prompt": "A die-cut sticker of a smiling cartoon avocado with a thick white outline, no background",
"background": "transparent",
"output_format": "png",
"aspect_ratio": "1:1",
"resolution": "1K"
}'
# The same on an existing photo: cut the product out.
curl -X POST https://api.apimodels.app/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7-flash",
"prompt": "Cut out the ceramic mug on a transparent background. Keep the mug, its handle and its glaze exactly as they are.",
"image": "https://example.com/mug.jpg",
"background": "transparent",
"output_format": "webp"
}'参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 是 | string | mai-image-2.7 或 mai-image-2.7-flash |
| prompt | 是 | string | 必填,最多 32,000 个字符;改图时写清改什么、保留什么 |
| image / images / image_urls | 否 | string / string[] | 改图用的输入图,1–5 张(公网网址或 data URI);不传就是文生图 |
| aspect_ratio | 否 | string | 1:1(文生图缺省)、4:3、3:4、3:2、2:3、16:9、9:16 |
| resolution | 否 | string | 1K(缺省,约 100 万像素)或 2K(每边翻倍);只对 aspect_ratio 生效 |
| size | 否 | string | 精确尺寸,如 1536x1024;每边 ≥768、总像素 ≤4,194,304,向下取到 16 的倍数。给了 size 就不看 aspect_ratio,resolution 也被忽略;不带 callback_url 时同一响应直接返回图 |
| image_size | 否 | string / object | 另一种写法:预设名 square_hd、landscape_4_3、portrait_4_3、landscape_3_2、portrait_3_2、landscape_16_9、portrait_16_9(配 resolution),或 {"width": W, "height": H}(同上面的尺寸规则)。优先级 image_size > size > aspect_ratio |
| background | 否 | string | opaque(缺省)或 transparent;transparent 需配 png 或 webp |
| output_format | 否 | string | png(缺省)/ jpeg / webp;jpg 按 jpeg 处理 |
| quality | 否 | string | 可以传,但不起作用(这个模型没有画质档) |
| response_format | 否 | string | 一次调用模式下:url 只返回链接 |
| callback_url | 否 | string | 任务完成后的 webhook 回调 URL |
限制
- 每次请求出 1 张;n(num_images)不是 1 会返回 400,要多张请分开发请求。
- 输入图最多 5 张,超过返回 400;遮罩(mask)、seed 和反向提示词(negative_prompt)都不支持,传了返回 400,不会被悄悄丢掉。
- 最大 2048×2048,没有 4K;比例只有上面七种,其他比例返回 400;每边不能小于 768 像素。精确尺寸时 resolution 被忽略;quality 不起作用。
- 输出只有 PNG、JPEG、WebP,没有 GIF 和 SVG;透明背景要 PNG 或 WebP。
- 微软以公开预览版提供这两个模型,表现可能会变。
- 文字能画清楚,但仍可能编出不存在的规格、日期和零件名,发布前请核对。
不保证每次都成功
提示词或图片可能被内容审核拒绝,上游偶尔会临时出错。失败的请求不扣费,返回里带失败原因:审核类改提示词或换图再试,临时错误直接重试。结果文件保留 30 天后自动删除,请及时下载或转存。
试一试:MAI Image 2.7 / MAI Image 2.7 Flash(试用区可选 1K / 2K 和比例,出 PNG;透明背景、JPEG / WebP 和精确尺寸请用 API)。要 4K、GIF 或 SVG,见 GPT Image 2.6。
常见问题
MAI Image 2.7 怎么改图?
向 /v1/images/generations 发请求,model 填 mai-image-2.7(或 mai-image-2.7-flash),提示词写清改什么、保留什么,原图放在 image(多张放 images,最多 5 张)。输入图按图像输入 token 计费。
MAI Image 2.7 多少钱?
按实际 token 计费。mai-image-2.7:每百万 token 文本输入 $7.15、图像输入 $11.44、图像输出 $48.62,1K 一张约 $0.05。mai-image-2.7-flash:$2.50 / $3.58 / $14.30,1K 一张约 $0.015。失败不扣费。
怎么出透明背景?
background 传 "transparent",output_format 选 png 或 webp。JPEG 没有透明通道,不能和透明背景一起用。