how-tos

Guida alla MAI Image 2.7 API: la prima immagine con cURL e Python

Poyo.ai Team
9 min read
Share:

Guida alla MAI Image 2.7 API con cURL e Python

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:

CampoRegola
modelmai-image-2.7 o mai-image-2.7-flash
promptObbligatorio, da 1 a 32,000 caratteri, non solo spazi
image_urlsArray da 1 a 5 URL HTTP o HTTPS pubblici, JPEG, PNG o WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 o WIDTHxHEIGHT
Dimensione personalizzataEntrambi i lati divisibili per 16, ogni lato almeno 768, larghezza x altezza al massimo 4,194,304
resolution1K (circa 1 MP) o 2K (circa 4 MP, 16:9 è 2720x1536); si applica alle dimensioni basate sul rapporto d'aspetto
backgroundopaque o transparent; transparent richiede output_format png o webp
output_formatpng, jpeg o webp
Campi sconosciutiRifiutati; 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

codeSignificatoCosa fare
400Parametri non validiCorreggi il body; non ritentare senza modifiche
401Chiave API mancante o non validaControlla l'header Authorization: Bearer
402Crediti insufficientiRicarica, poi reinvia
429Limite di frequenza superatoAttendi e ritenta più tardi
500, 502, 503Errore 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.

ModelloInput di testoInput di immaginiOutput di immagini (per 1M di token)
mai-image-2.71,000 crediti ($5.00)1,600 crediti ($8.00)6,800 crediti ($34.00)
mai-image-2.7-flash350 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.

Share: