how-tos

MAI Image 2.7 API Rehberi: cURL ve Python ile İlk Görsel

Poyo.ai Team
8 min read
Share:

cURL ve Python ile MAI Image 2.7 API rehberi

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:

AlanKural
modelmai-image-2.7 veya mai-image-2.7-flash
promptZorunlu, 1 ila 32,000 karakter, yalnızca boşluk olamaz
image_urls1 ila 5 herkese açık HTTP veya HTTPS URL'sinden oluşan dizi; JPEG, PNG veya WebP
size1: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
resolution1K (yaklaşık 1 MP) veya 2K (yaklaşık 4 MP, 16:9 için 2720x1536); en-boy oranıyla verilen boyutlara uygulanır
backgroundopaque veya transparent; şeffaflık için output_format png veya webp olmalı
output_formatpng, jpeg veya webp
Bilinmeyen alanlarReddedilir; ş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

codeAnlamıNe yapmalı
400Geçersiz parametrelerGövdeyi düzeltin; değiştirmeden tekrar denemeyin
401Eksik veya geçersiz API anahtarıAuthorization: Bearer başlığını kontrol edin
402Yetersiz krediBakiye yükleyin, sonra yeniden gönderin
429İstek limiti aşıldıBekleyin ve daha sonra tekrar deneyin
500, 502, 503Sunucu, 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.

ModelMetin girişiGörsel girişiGörsel çıktısı (1M token başına)
mai-image-2.71,000 kredi ($5.00)1,600 kredi ($8.00)6,800 kredi ($34.00)
mai-image-2.7-flash350 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.

Share: