how-tos

MAI Image 2.7 API-guide: første billede med cURL og Python

Poyo.ai Team
8 min read
Share:

MAI Image 2.7 API-guide med cURL og Python

Denne MAI Image 2.7 API-guide fører dig fra en API-nøgle til et færdigt billede i cURL og Python og gennemgår derefter alle inputtilstande, som PoYo-skemaet accepterer: tekst-til-billede, redigering af ét billede, komposition af flere billeder, brugerdefinerede størrelser, 2K-output og transparent PNG eller WebP. Alle bodies nedenfor bruger model-ID'et mai-image-2.7; skift til mai-image-2.7-flash for det billigere niveau, da begge MAI Image 2.7-skemaer er identiske bortset fra ID'et.

Feltreglerne kommer fra PoYos API-reference. Vil du vide, hvad modellen er, og hvordan den klarer sig i sammenligning, så start med oversigten over MAI Image 2.7 API.

Trin 1: send en MAI Image 2.7 API-request med cURL

Opret en nøgle i PoYo-dashboardet, og eksportér den som POYO_API_KEY. Hold den på din server, ikke i browserkode.

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

En vellykket indsendelse returnerer code: 200 og et data-objekt med task_id, status: "not_started" og created_time. Det er en opgave i kø, ikke et billede. Tjek code i body hver gang: nogle valideringsfejl kommer tilbage med HTTP 200 og code: 400.

Trin 2: poll opgavens status

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

Status går fra not_started over running til finished eller failed. En færdig opgave lister billedet i data.files som et objekt med file_url og file_type: "image" og angiver beløbet i credits_amount. En fejlet opgave forklarer sig selv i error_message.

Trin 3: en afgrænset polling-løkke i Python

Denne løkke tjekker både HTTP-status og code i body, stopper ved failed og giver op efter 10 minutter uden at indsende igen. I vores lanceringstest den 19. november 2026 tog et 2K 16:9-billede ca. 66 sekunder på MAI Image 2.7 og ca. 42 sekunder på Flash, så et poll-interval på 5 sekunder er rigeligt.

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)

En timeout betyder "tjek samme opgave-ID igen senere". En ny indsendelse ville starte endnu en opgave, der bliver faktureret.

Alle inputtilstande i MAI Image 2.7 API

Alle felter ligger inde i input. Model-ID'et og en valgfri callback_url ligger på øverste niveau.

Tekst-til-billede

Kun prompt er påkrævet. Uden size bliver outputtet 1:1; uden resolution er det 1K (1024x1024 for et kvadrat).

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

Rediger ét billede

Send én URL i image_urls. Det skal være et array, også for et enkelt billede.

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

Uden size beholder redigeringen billedformatet fra det første referencebillede i ca. 1 megapixel. Tilføj size, når du vil have et andet format eller en brugerdefineret størrelse.

Kombiner 2 til 5 billeder

Flere URL'er kombineres til ét nyt billede. Henvis til dem i prompten efter rolle, så modellen ved, hvilket billede der leverer hvad.

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

Referencebilleder bruges i op til ca. 1 megapixel, så der er ingen grund til at sende filer, der er meget større end det.

Brugerdefineret størrelse

En WIDTHxHEIGHT-streng bruges præcis som angivet.

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

Transparent baggrund og outputformat

