how-tos

MAI Image 2.7 API-gids: je eerste afbeelding met cURL en Python

Poyo.ai Team
8 min read
Share:

MAI Image 2.7 API-gids met cURL en Python

Deze MAI Image 2.7 API-gids brengt je van een API-key naar een afgewerkte afbeelding in cURL en Python, en behandelt daarna elke invoermodus die het PoYo-schema accepteert: text-to-image, bewerkingen van één afbeelding, composities van meerdere afbeeldingen, eigen formaten, 2K-output en transparante PNG of WebP. Elke body hieronder gebruikt het model-ID mai-image-2.7; vervang het door mai-image-2.7-flash voor de goedkopere tier, want beide MAI Image 2.7-schema's zijn identiek op het ID na.

De veldregels komen uit de PoYo API-referentie. Wil je weten wat het model is en hoe het zich verhoudt tot andere, begin dan met het overzicht van de MAI Image 2.7 API.

Stap 1: een MAI Image 2.7 API-request indienen met cURL

Maak een key aan in het PoYo-dashboard en exporteer die als POYO_API_KEY. Houd hem op je server, niet in browsercode.

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"
    }
  }'

Een geslaagde submit geeft code: 200 terug en een data-object met task_id, status: "not_started" en created_time. Dat is een taak in de wachtrij, nog geen afbeelding. Controleer code in de body elke keer: sommige validatiefouten komen terug met HTTP 200 en code: 400.

Stap 2: de taakstatus pollen

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

De status gaat van not_started naar running en daarna naar finished of failed. Een afgeronde taak vermeldt de afbeelding in data.files als object met file_url en file_type: "image", en geeft het afgerekende bedrag in credits_amount. Een mislukte taak legt de oorzaak uit in error_message.

Stap 3: een begrensde Python-pollinglus

Deze lus controleert zowel de HTTP-status als de code in de body, stopt bij failed en geeft het na 10 minuten op zonder opnieuw in te dienen. In onze launchtest van 19 november 2026 duurde een 2K-afbeelding in 16:9 ongeveer 66 seconden op MAI Image 2.7 en ongeveer 42 seconden op Flash, dus een pollinterval van 5 seconden is ruim voldoende.

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)

Een timeout betekent "controleer hetzelfde taak-ID later opnieuw". Opnieuw indienen zou een tweede betaalde taak starten.

Alle invoermodi van de MAI Image 2.7 API

Alle velden horen binnen input. Het model-ID en een optionele callback_url staan op het hoogste niveau.

Text-to-image

Alleen prompt is verplicht. Zonder size is de output 1:1; zonder resolution is die 1K (1024x1024 voor een vierkant).

{
  "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"
  }
}

Eén afbeelding bewerken

Geef één URL mee in image_urls. Het moet een array zijn, ook voor één afbeelding.

{
  "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"]
  }
}

Zonder size behoudt de bewerking de beeldverhouding van de eerste referentieafbeelding op ongeveer 1 megapixel. Voeg size toe als je een andere verhouding of een eigen formaat wilt.

2 tot 5 afbeeldingen combineren

Meerdere URL's worden gecombineerd tot één nieuwe afbeelding. Verwijs er in de prompt naar op basis van hun rol, zodat het model weet welke afbeelding wat levert.

{
  "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"
  }
}

Referentieafbeeldingen worden gebruikt tot ongeveer 1 megapixel, dus het heeft geen zin om veel grotere bestanden te sturen.

Eigen formaat

Een WIDTHxHEIGHT-string wordt exact gebruikt zoals opgegeven.

{
  "model": "mai-image-2.7",
  "input": {
    "prompt": "A wide panoramic banner of a mountain range at sunrise",
    "size": "3072x1344"
  }
}

Transparante achtergrond en outputformaat

