
本篇 MAI Image 2.7 API 指南带你从 API key 开始,用 cURL 和 Python 拿到一张成品图,然后逐一介绍 PoYo schema 接受的所有输入模式:文生图、单图编辑、多图合成、自定义尺寸、2K 输出,以及透明 PNG 或 WebP。下面所有请求体都使用模型 ID mai-image-2.7;如需更便宜的档位,换成 mai-image-2.7-flash 即可,因为两个 MAI Image 2.7 schema 除 ID 外完全相同。
字段规则来自 PoYo API 参考。想了解模型本身及其对比,请先看 MAI Image 2.7 API 概览。
第 1 步:用 cURL 提交 MAI Image 2.7 API 请求
在 PoYo 控制台创建一个 key,并导出为 POYO_API_KEY。请把它放在服务器端,不要放在浏览器代码里。
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "mai-image-2.7",
"input": {
"prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
"size": "16:9",
"resolution": "2K"
}
}'
提交成功会返回 code: 200,以及包含 task_id、status: "not_started" 和 created_time 的 data 对象。这是一个排队中的任务,不是图像。每次都要检查响应体中的 code:部分校验错误会以 HTTP 200 和 code: 400 返回。
第 2 步:轮询任务状态
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
状态依次经过 not_started、running,最后变为 finished 或 failed。已完成的任务会在 data.files 中以带有 file_url 和 file_type: "image" 的对象列出图像,并在 credits_amount 中报告扣费。失败的任务会在 error_message 中说明原因。
第 3 步:带超时上限的 Python 轮询循环
这个循环同时检查 HTTP 状态和响应体 code,遇到 failed 就停止,并在 10 分钟后放弃且不重新提交。在 2026 年 11 月 19 日的发布测试中,一张 2K 16:9 图像在 MAI Image 2.7 上约需 66 秒,在 Flash 上约需 42 秒,所以 5 秒的轮询间隔足够了。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def generate(input_body, model="mai-image-2.7", max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images[0], task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
url, credits = generate({
"prompt": "A rainy-night cafe with a neon sign reading \"OPEN LATE\"",
"size": "16:9",
"resolution": "2K",
})
print(url, credits)
超时的意思是"稍后再查同一个任务 ID"。重新提交会启动第二个计费任务。
MAI Image 2.7 API 的全部输入模式
所有字段都放在 input 中。模型 ID 和可选的 callback_url 位于顶层。
文生图
只有 prompt 是必填的。不传 size 时输出为 1:1;不传 resolution 时为 1K(正方形即 1024x1024)。
{
"model": "mai-image-2.7",
"input": {
"prompt": "A university campus poster at dusk with the title \"Open Day 2026\", photorealistic, cinematic light",
"size": "16:9",
"resolution": "2K"
}
}
编辑一张图
在 image_urls 中传入一个 URL。即使只有一张图,也必须是数组。
{
"model": "mai-image-2.7",
"input": {
"prompt": "Change the bicycle to blue and add a small dog next to it",
"image_urls": ["https://example.com/bicycle.png"]
}
}
不传 size 时,编辑结果保持第一张参考图的宽高比,约 1 百万像素。想要不同比例或自定义尺寸时再加 size。
合成 2 到 5 张图
多个 URL 会被合成为一张新图。在提示词中按角色指代各张图,让模型知道哪张图提供什么。
{
"model": "mai-image-2.7",
"input": {
"prompt": "Place the sneaker from image 1 on the wooden boards from image 2, at the pier from image 3, golden hour",
"image_urls": [
"https://example.com/sneaker.png",
"https://example.com/boards.png",
"https://example.com/pier.png"
],
"size": "16:9"
}
}
参考图最多按约 1 百万像素使用,所以没必要发送比这大很多的文件。
自定义尺寸
WIDTHxHEIGHT 字符串会按原样使用。
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
透明背景与输出格式
{
"model": "mai-image-2.7",
"input": {
"prompt": "A flat vector logo of a red fox head, clean edges, no background",
"background": "transparent",
"output_format": "webp"
}
}
output_format 也适用于不透明图像:想让照片类文件更小,就发送 "jpeg"。alpha 检查和我们实测的贴纸运行见透明背景指南。
字段校验规则
提交前在你自己这边先做校验,让错误请求尽早失败:
| 字段 | 规则 |
|---|---|
model | mai-image-2.7 或 mai-image-2.7-flash |
prompt | 必填,1 到 32,000 个字符,不能只有空白 |
image_urls | 1 到 5 个公开 HTTP 或 HTTPS URL 组成的数组,JPEG、PNG 或 WebP |
size | 1:1、4:3、3:4、3:2、2:3、16:9、9:16 或 WIDTHxHEIGHT |
| 自定义尺寸 | 两边都能被 16 整除,每边至少 768,宽 x 高不超过 4,194,304 |
resolution | 1K(约 1 MP)或 2K(约 4 MP,16:9 为 2720x1536);作用于宽高比尺寸 |
background | opaque 或 transparent;transparent 要求 output_format 为 png 或 webp |
output_format | png、jpeg 或 webp |
| 未知字段 | 会被拒绝;schema 不允许额外属性,因此要删掉 MAI Image 2.6 请求中的 enable_web_search 等字段 |
示例:2048x2048 和 3072x1344 可以通过;3000x1400 失败(不是 16 的倍数);640x1600 失败(有一边小于 768);2400x2400 失败(5,760,000 像素)。"background": "transparent" 搭配 "output_format": "jpeg" 会失败,因为 JPEG 没有 alpha 通道。
值得处理的错误
code | 含义 | 处理方式 |
|---|---|---|
| 400 | 参数无效 | 修正请求体;不要原样重试 |
| 401 | API key 缺失或无效 | 检查 Authorization: Bearer 请求头 |
| 402 | 积分不足 | 充值后重新提交 |
| 429 | 超出速率限制 | 退避后稍后重试 |
| 500、502、503 | 服务器、上游或可用性错误 | 带退避重试;先确认是否已经返回过任务 ID |
提交后进入 failed 的任务会在 error_message 中写明原因,例如内容政策拒绝。完整列表见 Error Codes。如果你的应用把用户上传的图片作为 image_urls,事先筛查可以减少失败任务;图像审核指南介绍了一种做法。
用回调代替轮询
在请求体顶层加上 "callback_url": "https://your-app.example.com/poyo-webhook"。任务完成或失败时,PoYo 会把任务数据(与状态响应中 data 的结构相同)POST 到该 URL,并在 X-Webhook-Signature 请求头中附上 HMAC-SHA256 签名。签名规则见 webhook 文档。对于始终没有到达的回调,请保留一个低频轮询作为兜底。
第一笔账单如何计算
MAI Image 2.7 API 按 token 计费:文本输入、图像输入(用于 image_urls)和图像输出。在 PoYo 上,输出约每 1,024 像素 1 个 token。
| 模型 | 文本输入 | 图像输入 | 图像输出(每 100 万 token) |
|---|---|---|---|
mai-image-2.7 | 1,000 积分($5.00) | 1,600 积分($8.00) | 6,800 积分($34.00) |
mai-image-2.7-flash | 350 积分($1.75) | 500 积分($2.50) | 2,000 积分($10.00) |
我们发布当天的测试(PoYo 生产 API,2026 年 11 月 19 日)展示了实际效果。同一个 2K 16:9 咖啡馆请求在两个档位上都返回 2720x1536,按现行费率计算,在 mai-image-2.7 上为 27.802 积分(约 $0.139),在 mai-image-2.7-flash 上为 8.1803 积分(约 $0.041)。推算:2720x1536 为 4,177,920 像素,约 4,080 个输出 token,对应 27.744 和 8.16 积分;各自剩下的少量差额约等于 58 个提示词 token。每种尺寸的费用表见价格文章。
常见问题
MAI Image 2.7 API 兼容 OpenAI SDK 吗?
不兼容。它是一个异步任务 API:提交到 /api/generate/submit,然后轮询 /api/generate/status/{task_id} 或接收回调。直接用 requests、fetch 或 cURL 即可。
如何用 MAI Image 2.7 API 编辑图片?
添加包含一个公开图片 URL 的 image_urls,并在 prompt 中描述要做的修改。传 2 到 5 个 URL 时,这些图片会被合成。
MAI Image 2.7 API 能指定精确的像素尺寸吗?
可以,以 WIDTHxHEIGHT 形式发送 size,两边都能被 16 整除,每边至少 768,总像素不超过 4,194,304。
一个 MAI Image 2.7 API 请求返回几张图? 一张。如需多个变体,请并行提交多个任务。
MAI Image 2.7 API 能返回 JPEG 吗?
可以,使用 "output_format": "jpeg",前提是 background 为 opaque。默认是 PNG,也支持 WebP。