
Panduan MAI Image 2.7 API ini membawa Anda dari API key sampai gambar jadi dengan cURL dan Python, lalu membahas setiap mode input yang diterima skema PoYo: text-to-image, edit satu gambar, komposisi multi-gambar, ukuran kustom, output 2K, serta PNG atau WebP transparan. Setiap body di bawah memakai ID model mai-image-2.7; ganti dengan mai-image-2.7-flash untuk tier yang lebih murah, karena kedua skema MAI Image 2.7 identik kecuali ID-nya.
Aturan field berasal dari referensi API PoYo. Untuk mengetahui apa model ini dan bagaimana perbandingannya, mulailah dari ikhtisar MAI Image 2.7 API.
Langkah 1: kirim request MAI Image 2.7 API dengan cURL
Buat key di dashboard PoYo dan export sebagai POYO_API_KEY. Simpan di server Anda, bukan di kode browser.
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"
}
}'
Submit yang berhasil mengembalikan code: 200 dan objek data berisi task_id, status: "not_started" dan created_time. Itu adalah task dalam antrean, bukan gambar. Selalu periksa code di body: beberapa error validasi dikembalikan dengan HTTP 200 dan code: 400.
Langkah 2: polling status task
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status bergerak dari not_started, running, lalu finished atau failed. Task yang selesai mencantumkan gambar di data.files sebagai objek dengan file_url dan file_type: "image", serta melaporkan tagihan di credits_amount. Task yang gagal menjelaskan penyebabnya di error_message.
Langkah 3: loop polling Python dengan batas waktu
Loop ini memeriksa status HTTP dan code di body, berhenti saat failed, dan menyerah setelah 10 menit tanpa mengirim ulang. Dalam uji peluncuran kami pada 19 November 2026, gambar 2K 16:9 butuh sekitar 66 detik di MAI Image 2.7 dan sekitar 42 detik di Flash, jadi interval polling 5 detik sudah cukup.
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 berarti "periksa lagi task ID yang sama nanti". Mengirim ulang akan memulai task kedua yang ikut ditagih.
Semua mode input MAI Image 2.7 API
Semua field berada di dalam input. ID model dan callback_url opsional berada di level atas.
Text-to-image
Hanya prompt yang wajib. Tanpa size, outputnya 1:1; tanpa resolution, outputnya 1K (1024x1024 untuk persegi).
{
"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"
}
}
Edit satu gambar
Kirim satu URL di image_urls. Nilainya harus berupa array meskipun hanya satu gambar.
{
"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"]
}
}
Tanpa size, hasil edit mempertahankan rasio aspek gambar referensi pertama pada sekitar 1 megapiksel. Tambahkan size jika Anda ingin rasio lain atau ukuran kustom.
Gabungkan 2 sampai 5 gambar
Beberapa URL digabungkan menjadi satu gambar baru. Sebut gambar-gambar itu di prompt berdasarkan perannya agar model tahu gambar mana menyumbang apa.
{
"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"
}
}
Gambar referensi dipakai hingga sekitar 1 megapiksel, jadi tidak perlu mengirim file yang jauh lebih besar dari itu.
Ukuran kustom
String WIDTHxHEIGHT dipakai persis seperti yang diberikan.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Latar belakang transparan dan format output
{
"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 juga berlaku untuk gambar opaque: kirim "jpeg" untuk file foto yang lebih kecil. Panduan latar belakang transparan membahas pengecekan alpha dan run stiker yang kami ukur.
Aturan validasi field
Validasi di sisi Anda sebelum submit agar request yang salah cepat gagal:
| Field | Aturan |
|---|---|
model | mai-image-2.7 atau mai-image-2.7-flash |
prompt | Wajib, 1 sampai 32,000 karakter, tidak boleh hanya spasi |
image_urls | Array berisi 1 sampai 5 URL HTTP atau HTTPS publik, JPEG, PNG atau WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 atau WIDTHxHEIGHT |
| Ukuran kustom | Kedua sisi habis dibagi 16, tiap sisi minimal 768, lebar x tinggi maksimal 4,194,304 |
resolution | 1K (sekitar 1 MP) atau 2K (sekitar 4 MP, 16:9 adalah 2720x1536); berlaku untuk ukuran rasio aspek |
background | opaque atau transparent; transparent membutuhkan output_format png atau webp |
output_format | png, jpeg atau webp |
| Field tak dikenal | Ditolak; skema tidak mengizinkan properti tambahan, jadi hapus field seperti enable_web_search dari request MAI Image 2.6 |
Contoh: 2048x2048 dan 3072x1344 lolos; 3000x1400 gagal (bukan kelipatan 16); 640x1600 gagal (ada sisi di bawah 768); 2400x2400 gagal (5,760,000 piksel). "background": "transparent" dengan "output_format": "jpeg" gagal karena JPEG tidak punya alpha channel.
Error yang perlu ditangani
code | Arti | Yang harus dilakukan |
|---|---|---|
| 400 | Parameter tidak valid | Perbaiki body; jangan ulangi tanpa perubahan |
| 401 | API key tidak ada atau tidak valid | Periksa header Authorization: Bearer |
| 402 | Kredit tidak cukup | Isi ulang, lalu kirim ulang |
| 429 | Batas rate terlampaui | Tunda, lalu coba lagi nanti |
| 500, 502, 503 | Error server, upstream atau ketersediaan | Coba lagi dengan backoff; periksa dulu apakah task ID sudah dikembalikan |
Task yang mencapai failed setelah submit membawa alasannya di error_message, misalnya penolakan kebijakan konten. Lihat Error Codes untuk daftar lengkapnya. Jika aplikasi Anda menerima unggahan pengguna sebagai image_urls, menyaringnya lebih dulu bisa mengurangi task gagal; panduan moderasi gambar menunjukkan salah satu caranya.
Gunakan callback alih-alih polling
Tambahkan "callback_url": "https://your-app.example.com/poyo-webhook" di level atas body. Saat task selesai atau gagal, PoYo melakukan POST data task (bentuknya sama dengan data di respons status) ke URL tersebut, ditandatangani dengan HMAC-SHA256 di header X-Webhook-Signature. Dokumentasi webhook menjelaskan aturan tanda tangannya. Tetap siapkan polling lambat sebagai cadangan untuk callback yang tidak pernah datang.
Cara tagihan pertama Anda dihitung
MAI Image 2.7 API menagih token: input teks, input gambar (untuk image_urls), dan output gambar. Di PoYo, output sekitar satu token per 1,024 piksel.
| Model | Input teks | Input gambar | Output gambar (per 1 juta token) |
|---|---|---|---|
mai-image-2.7 | 1,000 kredit ($5.00) | 1,600 kredit ($8.00) | 6,800 kredit ($34.00) |
mai-image-2.7-flash | 350 kredit ($1.75) | 500 kredit ($2.50) | 2,000 kredit ($10.00) |
Uji hari peluncuran kami (API produksi PoYo, 19 November 2026) menunjukkan artinya dalam praktik. Request kafe 2K 16:9 yang sama menghasilkan 2720x1536 di kedua tier dan, pada tarif saat ini, berbiaya 27.802 kredit (sekitar $0.139) di mai-image-2.7 dan 8.1803 kredit (sekitar $0.041) di mai-image-2.7-flash. Estimasi turunan: 2720x1536 adalah 4,177,920 piksel, sekitar 4,080 token output, yang setara 27.744 dan 8.16 kredit; sisa kecil pada masing-masing cocok dengan sekitar 58 token prompt. Artikel harga berisi tabel biaya untuk setiap ukuran.
Pertanyaan yang sering diajukan
Apakah MAI Image 2.7 API kompatibel dengan OpenAI SDK?
Tidak. Ini adalah API task asinkron: submit ke /api/generate/submit, lalu polling /api/generate/status/{task_id} atau terima callback. requests, fetch atau cURL biasa sudah cukup.
Bagaimana cara mengedit gambar dengan MAI Image 2.7 API?
Tambahkan image_urls berisi satu URL gambar publik dan jelaskan perubahannya di prompt. Dengan 2 sampai 5 URL, gambar-gambar itu digabungkan.
Bisakah saya menetapkan ukuran piksel persis di MAI Image 2.7 API?
Bisa, kirim size sebagai WIDTHxHEIGHT dengan kedua sisi habis dibagi 16, tiap sisi minimal 768, dan total maksimal 4,194,304 piksel.
Berapa gambar yang dikembalikan satu request MAI Image 2.7 API? Satu. Kirim beberapa task secara paralel untuk variasi.
Apakah MAI Image 2.7 API bisa mengembalikan JPEG?
Ya, dengan "output_format": "jpeg", selama background bernilai opaque. PNG adalah default dan WebP juga tersedia.