{
  "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 virker også på uigennemsigtige billeder: send "jpeg" for mindre fotografiske filer. Guiden til transparent baggrund dækker alfa-tjek og vores målte sticker-kørsel.

Valideringsregler for felterne

Valider på din egen side før indsendelse, så dårlige requests fejler hurtigt:

FeltRegel
modelmai-image-2.7 eller mai-image-2.7-flash
promptPåkrævet, 1 til 32,000 tegn, ikke kun whitespace
image_urlsArray med 1 til 5 offentlige HTTP- eller HTTPS-URL'er, JPEG, PNG eller WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 eller WIDTHxHEIGHT
Brugerdefineret størrelseBegge sider delelige med 16, hver side mindst 768, bredde x højde højst 4,194,304
resolution1K (ca. 1 MP) eller 2K (ca. 4 MP, 16:9 er 2720x1536); gælder for størrelser angivet som billedformat
backgroundopaque eller transparent; transparent kræver output_format png eller webp
output_formatpng, jpeg eller webp
Ukendte felterAfvises; skemaet tillader ikke ekstra properties, så fjern felter som enable_web_search fra MAI Image 2.6-requests

Eksempler: 2048x2048 og 3072x1344 går igennem; 3000x1400 fejler (ikke multipla af 16); 640x1600 fejler (en side under 768); 2400x2400 fejler (5,760,000 pixels). "background": "transparent" med "output_format": "jpeg" fejler, fordi JPEG ikke har nogen alfakanal.

Fejl, der er værd at håndtere

codeBetydningHvad du skal gøre
400Ugyldige parametreRet body; prøv ikke igen uændret
401Manglende eller ugyldig API-nøgleTjek headeren Authorization: Bearer
402Utilstrækkelige creditsFyld op, og indsend igen
429Rate limit overskredetVent, og prøv igen senere
500, 502, 503Server-, upstream- eller tilgængelighedsfejlPrøv igen med backoff; tjek først, om et opgave-ID allerede blev returneret

En opgave, der ender i failed efter indsendelsen, har årsagen i error_message, for eksempel en afvisning på grund af indholdspolitik. Se Error Codes for den fulde liste. Hvis din app accepterer brugeruploads som image_urls, sparer du fejlede opgaver ved at screene dem først; guiden til billedmoderation viser én måde.

Brug et callback i stedet for polling

Tilføj "callback_url": "https://your-app.example.com/poyo-webhook" på øverste niveau i body. Når opgaven er færdig eller fejler, sender PoYo en POST med opgavedataene (samme form som data i statussvaret) til den URL, signeret med HMAC-SHA256 i headeren X-Webhook-Signature. Webhook-dokumentationen beskriver signaturreglen. Behold en langsom polling som fallback for callbacks, der aldrig kommer frem.

Sådan beregnes din første regning

MAI Image 2.7 API afregner tokens: tekstinput, billedinput (for image_urls) og billedoutput. På PoYo er output ca. én token pr. 1,024 pixels.

ModelTekstinputBilledinputBilledoutput (pr. 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)

Vores test på lanceringsdagen (PoYos produktions-API, 19. november 2026) viser, hvad det betyder i praksis. Den samme 2K 16:9 café-request returnerede 2720x1536 på begge niveauer og lander med gældende satser på 27.802 credits (ca. $0.139) på mai-image-2.7 og 8.1803 credits (ca. $0.041) på mai-image-2.7-flash. Afledt estimat: 2720x1536 er 4,177,920 pixels, ca. 4,080 output-tokens, hvilket står for 27.744 og 8.16 credits; den lille rest på hver svarer til ca. 58 prompt-tokens. Prisartiklen har pristabeller for alle størrelser.

Ofte stillede spørgsmål

Er MAI Image 2.7 API kompatibel med OpenAI SDK? Nej. Det er et asynkront opgave-API: indsend til /api/generate/submit, og poll derefter /api/generate/status/{task_id} eller modtag et callback. Almindelig requests, fetch eller cURL fungerer.

Hvordan redigerer jeg et billede med MAI Image 2.7 API? Tilføj image_urls med én offentlig billed-URL, og beskriv ændringen i prompt. Med 2 til 5 URL'er kombineres billederne.

Kan jeg angive en præcis pixelstørrelse i MAI Image 2.7 API? Ja, send size som WIDTHxHEIGHT med begge sider delelige med 16, hver mindst 768 og højst 4,194,304 pixels i alt.

Hvor mange billeder returnerer én MAI Image 2.7 API-request? Ét. Indsend flere opgaver parallelt for at få variationer.

Returnerer MAI Image 2.7 API JPEG? Ja, med "output_format": "jpeg", så længe background er opaque. PNG er standard, og WebP er også tilgængeligt.

Share: