
Hướng dẫn MAI Image 2.7 API này đưa bạn từ API key đến một ảnh hoàn chỉnh bằng cURL và Python, sau đó trình bày mọi chế độ đầu vào mà schema của PoYo chấp nhận: text-to-image, chỉnh sửa một ảnh, kết hợp nhiều ảnh, kích thước tùy chỉnh, đầu ra 2K và PNG hoặc WebP trong suốt. Mọi body bên dưới đều dùng model ID mai-image-2.7; đổi sang mai-image-2.7-flash để dùng tier rẻ hơn, vì hai schema MAI Image 2.7 giống hệt nhau ngoài ID.
Quy tắc các trường lấy từ tài liệu tham khảo API của PoYo. Để biết model là gì và so sánh ra sao, hãy bắt đầu với tổng quan MAI Image 2.7 API.
Bước 1: gửi request MAI Image 2.7 API bằng cURL
Tạo key trong dashboard PoYo và export thành POYO_API_KEY. Giữ key trên server của bạn, không đặt trong mã chạy trên trình duyệt.
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"
}
}'
Gửi thành công sẽ trả về code: 200 và một đối tượng data chứa task_id, status: "not_started" và created_time. Đó là một tác vụ trong hàng đợi, chưa phải ảnh. Luôn kiểm tra code trong body: một số lỗi xác thực trả về với HTTP 200 và code: 400.
Bước 2: polling trạng thái tác vụ
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Trạng thái đi qua not_started, running, rồi finished hoặc failed. Tác vụ hoàn tất liệt kê ảnh trong data.files dưới dạng đối tượng có file_url và file_type: "image", đồng thời báo số phí trong credits_amount. Tác vụ thất bại giải thích lý do trong error_message.
Bước 3: vòng lặp polling Python có giới hạn
Vòng lặp này kiểm tra cả mã trạng thái HTTP lẫn code trong body, dừng khi gặp failed, và bỏ cuộc sau 10 phút mà không gửi lại. Trong bài thử ra mắt ngày 19 tháng 11 năm 2026, ảnh 2K 16:9 mất khoảng 66 giây trên MAI Image 2.7 và khoảng 42 giây trên Flash, nên khoảng polling 5 giây là đủ.
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)
Timeout có nghĩa là "kiểm tra lại cùng task ID đó sau". Gửi lại sẽ tạo một tác vụ thứ hai bị tính phí.
Mọi chế độ đầu vào của MAI Image 2.7 API
Tất cả các trường nằm trong input. Model ID và callback_url tùy chọn nằm ở cấp trên cùng.
Text-to-image
Chỉ prompt là bắt buộc. Không có size thì đầu ra là 1:1; không có resolution thì là 1K (1024x1024 với ảnh vuông).
{
"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"
}
}
Chỉnh sửa một ảnh
Truyền một URL trong image_urls. Trường này phải là mảng kể cả khi chỉ có một ảnh.
{
"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"]
}
}
Không có size, ảnh chỉnh sửa giữ tỷ lệ khung hình của ảnh tham chiếu đầu tiên ở khoảng 1 megapixel. Thêm size khi bạn muốn tỷ lệ khác hoặc kích thước tùy chỉnh.
Kết hợp 2 đến 5 ảnh
Nhiều URL được kết hợp thành một ảnh mới. Hãy nhắc tới các ảnh trong prompt theo vai trò để model biết ảnh nào cung cấp gì.
{
"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"
}
}
Ảnh tham chiếu được dùng ở mức tối đa khoảng 1 megapixel, nên không cần gửi file lớn hơn thế nhiều.
Kích thước tùy chỉnh
Chuỗi WIDTHxHEIGHT được dùng đúng như đã cho.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Nền trong suốt và định dạng đầu ra
{
"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 cũng áp dụng cho ảnh không trong suốt: gửi "jpeg" để có file ảnh chụp nhỏ hơn. Hướng dẫn nền trong suốt trình bày cách kiểm tra alpha và lần chạy sticker mà chúng tôi đã đo.
Quy tắc xác thực các trường
Hãy xác thực ở phía bạn trước khi gửi để request sai bị loại sớm:
| Trường | Quy tắc |
|---|---|
model | mai-image-2.7 hoặc mai-image-2.7-flash |
prompt | Bắt buộc, 1 đến 32,000 ký tự, không được chỉ có khoảng trắng |
image_urls | Mảng gồm 1 đến 5 URL HTTP hoặc HTTPS công khai, JPEG, PNG hoặc WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 hoặc WIDTHxHEIGHT |
| Kích thước tùy chỉnh | Cả hai cạnh chia hết cho 16, mỗi cạnh ít nhất 768, rộng x cao tối đa 4,194,304 |
resolution | 1K (khoảng 1 MP) hoặc 2K (khoảng 4 MP, 16:9 là 2720x1536); áp dụng cho kích thước theo tỷ lệ khung hình |
background | opaque hoặc transparent; transparent yêu cầu output_format là png hoặc webp |
output_format | png, jpeg hoặc webp |
| Trường không xác định | Bị từ chối; schema không cho phép thuộc tính thừa, nên hãy bỏ các trường như enable_web_search từ request MAI Image 2.6 |
Ví dụ: 2048x2048 và 3072x1344 hợp lệ; 3000x1400 không hợp lệ (không phải bội số của 16); 640x1600 không hợp lệ (có cạnh dưới 768); 2400x2400 không hợp lệ (5,760,000 pixel). "background": "transparent" cùng "output_format": "jpeg" không hợp lệ vì JPEG không có kênh alpha.
Các lỗi cần xử lý
code | Ý nghĩa | Cách xử lý |
|---|---|---|
| 400 | Tham số không hợp lệ | Sửa body; không thử lại nguyên trạng |
| 401 | Thiếu hoặc sai API key | Kiểm tra header Authorization: Bearer |
| 402 | Không đủ credit | Nạp thêm rồi gửi lại |
| 429 | Vượt giới hạn tốc độ | Chờ rồi thử lại sau |
| 500, 502, 503 | Lỗi server, upstream hoặc khả dụng | Thử lại với backoff; trước tiên kiểm tra xem task ID đã được trả về chưa |
Tác vụ chuyển sang failed sau khi gửi sẽ ghi lý do trong error_message, ví dụ bị từ chối do chính sách nội dung. Xem Error Codes để có danh sách đầy đủ. Nếu ứng dụng của bạn nhận ảnh người dùng tải lên làm image_urls, sàng lọc trước sẽ giảm số tác vụ thất bại; hướng dẫn kiểm duyệt ảnh trình bày một cách làm.
Dùng callback thay cho polling
Thêm "callback_url": "https://your-app.example.com/poyo-webhook" ở cấp trên cùng của body. Khi tác vụ hoàn tất hoặc thất bại, PoYo sẽ POST dữ liệu tác vụ (cùng cấu trúc với data của phản hồi trạng thái) tới URL đó, được ký bằng HMAC-SHA256 trong header X-Webhook-Signature. Tài liệu webhook nêu quy tắc chữ ký. Hãy giữ một cơ chế polling chậm làm dự phòng cho những callback không bao giờ tới.
Hóa đơn đầu tiên được tính thế nào
MAI Image 2.7 API tính phí theo token: đầu vào văn bản, đầu vào hình ảnh (cho image_urls) và đầu ra hình ảnh. Trên PoYo, đầu ra khoảng một token cho mỗi 1,024 pixel.
| Model | Đầu vào văn bản | Đầu vào hình ảnh | Đầu ra hình ảnh (mỗi 1 triệu token) |
|---|---|---|---|
mai-image-2.7 | 1,000 credit ($5.00) | 1,600 credit ($8.00) | 6,800 credit ($34.00) |
mai-image-2.7-flash | 350 credit ($1.75) | 500 credit ($2.50) | 2,000 credit ($10.00) |
Bài thử ngày ra mắt (API production của PoYo, 19 tháng 11 năm 2026) cho thấy điều đó trong thực tế. Cùng một request quán cà phê 2K 16:9 trả về 2720x1536 trên cả hai tier và, theo giá hiện hành, tốn 27.802 credit (khoảng $0.139) trên mai-image-2.7 và 8.1803 credit (khoảng $0.041) trên mai-image-2.7-flash. Ước tính suy ra: 2720x1536 là 4,177,920 pixel, khoảng 4,080 token đầu ra, tương ứng 27.744 và 8.16 credit; phần dư nhỏ ở mỗi bên khớp với khoảng 58 token prompt. Bài viết về giá có bảng chi phí cho mọi kích thước.
Câu hỏi thường gặp
MAI Image 2.7 API có tương thích với OpenAI SDK không?
Không. Đây là API tác vụ bất đồng bộ: gửi tới /api/generate/submit, rồi polling /api/generate/status/{task_id} hoặc nhận callback. Dùng requests, fetch hoặc cURL thông thường là được.
Làm sao chỉnh sửa ảnh bằng MAI Image 2.7 API?
Thêm image_urls chứa một URL ảnh công khai và mô tả thay đổi trong prompt. Với 2 đến 5 URL, các ảnh sẽ được kết hợp.
Tôi có thể đặt kích thước pixel chính xác trong MAI Image 2.7 API không?
Có, gửi size dưới dạng WIDTHxHEIGHT với cả hai cạnh chia hết cho 16, mỗi cạnh ít nhất 768, và tổng tối đa 4,194,304 pixel.
Một request MAI Image 2.7 API trả về bao nhiêu ảnh? Một. Hãy gửi nhiều tác vụ song song để có các biến thể.
MAI Image 2.7 API có trả về JPEG không?
Có, với "output_format": "jpeg", miễn là background là opaque. PNG là mặc định và WebP cũng có sẵn.