
Questa guida alla MAI Image 2.7 API ti porta da una chiave API a un'immagine finita con cURL e Python, poi copre ogni modalità di input accettata dallo schema PoYo: text-to-image, modifica di una singola immagine, composizione di più immagini, dimensioni personalizzate, output 2K e PNG o WebP trasparente. Tutti i body qui sotto usano l'ID modello mai-image-2.7; sostituiscilo con mai-image-2.7-flash per il livello più economico, perché i due schemi di MAI Image 2.7 sono identici a parte l'ID.
Le regole dei campi provengono dal riferimento dell'API PoYo. Per capire cos'è il modello e come si confronta, parti dalla panoramica della MAI Image 2.7 API.
Passo 1: inviare una richiesta alla MAI Image 2.7 API con cURL
Crea una chiave nella dashboard di PoYo ed esportala come POYO_API_KEY. Tienila sul tuo server, non nel codice del browser.
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"
}
}'
Un invio riuscito restituisce code: 200 e un oggetto data con task_id, status: "not_started" e created_time. È un task in coda, non ancora un'immagine. Controlla code nel body ogni volta: alcuni errori di validazione tornano con HTTP 200 e code: 400.
Passo 2: polling dello stato del task
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Lo stato passa da not_started a running e poi a finished o failed. Un task completato elenca l'immagine in data.files come oggetto con file_url e file_type: "image" e riporta l'addebito in credits_amount. Un task fallito indica il motivo in error_message.
Passo 3: un ciclo di polling in Python con limite
Questo ciclo controlla sia lo stato HTTP sia il code del body, si ferma su failed e rinuncia dopo 10 minuti senza reinviare. Nel nostro test di lancio del 19 novembre 2026, un'immagine 2K in 16:9 ha richiesto circa 66 secondi su MAI Image 2.7 e circa 42 secondi su Flash, quindi un intervallo di polling di 5 secondi è più che sufficiente.
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)
Un timeout significa «ricontrolla lo stesso ID del task più tardi». Reinviare avvierebbe un secondo task a pagamento.
Tutte le modalità di input della MAI Image 2.7 API
Tutti i campi vanno dentro input. L'ID modello e una callback_url facoltativa stanno al livello principale.
Text-to-image
Solo prompt è obbligatorio. Senza size l'output è 1:1; senza resolution è 1K (1024x1024 per un quadrato).
{
"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"
}
}
Modificare un'immagine
Passa un URL in image_urls. Deve essere un array anche per una sola immagine.
{
"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"]
}
}
Senza size, la modifica mantiene il rapporto d'aspetto della prima immagine di riferimento a circa 1 megapixel. Aggiungi size se vuoi un rapporto diverso o una dimensione personalizzata.
Combinare da 2 a 5 immagini
Più URL vengono combinati in una nuova immagine. Richiamali nel prompt in base al loro ruolo, così il modello sa cosa fornisce ciascuna immagine.
{
"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"
}
}
Le immagini di riferimento vengono usate fino a circa 1 megapixel, quindi non serve inviare file molto più grandi.
Dimensione personalizzata
Una stringa WIDTHxHEIGHT viene usata esattamente come indicata.
{
"model": "mai-image-2.7",
"input": {
"prompt": "A wide panoramic banner of a mountain range at sunrise",
"size": "3072x1344"
}
}
Sfondo trasparente e formato di output
{
"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 funziona anche sulle immagini opache: invia "jpeg" per file fotografici più leggeri. La guida allo sfondo trasparente tratta i controlli del canale alfa e il nostro test misurato con uno sticker.
Regole di validazione dei campi
Valida dal tuo lato prima dell'invio, così le richieste errate falliscono subito:
| Campo | Regola |
|---|---|
model | mai-image-2.7 o mai-image-2.7-flash |
prompt | Obbligatorio, da 1 a 32,000 caratteri, non solo spazi |
image_urls | Array da 1 a 5 URL HTTP o HTTPS pubblici, JPEG, PNG o WebP |
size | 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 o WIDTHxHEIGHT |
| Dimensione personalizzata | Entrambi i lati divisibili per 16, ogni lato almeno 768, larghezza x altezza al massimo 4,194,304 |
resolution | 1K (circa 1 MP) o 2K (circa 4 MP, 16:9 è 2720x1536); si applica alle dimensioni basate sul rapporto d'aspetto |
background | opaque o transparent; transparent richiede output_format png o webp |
output_format | png, jpeg o webp |
| Campi sconosciuti | Rifiutati; lo schema non ammette proprietà aggiuntive, quindi rimuovi campi come enable_web_search dalle richieste MAI Image 2.6 |
Esempi: 2048x2048 e 3072x1344 sono validi; 3000x1400 fallisce (non multipli di 16); 640x1600 fallisce (un lato sotto 768); 2400x2400 fallisce (5,760,000 pixel). "background": "transparent" con "output_format": "jpeg" fallisce perché il JPEG non ha canale alfa.
Errori da gestire
code | Significato | Cosa fare |
|---|---|---|
| 400 | Parametri non validi | Correggi il body; non ritentare senza modifiche |
| 401 | Chiave API mancante o non valida | Controlla l'header Authorization: Bearer |
| 402 | Crediti insufficienti | Ricarica, poi reinvia |
| 429 | Limite di frequenza superato | Attendi e ritenta più tardi |
| 500, 502, 503 | Errore del server, del provider a monte o di disponibilità | Ritenta con backoff; prima verifica se è già stato restituito un ID del task |
Un task che arriva a failed dopo l'invio riporta il motivo in error_message, per esempio un rifiuto per la policy sui contenuti. Consulta i codici di errore per l'elenco completo. Se la tua app accetta caricamenti degli utenti come image_urls, controllarli prima evita task falliti; la guida alla moderazione delle immagini mostra un modo per farlo.
Usare una callback invece del polling
Aggiungi "callback_url": "https://your-app.example.com/poyo-webhook" al livello principale del body. Quando il task termina o fallisce, PoYo invia via POST i dati del task (con la stessa struttura del data della risposta di stato) a quell'URL, firmati con HMAC-SHA256 nell'header X-Webhook-Signature. La documentazione dei webhook descrive la regola della firma. Mantieni un polling lento come riserva per le callback che non arrivano mai.
Come viene calcolato il tuo primo addebito
La MAI Image 2.7 API addebita token: input di testo, input di immagini (per image_urls) e output di immagini. Su PoYo l'output corrisponde a circa un token ogni 1,024 pixel.
| Modello | Input di testo | Input di immagini | Output di immagini (per 1M di token) |
|---|---|---|---|
mai-image-2.7 | 1,000 crediti ($5.00) | 1,600 crediti ($8.00) | 6,800 crediti ($34.00) |
mai-image-2.7-flash | 350 crediti ($1.75) | 500 crediti ($2.50) | 2,000 crediti ($10.00) |
Il nostro test del giorno del lancio (API di produzione di PoYo, 19 novembre 2026) mostra cosa significa in pratica. La stessa richiesta 2K 16:9 del caffè ha restituito 2720x1536 su entrambi i livelli e, alle tariffe attuali, corrisponde a 27.802 crediti (circa $0.139) su mai-image-2.7 e 8.1803 crediti (circa $0.041) su mai-image-2.7-flash. Stima derivata: 2720x1536 fanno 4,177,920 pixel, circa 4,080 token di output, che spiegano 27.744 e 8.16 crediti; il piccolo resto in ciascun caso corrisponde a circa 58 token di prompt. L'articolo sui prezzi contiene tabelle dei costi per ogni dimensione.
Domande frequenti
La MAI Image 2.7 API è compatibile con l'SDK di OpenAI?
No. È un'API a task asincroni: invia a /api/generate/submit, poi esegui il polling di /api/generate/status/{task_id} o ricevi una callback. Bastano requests, fetch o cURL.
Come modifico un'immagine con la MAI Image 2.7 API?
Aggiungi image_urls con l'URL pubblico di un'immagine e descrivi la modifica in prompt. Con 2-5 URL, le immagini vengono combinate.
Posso impostare una dimensione esatta in pixel nella MAI Image 2.7 API?
Sì, invia size come WIDTHxHEIGHT con entrambi i lati divisibili per 16, ciascuno di almeno 768, e al massimo 4,194,304 pixel in totale.
Quante immagini restituisce una richiesta alla MAI Image 2.7 API? Una. Invia più task in parallelo per ottenere varianti.
La MAI Image 2.7 API restituisce JPEG?
Sì, con "output_format": "jpeg", purché background sia opaque. Il PNG è il formato predefinito ed è disponibile anche il WebP.