how-tos

Poradnik MAI Image 2.7 API: pierwszy obraz w cURL i Pythonie

Poyo.ai Team
8 min read
Share:

Poradnik MAI Image 2.7 API z cURL i Pythonem

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:

PoleZasada
modelmai-image-2.7 lub mai-image-2.7-flash
promptWymagane, od 1 do 32,000 znaków, nie same białe znaki
image_urlsTablica 1 do 5 publicznych adresów HTTP lub HTTPS, JPEG, PNG lub WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 lub WIDTHxHEIGHT
Własny rozmiarOba boki podzielne przez 16, każdy bok co najmniej 768, szerokość x wysokość najwyżej 4,194,304
resolution1K (ok. 1 MP) lub 2K (ok. 4 MP, 16:9 to 2720x1536); dotyczy rozmiarów podanych jako proporcje
backgroundopaque lub transparent; przezroczystość wymaga output_format png lub webp
output_formatpng, jpeg lub webp
Nieznane polaOdrzucane; 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ć

codeZnaczenieCo zrobić
400Nieprawidłowe parametryPopraw ciało żądania; nie ponawiaj bez zmian
401Brak lub nieprawidłowy klucz APISprawdź nagłówek Authorization: Bearer
402Niewystarczająca liczba kredytówDoładuj konto i wyślij ponownie
429Przekroczony limit żądańOdczekaj i spróbuj później
500, 502, 503Błąd serwera, dostawcy lub dostępnościPonó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.

ModelWejście tekstoweWejście obrazoweWyjście obrazowe (za 1M tokenów)
mai-image-2.71,000 kredytów ($5.00)1,600 kredytów ($8.00)6,800 kredytów ($34.00)
mai-image-2.7-flash350 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.

Share: