
Ten poradnik MAI Image 2.7 API prowadzi od klucza API do gotowego obrazu w cURL i Pythonie, a potem omawia każdy tryb wejścia, który przyjmuje schemat PoYo: tekst-na-obraz, edycję jednego obrazu, kompozycję z wielu obrazów, własne rozmiary, wynik 2K oraz przezroczyste PNG lub WebP. Każde ciało żądania poniżej używa ID modelu mai-image-2.7; podmień je na mai-image-2.7-flash, aby użyć tańszego wariantu, bo oba schematy MAI Image 2.7 są identyczne poza ID.
Zasady pól pochodzą z dokumentacji API PoYo. Jeśli chcesz wiedzieć, czym jest model i jak wypada na tle innych, zacznij od przeglądu MAI Image 2.7 API.
Krok 1: wyślij żądanie do MAI Image 2.7 API przez cURL
Utwórz klucz w panelu PoYo i wyeksportuj go jako POYO_API_KEY. Trzymaj go na serwerze, a nie w kodzie przeglądarki.
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"
}
}'
Udane wysłanie zwraca code: 200 i obiekt data z task_id, status: "not_started" i created_time. To zadanie w kolejce, a nie obraz. Za każdym razem sprawdzaj code w ciele odpowiedzi: niektóre błędy walidacji wracają z HTTP 200 i code: 400.
Krok 2: odpytuj status zadania
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Status przechodzi przez not_started, running, a następnie finished lub failed. Zakończone zadanie podaje obraz w data.files jako obiekt z file_url i file_type: "image", a pobraną kwotę w credits_amount. Nieudane zadanie wyjaśnia przyczynę w error_message.
Krok 3: ograniczona czasowo pętla odpytywania w Pythonie
Ta pętla sprawdza zarówno status HTTP, jak i code w ciele, zatrzymuje się przy failed i poddaje się po 10 minutach bez ponownego wysyłania. W naszym teście z dnia premiery, 19 listopada 2026, obraz 2K 16:9 zajął ok. 66 sekund w MAI Image 2.7 i ok. 42 sekundy we Flash, więc odpytywanie co 5 sekund w zupełności wystarcza.
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)
Timeout oznacza „sprawdź to samo ID zadania później”. Ponowne wysłanie uruchomiłoby drugie, płatne zadanie.
Wszystkie tryby wejścia MAI Image 2.7 API
Wszystkie pola trafiają do input. ID modelu i opcjonalny callback_url są na najwyższym poziomie.
Tekst-na-obraz
Wymagany jest tylko prompt. Bez size wynik ma proporcje 1:1; bez resolution jest to 1K (1024x1024 dla kwadratu).
{
"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"
}
}
Edycja jednego obrazu
Przekaż jeden adres w image_urls. Musi to być tablica, nawet dla jednego obrazu.
{
"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"]
}
}
Bez size edycja zachowuje proporcje pierwszego obrazu referencyjnego w rozdzielczości ok. 1 megapiksela. Dodaj size, jeśli chcesz inne proporcje albo własny rozmiar.
Łączenie 2 do 5 obrazów
Kilka adresów jest łączonych w jeden nowy obraz. Odwołuj się do nich w prompcie według roli, aby model wiedział, który obraz co wnosi.
{
"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"
}
}
Obrazy referencyjne są używane w rozdzielczości do ok. 1 megapiksela, więc nie ma potrzeby wysyłać plików dużo większych.
Własny rozmiar
Ciąg WIDTHxHEIGHT jest używany dokładnie tak, jak go podano.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Przezroczyste tło i format wyjściowy
{
"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 działa też dla obrazów nieprzezroczystych: wyślij "jpeg", aby dostać mniejsze pliki fotograficzne. Poradnik o przezroczystym tle omawia sprawdzanie kanału alfa i nasz zmierzony przebieg z naklejką.
Zasady walidacji pól
Waliduj po swojej stronie przed wysłaniem, aby błędne żądania odpadały od razu:
| Pole | Zasada |
|---|---|
model | mai-image-2.7 lub mai-image-2.7-flash |
prompt | Wymagane, od 1 do 32,000 znaków, nie same białe znaki |
image_urls | Tablica 1 do 5 publicznych adresów HTTP lub HTTPS, JPEG, PNG lub WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 lub WIDTHxHEIGHT |
| Własny rozmiar | Oba boki podzielne przez 16, każdy bok co najmniej 768, szerokość x wysokość najwyżej 4,194,304 |
resolution | 1K (ok. 1 MP) lub 2K (ok. 4 MP, 16:9 to 2720x1536); dotyczy rozmiarów podanych jako proporcje |
background | opaque lub transparent; przezroczystość wymaga output_format png lub webp |
output_format | png, jpeg lub webp |
| Nieznane pola | Odrzucane; schemat nie dopuszcza dodatkowych właściwości, więc usuń pola takie jak enable_web_search z żądań MAI Image 2.6 |
Przykłady: 2048x2048 i 3072x1344 przechodzą; 3000x1400 nie przechodzi (nie są wielokrotnościami 16); 640x1600 nie przechodzi (bok poniżej 768); 2400x2400 nie przechodzi (5,760,000 pikseli). "background": "transparent" z "output_format": "jpeg" nie przechodzi, bo JPEG nie ma kanału alfa.
Błędy, które warto obsłużyć
code | Znaczenie | Co zrobić |
|---|---|---|
| 400 | Nieprawidłowe parametry | Popraw ciało żądania; nie ponawiaj bez zmian |
| 401 | Brak lub nieprawidłowy klucz API | Sprawdź nagłówek Authorization: Bearer |
| 402 | Niewystarczająca liczba kredytów | Doładuj konto i wyślij ponownie |
| 429 | Przekroczony limit żądań | Odczekaj i spróbuj później |
| 500, 502, 503 | Błąd serwera, dostawcy lub dostępności | Ponów z backoffem; najpierw sprawdź, czy ID zadania nie zostało już zwrócone |
Zadanie, które po wysłaniu kończy się statusem failed, ma przyczynę w error_message, na przykład odrzucenie przez politykę treści. Pełną listę znajdziesz w Error Codes. Jeśli Twoja aplikacja przyjmuje pliki od użytkowników jako image_urls, wcześniejsze ich sprawdzenie oszczędza nieudanych zadań; poradnik o moderacji obrazów pokazuje jeden ze sposobów.
Callback zamiast odpytywania
Dodaj "callback_url": "https://your-app.example.com/poyo-webhook" na najwyższym poziomie ciała żądania. Gdy zadanie się zakończy lub nie powiedzie, PoYo wyśle POST z danymi zadania (w tym samym kształcie co data w odpowiedzi statusu) na ten adres, podpisany HMAC-SHA256 w nagłówku X-Webhook-Signature. Dokumentacja webhooków podaje zasadę podpisu. Zachowaj wolne odpytywanie jako zabezpieczenie na wypadek callbacków, które nigdy nie dotrą.
Jak liczony jest pierwszy rachunek
MAI Image 2.7 API rozlicza tokeny: wejście tekstowe, wejście obrazowe (dla image_urls) i wyjście obrazowe. W PoYo wyjście to ok. jeden token na 1,024 piksele.
| Model | Wejście tekstowe | Wejście obrazowe | Wyjście obrazowe (za 1M tokenów) |
|---|---|---|---|
mai-image-2.7 | 1,000 kredytów ($5.00) | 1,600 kredytów ($8.00) | 6,800 kredytów ($34.00) |
mai-image-2.7-flash | 350 kredytów ($1.75) | 500 kredytów ($2.50) | 2,000 kredytów ($10.00) |
Nasz test z dnia premiery (produkcyjne API PoYo, 19 listopada 2026) pokazuje, co to oznacza w praktyce. To samo żądanie 2K 16:9 z kawiarnią zwróciło 2720x1536 w obu wariantach i według obecnych stawek wychodzi 27.802 kredytu (ok. $0.139) w mai-image-2.7 oraz 8.1803 kredytu (ok. $0.041) w mai-image-2.7-flash. Szacunek pochodny: 2720x1536 to 4,177,920 pikseli, ok. 4,080 tokenów wyjściowych, co daje 27.744 i 8.16 kredytu; niewielka reszta w obu przypadkach odpowiada ok. 58 tokenom promptu. Artykuł o cenach zawiera tabele kosztów dla wszystkich rozmiarów.
Najczęściej zadawane pytania
Czy MAI Image 2.7 API jest zgodne z OpenAI SDK?
Nie. To asynchroniczne API zadań: wysyłasz do /api/generate/submit, a potem odpytujesz /api/generate/status/{task_id} albo odbierasz callback. Wystarczą zwykłe requests, fetch lub cURL.
Jak edytować obraz w MAI Image 2.7 API?
Dodaj image_urls z jednym publicznym adresem obrazu i opisz zmianę w prompt. Przy 2 do 5 adresach obrazy są łączone.
Czy w MAI Image 2.7 API mogę ustawić dokładny rozmiar w pikselach?
Tak, wyślij size jako WIDTHxHEIGHT, z oboma bokami podzielnymi przez 16, każdym co najmniej 768 i łącznie najwyżej 4,194,304 pikseli.
Ile obrazów zwraca jedno żądanie do MAI Image 2.7 API? Jeden. Aby uzyskać warianty, wyślij kilka zadań równolegle.
Czy MAI Image 2.7 API zwraca JPEG?
Tak, z "output_format": "jpeg", o ile background ma wartość opaque. Domyślny jest PNG, dostępny jest też WebP.