
Dieser Leitfaden zur MAI Image 2.7 API führt Sie vom API-Key bis zum fertigen Bild in cURL und Python und behandelt dann jeden Eingabemodus, den das PoYo-Schema akzeptiert: Text-to-Image, Bearbeitung eines einzelnen Bildes, Komposition aus mehreren Bildern, benutzerdefinierte Größen, 2K-Ausgabe und transparentes PNG oder WebP. Jeder Body unten verwendet die Modell-ID mai-image-2.7; für die günstigere Stufe setzen Sie mai-image-2.7-flash ein, denn beide MAI Image 2.7-Schemas sind bis auf die ID identisch.
Die Feldregeln stammen aus der PoYo API-Referenz. Was das Modell ist und wie es sich einordnet, erfahren Sie im Überblick zur MAI Image 2.7 API.
Schritt 1: einen MAI Image 2.7 API Request mit cURL senden
Erstellen Sie im PoYo-Dashboard einen Key und exportieren Sie ihn als POYO_API_KEY. Halten Sie ihn auf Ihrem Server, nicht im Browser-Code.
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"
}
}'
Ein erfolgreicher Submit liefert code: 200 und ein data-Objekt mit task_id, status: "not_started" und created_time. Das ist ein Task in der Warteschlange, noch kein Bild. Prüfen Sie jedes Mal code im Body: Manche Validierungsfehler kommen mit HTTP 200 und code: 400 zurück.
Schritt 2: den Task-Status pollen
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Der Status durchläuft not_started, running und dann finished oder failed. Ein abgeschlossener Task führt das Bild in data.files als Objekt mit file_url und file_type: "image" auf und meldet die Abrechnung in credits_amount. Ein fehlgeschlagener Task nennt den Grund in error_message.
Schritt 3: eine begrenzte Python-Polling-Schleife
Diese Schleife prüft sowohl den HTTP-Status als auch das code im Body, bricht bei failed ab und gibt nach 10 Minuten auf, ohne erneut zu submitten. In unserem Launch-Test vom 19. November 2026 dauerte ein 2K-Bild in 16:9 etwa 66 Sekunden bei MAI Image 2.7 und etwa 42 Sekunden bei Flash, ein Polling-Intervall von 5 Sekunden reicht also völlig.
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)
Ein Timeout bedeutet „denselben Task später erneut prüfen“. Ein erneuter Submit würde einen zweiten kostenpflichtigen Task starten.
Alle Eingabemodi der MAI Image 2.7 API
Alle Felder gehören in input. Die Modell-ID und eine optionale callback_url stehen auf oberster Ebene.
Text-to-Image
Nur prompt ist Pflicht. Ohne size ist die Ausgabe 1:1; ohne resolution ist sie 1K (1024x1024 bei einem Quadrat).
{
"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"
}
}
Ein Bild bearbeiten
Übergeben Sie eine URL in image_urls. Es muss auch bei einem einzelnen Bild ein Array sein.
{
"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"]
}
}
Ohne size behält die Bearbeitung das Seitenverhältnis des ersten Referenzbildes bei etwa 1 Megapixel bei. Fügen Sie size hinzu, wenn Sie ein anderes Verhältnis oder eine benutzerdefinierte Größe möchten.
2 bis 5 Bilder kombinieren
Mehrere URLs werden zu einem neuen Bild kombiniert. Bezeichnen Sie sie im Prompt nach ihrer Rolle, damit das Modell weiß, welches Bild was beisteuert.
{
"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"
}
}
Referenzbilder werden mit bis zu etwa 1 Megapixel verwendet, es lohnt sich also nicht, deutlich größere Dateien zu senden.
Benutzerdefinierte Größe
Ein WIDTHxHEIGHT-String wird exakt wie angegeben verwendet.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Transparenter Hintergrund und Ausgabeformat
{
"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 funktioniert auch bei deckenden Bildern: Senden Sie "jpeg" für kleinere fotografische Dateien. Der Leitfaden zu transparenten Hintergründen behandelt Alpha-Prüfungen und unseren gemessenen Sticker-Lauf.
Validierungsregeln für die Felder
Validieren Sie vor dem Submit auf Ihrer Seite, damit fehlerhafte Requests schnell scheitern:
| Feld | Regel |
|---|---|
model | mai-image-2.7 oder mai-image-2.7-flash |
prompt | Pflichtfeld, 1 bis 32,000 Zeichen, nicht nur Leerzeichen |
image_urls | Array mit 1 bis 5 öffentlichen HTTP- oder HTTPS-URLs, JPEG, PNG oder WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 oder WIDTHxHEIGHT |
| Benutzerdefinierte Größe | Beide Seiten durch 16 teilbar, jede Seite mindestens 768, Breite x Höhe höchstens 4,194,304 |
resolution | 1K (etwa 1 MP) oder 2K (etwa 4 MP, 16:9 ergibt 2720x1536); gilt für Größen per Seitenverhältnis |
background | opaque oder transparent; transparent erfordert output_format png oder webp |
output_format | png, jpeg oder webp |
| Unbekannte Felder | Abgelehnt; das Schema erlaubt keine zusätzlichen Properties, entfernen Sie also Felder wie enable_web_search aus MAI Image 2.6 Requests |
Beispiele: 2048x2048 und 3072x1344 sind gültig; 3000x1400 scheitert (keine Vielfachen von 16); 640x1600 scheitert (eine Seite unter 768); 2400x2400 scheitert (5,760,000 Pixel). "background": "transparent" mit "output_format": "jpeg" scheitert, weil JPEG keinen Alphakanal hat.
Fehler, die Sie behandeln sollten
code | Bedeutung | Was zu tun ist |
|---|---|---|
| 400 | Ungültige Parameter | Body korrigieren; nicht unverändert erneut versuchen |
| 401 | Fehlender oder ungültiger API-Key | Header Authorization: Bearer prüfen |
| 402 | Nicht genügend Credits | Aufladen, dann erneut submitten |
| 429 | Rate Limit überschritten | Pausieren und später erneut versuchen |
| 500, 502, 503 | Server-, Upstream- oder Verfügbarkeitsfehler | Mit Backoff erneut versuchen; zuerst prüfen, ob bereits eine Task-ID zurückkam |
Ein Task, der nach dem Submit failed erreicht, nennt den Grund in error_message, zum Beispiel eine Ablehnung durch die Content Policy. Die vollständige Liste finden Sie unter Fehlercodes. Wenn Ihre App Uploads von Nutzern als image_urls annimmt, spart eine vorherige Prüfung fehlgeschlagene Tasks; der Leitfaden zur Bildmoderation zeigt einen Weg dafür.
Callback statt Polling verwenden
Fügen Sie "callback_url": "https://your-app.example.com/poyo-webhook" auf oberster Ebene des Bodys hinzu. Wenn der Task abgeschlossen ist oder fehlschlägt, sendet PoYo die Task-Daten (in derselben Struktur wie data der Status-Antwort) per POST an diese URL, signiert mit HMAC-SHA256 im Header X-Webhook-Signature. Die Webhook-Doku beschreibt die Signaturregel. Behalten Sie ein langsames Polling als Fallback für Callbacks, die nie ankommen.
So wird Ihre erste Rechnung berechnet
Die MAI Image 2.7 API rechnet Tokens ab: Text-Input, Bild-Input (für image_urls) und Bild-Output. Bei PoYo entspricht der Output etwa einem Token pro 1,024 Pixel.
| Modell | Text-Input | Bild-Input | Bild-Output (pro 1M Tokens) |
|---|---|---|---|
mai-image-2.7 | 1,000 Credits ($5.00) | 1,600 Credits ($8.00) | 6,800 Credits ($34.00) |
mai-image-2.7-flash | 350 Credits ($1.75) | 500 Credits ($2.50) | 2,000 Credits ($10.00) |
Unser Test am Launch-Tag (PoYo-Produktions-API, 19. November 2026) zeigt, was das in der Praxis bedeutet. Derselbe 2K-Café-Request in 16:9 lieferte auf beiden Stufen 2720x1536 und kommt zu aktuellen Sätzen auf 27.802 Credits (etwa $0.139) bei mai-image-2.7 und 8.1803 Credits (etwa $0.041) bei mai-image-2.7-flash. Abgeleitete Schätzung: 2720x1536 sind 4,177,920 Pixel, also etwa 4,080 Output-Tokens, was 27.744 bzw. 8.16 Credits erklärt; der kleine Rest entspricht jeweils etwa 58 Prompt-Tokens. Der Preis-Beitrag enthält Kostentabellen für jede Größe.
Häufig gestellte Fragen
Ist die MAI Image 2.7 API mit dem OpenAI SDK kompatibel?
Nein. Es ist eine asynchrone Task-API: an /api/generate/submit senden, dann /api/generate/status/{task_id} pollen oder einen Callback empfangen. Einfaches requests, fetch oder cURL funktionieren.
Wie bearbeite ich ein Bild mit der MAI Image 2.7 API?
Fügen Sie image_urls mit einer öffentlichen Bild-URL hinzu und beschreiben Sie die Änderung in prompt. Mit 2 bis 5 URLs werden die Bilder kombiniert.
Kann ich in der MAI Image 2.7 API eine exakte Pixelgröße festlegen?
Ja, senden Sie size als WIDTHxHEIGHT, wobei beide Seiten durch 16 teilbar, jeweils mindestens 768 und insgesamt höchstens 4,194,304 Pixel sein müssen.
Wie viele Bilder liefert ein MAI Image 2.7 API Request? Eines. Für Varianten senden Sie mehrere Tasks parallel.
Liefert die MAI Image 2.7 API JPEG?
Ja, mit "output_format": "jpeg", solange background auf opaque steht. PNG ist der Standard, WebP ist ebenfalls verfügbar.