
Bu MAI Image 2.7 API rehberi sizi cURL ve Python'da bir API anahtarından bitmiş bir görsele götürür, ardından PoYo şemasının kabul ettiği her giriş modunu ele alır: metinden görsele, tek görsel düzenleme, çok görselli kompozisyon, özel boyutlar, 2K çıktı ve şeffaf PNG veya WebP. Aşağıdaki tüm gövdeler mai-image-2.7 model kimliğini kullanır; daha ucuz katman için mai-image-2.7-flash yazın, çünkü iki MAI Image 2.7 şeması da kimlik dışında aynıdır.
Alan kuralları PoYo API referansından alınmıştır. Modelin ne olduğunu ve diğerleriyle nasıl kıyaslandığını öğrenmek için MAI Image 2.7 API genel bakışıyla başlayın.
Adım 1: cURL ile bir MAI Image 2.7 API isteği gönderin
PoYo panelinde bir anahtar oluşturun ve POYO_API_KEY olarak dışa aktarın. Anahtarı tarayıcı kodunda değil, sunucunuzda tutun.
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"
}
}'
Başarılı bir gönderim code: 200 ve task_id, status: "not_started" ve created_time içeren bir data nesnesi döndürür. Bu bir görsel değil, kuyruğa alınmış bir görevdir. Gövdedeki code alanını her seferinde kontrol edin: bazı doğrulama hataları HTTP 200 ve code: 400 ile döner.
Adım 2: görev durumunu sorgulayın
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Durum not_started, running ve ardından finished veya failed olarak ilerler. Tamamlanan bir görev görseli data.files içinde file_url ve file_type: "image" içeren bir nesne olarak listeler ve ücreti credits_amount alanında bildirir. Başarısız bir görev nedenini error_message alanında açıklar.
Adım 3: süre sınırlı bir Python sorgulama döngüsü
Bu döngü hem HTTP durumunu hem de gövdedeki code alanını kontrol eder, failed durumunda durur ve yeniden göndermeden 10 dakika sonra vazgeçer. 19 Kasım 2026 lansman testimizde 2K 16:9 bir görsel MAI Image 2.7'de yaklaşık 66 saniye, Flash'ta yaklaşık 42 saniye sürdü; bu yüzden 5 saniyelik sorgulama aralığı fazlasıyla yeterli.
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)
Zaman aşımı "aynı görev kimliğini daha sonra tekrar kontrol et" demektir. Yeniden göndermek, ücretlendirilen ikinci bir görev başlatır.
MAI Image 2.7 API'nin tüm giriş modları
Tüm alanlar input içine yazılır. Model kimliği ve isteğe bağlı callback_url en üst düzeydedir.
Metinden görsele
Yalnızca prompt zorunludur. size olmadan çıktı 1:1 olur; resolution olmadan 1K olur (kare için 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"
}
}
Tek görsel düzenleme
image_urls içinde tek bir URL gönderin. Tek görsel için bile bir dizi olmalıdır.
{
"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 olmadan düzenleme, ilk referans görselin en-boy oranını yaklaşık 1 megapikselde korur. Farklı bir oran veya özel boyut istediğinizde size ekleyin.
2 ila 5 görseli birleştirme
Birden fazla URL tek bir yeni görselde birleştirilir. Hangi görselin neyi sağladığını modelin bilmesi için promptta görsellere rollerine göre atıfta bulunun.
{
"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"
}
}
Referans görseller yaklaşık 1 megapiksele kadar kullanılır; bu yüzden bundan çok daha büyük dosyalar göndermeye gerek yoktur.
Özel boyut
Bir WIDTHxHEIGHT dizesi verildiği gibi birebir kullanılır.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Şeffaf arka plan ve çıktı formatı
{
"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 opak görsellerde de çalışır: daha küçük fotoğraf dosyaları için "jpeg" gönderin. Şeffaf arka plan rehberi alfa kontrollerini ve ölçtüğümüz çıkartma çalıştırmasını ele alıyor.
Alan doğrulama kuralları
Hatalı isteklerin hızlıca başarısız olması için göndermeden önce kendi tarafınızda doğrulayın:
| Alan | Kural |
|---|---|
model | mai-image-2.7 veya mai-image-2.7-flash |
prompt | Zorunlu, 1 ila 32,000 karakter, yalnızca boşluk olamaz |
image_urls | 1 ila 5 herkese açık HTTP veya HTTPS URL'sinden oluşan dizi; JPEG, PNG veya WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 veya WIDTHxHEIGHT |
| Özel boyut | İki kenar da 16'ya bölünebilmeli, her kenar en az 768, genişlik x yükseklik en fazla 4,194,304 |
resolution | 1K (yaklaşık 1 MP) veya 2K (yaklaşık 4 MP, 16:9 için 2720x1536); en-boy oranıyla verilen boyutlara uygulanır |
background | opaque veya transparent; şeffaflık için output_format png veya webp olmalı |
output_format | png, jpeg veya webp |
| Bilinmeyen alanlar | Reddedilir; şema ek özelliklere izin vermez, bu yüzden MAI Image 2.6 isteklerinden enable_web_search gibi alanları kaldırın |
Örnekler: 2048x2048 ve 3072x1344 geçer; 3000x1400 başarısız olur (16'nın katı değil); 640x1600 başarısız olur (bir kenar 768'in altında); 2400x2400 başarısız olur (5,760,000 piksel). "background": "transparent" ile "output_format": "jpeg" başarısız olur, çünkü JPEG'in alfa kanalı yoktur.
Ele alınması gereken hatalar
code | Anlamı | Ne yapmalı |
|---|---|---|
| 400 | Geçersiz parametreler | Gövdeyi düzeltin; değiştirmeden tekrar denemeyin |
| 401 | Eksik veya geçersiz API anahtarı | Authorization: Bearer başlığını kontrol edin |
| 402 | Yetersiz kredi | Bakiye yükleyin, sonra yeniden gönderin |
| 429 | İstek limiti aşıldı | Bekleyin ve daha sonra tekrar deneyin |
| 500, 502, 503 | Sunucu, upstream veya erişilebilirlik hatası | Backoff ile tekrar deneyin; önce bir görev kimliğinin zaten dönüp dönmediğini kontrol edin |
Gönderimden sonra failed durumuna geçen bir görev, nedenini error_message içinde taşır; örneğin içerik politikası nedeniyle ret. Tam liste için Error Codes sayfasına bakın. Uygulamanız kullanıcı yüklemelerini image_urls olarak kabul ediyorsa, bunları önceden taramak başarısız görevlerden tasarruf sağlar; görsel moderasyon rehberi bunun bir yolunu gösteriyor.
Sorgulama yerine callback kullanın
Gövdenin en üst düzeyine "callback_url": "https://your-app.example.com/poyo-webhook" ekleyin. Görev bittiğinde veya başarısız olduğunda PoYo, görev verilerini (durum yanıtındaki data ile aynı yapıda) X-Webhook-Signature başlığında HMAC-SHA256 ile imzalanmış olarak bu URL'ye POST eder. İmza kuralı webhook dokümantasyonunda yer alıyor. Hiç gelmeyen callback'ler için yavaş bir sorgulamayı yedek olarak tutun.
İlk faturanız nasıl hesaplanır?
MAI Image 2.7 API token'ları ücretlendirir: metin girişi, görsel girişi (image_urls için) ve görsel çıktısı. PoYo'da çıktı, yaklaşık 1,024 piksel başına bir token'dır.
| Model | Metin girişi | Görsel girişi | Görsel çıktısı (1M token başına) |
|---|---|---|---|
mai-image-2.7 | 1,000 kredi ($5.00) | 1,600 kredi ($8.00) | 6,800 kredi ($34.00) |
mai-image-2.7-flash | 350 kredi ($1.75) | 500 kredi ($2.50) | 2,000 kredi ($10.00) |
Lansman günü testimiz (PoYo üretim API'si, 19 Kasım 2026) bunun pratikte ne anlama geldiğini gösteriyor. Aynı 2K 16:9 kafe isteği iki katmanda da 2720x1536 döndürdü ve güncel oranlarla mai-image-2.7'de 27.802 kredi (yaklaşık $0.139), mai-image-2.7-flash'ta 8.1803 kredi (yaklaşık $0.041) tutuyor. Türetilmiş tahmin: 2720x1536, 4,177,920 piksel yani yaklaşık 4,080 çıktı token'ıdır; bu da 27.744 ve 8.16 krediyi oluşturur; her birindeki küçük kalan, yaklaşık 58 prompt token'ına karşılık gelir. Fiyat yazısında her boyut için maliyet tabloları var.
Sık sorulan sorular
MAI Image 2.7 API, OpenAI SDK ile uyumlu mu?
Hayır. Asenkron bir görev API'sidir: /api/generate/submit adresine gönderin, ardından /api/generate/status/{task_id} adresini sorgulayın veya bir callback alın. Düz requests, fetch veya cURL yeterlidir.
MAI Image 2.7 API ile bir görseli nasıl düzenlerim?
Herkese açık tek bir görsel URL'si içeren image_urls ekleyin ve değişikliği prompt içinde anlatın. 2 ila 5 URL ile görseller birleştirilir.
MAI Image 2.7 API'de kesin bir piksel boyutu ayarlayabilir miyim?
Evet, size alanını iki kenarı da 16'ya bölünebilen, her biri en az 768 ve toplamda en fazla 4,194,304 piksel olan bir WIDTHxHEIGHT olarak gönderin.
Tek bir MAI Image 2.7 API isteği kaç görsel döndürür? Bir. Varyasyonlar için birden fazla görevi paralel gönderin.
MAI Image 2.7 API JPEG döndürür mü?
Evet, background değeri opaque olduğu sürece "output_format": "jpeg" ile. Varsayılan PNG'dir, WebP de kullanılabilir.