{
  "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 werkt ook voor niet-transparante afbeeldingen: stuur "jpeg" voor kleinere fotografische bestanden. De gids voor transparante achtergronden behandelt alfacontroles en onze gemeten sticker-run.

Validatieregels per veld

Valideer aan je eigen kant voordat je indient, zodat foute requests snel falen:

VeldRegel
modelmai-image-2.7 of mai-image-2.7-flash
promptVerplicht, 1 tot 32,000 tekens, niet alleen witruimte
image_urlsArray van 1 tot 5 publieke HTTP- of HTTPS-URL's, JPEG, PNG of WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 of WIDTHxHEIGHT
Eigen formaatBeide zijden deelbaar door 16, elke zijde minimaal 768, breedte x hoogte maximaal 4,194,304
resolution1K (ongeveer 1 MP) of 2K (ongeveer 4 MP, 16:9 is 2720x1536); geldt voor formaten op basis van beeldverhouding
backgroundopaque of transparent; transparent vereist output_format png of webp
output_formatpng, jpeg of webp
Onbekende veldenGeweigerd; het schema staat geen extra eigenschappen toe, dus verwijder velden zoals enable_web_search uit MAI Image 2.6-requests

Voorbeelden: 2048x2048 en 3072x1344 zijn geldig; 3000x1400 faalt (geen veelvouden van 16); 640x1600 faalt (een zijde onder 768); 2400x2400 faalt (5,760,000 pixels). "background": "transparent" met "output_format": "jpeg" faalt omdat JPEG geen alfakanaal heeft.

Fouten die je moet afhandelen

codeBetekenisWat te doen
400Ongeldige parametersCorrigeer de body; probeer niet ongewijzigd opnieuw
401Ontbrekende of ongeldige API-keyControleer de header Authorization: Bearer
402Onvoldoende creditsVul aan en dien daarna opnieuw in
429Rate limit overschredenWacht en probeer het later opnieuw
500, 502, 503Server-, upstream- of beschikbaarheidsfoutProbeer opnieuw met backoff; controleer eerst of er al een taak-ID is teruggegeven

Een taak die na het indienen failed bereikt, vermeldt de reden in error_message, bijvoorbeeld een afwijzing door het contentbeleid. Zie Error Codes voor de volledige lijst. Accepteert je app uploads van gebruikers als image_urls, dan voorkom je mislukte taken door ze eerst te screenen; de gids voor beeldmoderatie laat één manier zien.

Een callback gebruiken in plaats van polling

Voeg "callback_url": "https://your-app.example.com/poyo-webhook" toe op het hoogste niveau van de body. Wanneer de taak klaar is of mislukt, stuurt PoYo de taakdata (dezelfde vorm als data in de statusresponse) met een POST naar die URL, ondertekend met HMAC-SHA256 in de header X-Webhook-Signature. De webhookdocs geven de handtekeningregel. Houd een trage polling-fallback aan voor callbacks die nooit aankomen.

Hoe je eerste rekening wordt berekend

De MAI Image 2.7 API rekent tokens af: tekstinput, afbeeldingsinput (voor image_urls) en afbeeldingsoutput. Op PoYo is de output ongeveer één token per 1,024 pixels.

ModelTekstinputAfbeeldingsinputAfbeeldingsoutput (per 1M tokens)
mai-image-2.71,000 credits ($5.00)1,600 credits ($8.00)6,800 credits ($34.00)
mai-image-2.7-flash350 credits ($1.75)500 credits ($2.50)2,000 credits ($10.00)

Onze launchtest (PoYo-productie-API, 19 november 2026) laat zien wat dat in de praktijk betekent. Hetzelfde 2K-café-request in 16:9 gaf op beide tiers 2720x1536 terug en komt tegen de huidige tarieven uit op 27.802 credits (ongeveer $0.139) op mai-image-2.7 en 8.1803 credits (ongeveer $0.041) op mai-image-2.7-flash. Afgeleide schatting: 2720x1536 is 4,177,920 pixels, ongeveer 4,080 outputtokens, goed voor 27.744 en 8.16 credits; het kleine restant past bij ongeveer 58 prompttokens. De prijzenpost heeft kostentabellen voor elk formaat.

Veelgestelde vragen

Is de MAI Image 2.7 API compatibel met de OpenAI SDK? Nee. Het is een asynchrone taak-API: dien in bij /api/generate/submit en poll daarna /api/generate/status/{task_id} of ontvang een callback. Gewone requests, fetch of cURL werken.

Hoe bewerk ik een afbeelding met de MAI Image 2.7 API? Voeg image_urls toe met één publieke afbeeldings-URL en beschrijf de wijziging in prompt. Met 2 tot 5 URL's worden de afbeeldingen gecombineerd.

Kan ik in de MAI Image 2.7 API een exact pixelformaat instellen? Ja, stuur size als WIDTHxHEIGHT met beide zijden deelbaar door 16, elke zijde minimaal 768 en in totaal maximaal 4,194,304 pixels.

Hoeveel afbeeldingen geeft één MAI Image 2.7 API-request terug? Eén. Dien meerdere taken parallel in voor variaties.

Geeft de MAI Image 2.7 API JPEG terug? Ja, met "output_format": "jpeg", zolang background op opaque staat. PNG is de standaard en WebP is ook beschikbaar.

Share: