how-tos

MAI Image 2.7 API-guide: første bilde 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-guiden tar deg fra en API-nøkkel til et ferdig bilde i cURL og Python, og går deretter gjennom alle inputmodusene PoYo-skjemaet godtar: tekst-til-bilde, redigering av ett bilde, komposisjon av flere bilder, egendefinerte størrelser, 2K-output og transparent PNG eller WebP. Alle bodies nedenfor bruker modell-ID-en mai-image-2.7; bytt til mai-image-2.7-flash for det billigere nivået, siden begge MAI Image 2.7-skjemaene er identiske bortsett fra ID-en.

Feltreglene kommer fra PoYos API-referanse. Vil du vite hva modellen er og hvordan den står seg i sammenligning, start med oversikten over MAI Image 2.7 API.

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

Opprett en nøkkel i PoYo-dashbordet og eksporter den som POYO_API_KEY. Hold den på serveren, ikke i nettleserkode.

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 innsending returnerer code: 200 og et data-objekt med task_id, status: "not_started" og created_time. Det er en oppgave i kø, ikke et bilde. Sjekk code i body hver gang: noen valideringsfeil kommer tilbake med HTTP 200 og code: 400.

Steg 2: poll oppgavestatusen

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

Statusen går fra not_started via running til finished eller failed. En ferdig oppgave lister bildet i data.files som et objekt med file_url og file_type: "image", og oppgir beløpet i credits_amount. En mislykket oppgave forklarer seg selv i error_message.

Steg 3: en avgrenset polling-løkke i Python

Denne løkken sjekker både HTTP-status og code i body, stopper ved failed og gir opp etter 10 minutter uten å sende inn på nytt. I lanseringstesten vår den 19. november 2026 tok et 2K 16:9-bilde ca. 66 sekunder på MAI Image 2.7 og ca. 42 sekunder på Flash, så et poll-intervall på 5 sekunder er mer enn nok.

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 betyr "sjekk samme oppgave-ID igjen senere". En ny innsending ville starte en ny oppgave som også faktureres.

Alle inputmoduser i MAI Image 2.7 API

Alle felter ligger inne i input. Modell-ID-en og en valgfri callback_url ligger på toppnivå.

Tekst-til-bilde

Bare prompt er påkrevd. Uten size blir outputen 1:1; uten resolution er den 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 ett bilde

Send én URL i image_urls. Det må være en array, også for ett enkelt bilde.

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

Uten size beholder redigeringen sideforholdet til det første referansebildet i ca. 1 megapiksel. Legg til size når du vil ha et annet sideforhold eller en egendefinert størrelse.

Kombiner 2 til 5 bilder

Flere URL-er kombineres til ett nytt bilde. Vis til dem i prompten etter rolle, slik at modellen vet hvilket bilde som bidrar med hva.

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

Referansebilder brukes i opptil ca. 1 megapiksel, så det er ingen grunn til å sende filer som er mye større enn det.

Egendefinert størrelse

En WIDTHxHEIGHT-streng brukes nøyaktig som oppgitt.

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

Transparent bakgrunn 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 fungerer også på ugjennomsiktige bilder: send "jpeg" for mindre fotografiske filer. Guiden til transparent bakgrunn dekker alfasjekker og den målte sticker-kjøringen vår.

Valideringsregler for feltene

Valider på din side før innsending, så dårlige requests feiler raskt:

FeltRegel
modelmai-image-2.7 eller mai-image-2.7-flash
promptPåkrevd, 1 til 32,000 tegn, ikke bare 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
Egendefinert størrelseBegge sider delelige med 16, hver side minst 768, bredde x høyde maks 4,194,304
resolution1K (ca. 1 MP) eller 2K (ca. 4 MP, 16:9 er 2720x1536); gjelder størrelser oppgitt som sideforhold
backgroundopaque eller transparent; transparent krever output_format png eller webp
output_formatpng, jpeg eller webp
Ukjente felterAvvises; skjemaet tillater ikke ekstra properties, så fjern felter som enable_web_search fra MAI Image 2.6-requests

Eksempler: 2048x2048 og 3072x1344 går gjennom; 3000x1400 feiler (ikke multipler av 16); 640x1600 feiler (en side under 768); 2400x2400 feiler (5,760,000 piksler). "background": "transparent" med "output_format": "jpeg" feiler fordi JPEG ikke har noen alfakanal.

Feil som er verdt å håndtere

codeBetydningHva du gjør
400Ugyldige parametereRett body; ikke prøv igjen uendret
401Manglende eller ugyldig API-nøkkelSjekk headeren Authorization: Bearer
402Ikke nok creditsFyll på, og send inn på nytt
429Rate limit overskredetVent, og prøv igjen senere
500, 502, 503Server-, upstream- eller tilgjengelighetsfeilPrøv igjen med backoff; sjekk først om en oppgave-ID allerede ble returnert

En oppgave som ender i failed etter innsending, har årsaken i error_message, for eksempel en avvisning på grunn av innholdsregler. Se Error Codes for hele listen. Hvis appen din godtar brukeropplastinger som image_urls, sparer du mislykkede oppgaver ved å screene dem først; guiden til bildemoderering viser én måte.

Bruk callback i stedet for polling

Legg til "callback_url": "https://your-app.example.com/poyo-webhook" på toppnivå i body. Når oppgaven er ferdig eller feiler, sender PoYo en POST med oppgavedataene (samme form som data i statussvaret) til den URL-en, signert med HMAC-SHA256 i headeren X-Webhook-Signature. Webhook-dokumentasjonen beskriver signaturregelen. Behold en langsom polling som reserve for callbacks som aldri kommer frem.

Slik beregnes den første regningen din

MAI Image 2.7 API fakturerer tokens: tekstinput, bildeinput (for image_urls) og bildeoutput. På PoYo er output ca. én token per 1,024 piksler.

ModellTekstinputBildeinputBildeoutput (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)

Testen vår på lanseringsdagen (PoYos produksjons-API, 19. november 2026) viser hva det betyr i praksis. Den samme 2K 16:9 kafé-requesten returnerte 2720x1536 på begge nivåene og kommer med gjeldende 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. Avledet estimat: 2720x1536 er 4,177,920 piksler, ca. 4,080 output-tokens, som utgjør 27.744 og 8.16 credits; den lille resten på hver tilsvarer omtrent 58 prompt-tokens. Prisartikkelen har pristabeller for alle størrelser.

Ofte stilte spørsmål

Er MAI Image 2.7 API kompatibel med OpenAI SDK? Nei. Det er et asynkront oppgave-API: send inn til /api/generate/submit, og poll deretter /api/generate/status/{task_id} eller motta en callback. Vanlig requests, fetch eller cURL fungerer.

Hvordan redigerer jeg et bilde med MAI Image 2.7 API? Legg til image_urls med én offentlig bilde-URL og beskriv endringen i prompt. Med 2 til 5 URL-er kombineres bildene.

Kan jeg angi en nøyaktig pikselstørrelse i MAI Image 2.7 API? Ja, send size som WIDTHxHEIGHT med begge sider delelige med 16, hver minst 768, og maks 4,194,304 piksler totalt.

Hvor mange bilder returnerer én MAI Image 2.7 API-request? Ett. Send inn flere oppgaver parallelt for variasjoner.

Returnerer MAI Image 2.7 API JPEG? Ja, med "output_format": "jpeg", så lenge background er opaque. PNG er standard, og WebP er også tilgjengelig.

Share: