APIMODELSAPIMODELS
API 文档

apimodels.app

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.7mai-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 为准。失败的请求不扣费。

文生图

POST/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是stringmai-image-2.7 或 mai-image-2.7-flash
prompt是string必填,最多 32,000 个字符;改图时写清改什么、保留什么
image / images / image_urls否string / string[]改图用的输入图,1–5 张(公网网址或 data URI);不传就是文生图
aspect_ratio否string1:1(文生图缺省)、4:3、3:4、3:2、2:3、16:9、9:16
resolution否string1K(缺省,约 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否stringopaque(缺省)或 transparent;transparent 需配 png 或 webp
output_format否stringpng(缺省)/ 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 没有透明通道,不能和透明背景一起用。