how-tos

Guide de la MAI Image 2.7 API : première image en cURL et Python

Poyo.ai Team
9 min read
Share:

Guide de la MAI Image 2.7 API avec cURL et Python

Ce guide de la MAI Image 2.7 API vous mène d’une clé API à une image terminée en cURL et en Python, puis couvre chaque mode d’entrée accepté par le schéma PoYo : text-to-image, édition d’une seule image, composition multi-images, tailles personnalisées, sortie 2K et PNG ou WebP transparent. Tous les corps ci-dessous utilisent l’ID de modèle mai-image-2.7 ; remplacez-le par mai-image-2.7-flash pour le niveau moins cher, puisque les deux schémas MAI Image 2.7 sont identiques à l’ID près.

Les règles des champs proviennent de la référence de l’API PoYo. Pour savoir ce qu’est le modèle et comment il se situe, commencez par la présentation de la MAI Image 2.7 API.

Étape 1 : soumettre une requête à la MAI Image 2.7 API avec cURL

Créez une clé dans le tableau de bord PoYo et exportez-la sous le nom POYO_API_KEY. Gardez-la sur votre serveur, pas dans le code exécuté par le navigateur.

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

Une soumission réussie renvoie code: 200 et un objet data contenant task_id, status: "not_started" et created_time. C’est une tâche en file d’attente, pas encore une image. Vérifiez code dans le corps à chaque fois : certaines erreurs de validation reviennent avec HTTP 200 et code: 400.

Étape 2 : interroger le statut de la tâche

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

Le statut passe par not_started, running, puis finished ou failed. Une tâche terminée liste l’image dans data.files sous forme d’objet avec file_url et file_type: "image", et indique le montant facturé dans credits_amount. Une tâche en échec donne la raison dans error_message.

Étape 3 : une boucle de polling Python bornée

Cette boucle vérifie à la fois le statut HTTP et le code du corps, s’arrête sur failed et abandonne après 10 minutes sans resoumettre. Lors de notre test de lancement du 19 novembre 2026, une image 2K en 16:9 a pris environ 66 secondes sur MAI Image 2.7 et environ 42 secondes sur Flash : un intervalle de polling de 5 secondes suffit largement.

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 signifie « revérifier plus tard le même ID de tâche ». Resoumettre lancerait une seconde tâche facturable.

Tous les modes d’entrée de la MAI Image 2.7 API

Tous les champs vont dans input. L’ID de modèle et une callback_url facultative se placent au niveau racine.

Text-to-image

Seul prompt est obligatoire. Sans size, la sortie est en 1:1 ; sans resolution, elle est en 1K (1024x1024 pour un carré).

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

Éditer une image

Passez une URL dans image_urls. Ce doit être un tableau, même pour une seule image.

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

Sans size, l’édition conserve le ratio de la première image de référence, à environ 1 mégapixel. Ajoutez size si vous voulez un autre ratio ou une taille personnalisée.

Combiner de 2 à 5 images

Plusieurs URL sont combinées en une nouvelle image. Désignez-les dans le prompt par leur rôle pour que le modèle sache ce que chaque image apporte.

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

Les images de référence sont utilisées jusqu’à environ 1 mégapixel : inutile d’envoyer des fichiers beaucoup plus grands.

Taille personnalisée

Une chaîne WIDTHxHEIGHT est utilisée exactement telle quelle.

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

Arrière-plan transparent et format de sortie

{
  "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 fonctionne aussi sur les images opaques : envoyez "jpeg" pour des fichiers photographiques plus légers. Le guide de l’arrière-plan transparent couvre les vérifications alpha et notre essai de sticker mesuré.

Règles de validation des champs

Validez de votre côté avant de soumettre, pour que les requêtes invalides échouent tout de suite :

ChampRègle
modelmai-image-2.7 ou mai-image-2.7-flash
promptObligatoire, de 1 à 32,000 caractères, pas uniquement des espaces
image_urlsTableau de 1 à 5 URL HTTP ou HTTPS publiques, JPEG, PNG ou WebP
size1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16 ou WIDTHxHEIGHT
Taille personnaliséeLes deux côtés divisibles par 16, chaque côté d’au moins 768, largeur x hauteur au plus 4,194,304
resolution1K (environ 1 MP) ou 2K (environ 4 MP, 16:9 donne 2720x1536) ; s’applique aux tailles définies par un ratio
backgroundopaque ou transparent ; transparent exige un output_format png ou webp
output_formatpng, jpeg ou webp
Champs inconnusRefusés ; le schéma n’autorise pas de propriétés supplémentaires, retirez donc les champs comme enable_web_search des requêtes MAI Image 2.6

Exemples : 2048x2048 et 3072x1344 passent ; 3000x1400 échoue (pas des multiples de 16) ; 640x1600 échoue (un côté sous 768) ; 2400x2400 échoue (5,760,000 pixels). "background": "transparent" avec "output_format": "jpeg" échoue, car le JPEG n’a pas de canal alpha.

Erreurs à gérer

codeSignificationQue faire
400Paramètres invalidesCorriger le corps ; ne pas réessayer à l’identique
401Clé API manquante ou invalideVérifier l’en-tête Authorization: Bearer
402Crédits insuffisantsRecharger, puis resoumettre
429Limite de débit dépasséePatienter et réessayer plus tard
500, 502, 503Erreur serveur, amont ou de disponibilitéRéessayer avec backoff ; vérifier d’abord si un ID de tâche a déjà été renvoyé

Une tâche qui passe en failed après soumission indique la raison dans error_message, par exemple un refus lié à la politique de contenu. Consultez les codes d’erreur pour la liste complète. Si votre application accepte des images envoyées par les utilisateurs comme image_urls, les filtrer d’abord évite des tâches en échec ; le guide de modération d’images montre une façon de faire.

Utiliser un callback plutôt que le polling

Ajoutez "callback_url": "https://your-app.example.com/poyo-webhook" au niveau racine du corps. Quand la tâche se termine ou échoue, PoYo envoie en POST les données de la tâche (même forme que le data de la réponse de statut) à cette URL, signées en HMAC-SHA256 dans l’en-tête X-Webhook-Signature. La documentation des webhooks donne la règle de signature. Gardez un polling lent en secours pour les callbacks qui n’arrivent jamais.

Comment votre première facture est calculée

La MAI Image 2.7 API facture des tokens : entrée texte, entrée image (pour image_urls) et sortie image. Sur PoYo, la sortie représente environ un token pour 1,024 pixels.

ModèleEntrée texteEntrée imageSortie image (par 1M de tokens)
mai-image-2.71,000 crédits ($5.00)1,600 crédits ($8.00)6,800 crédits ($34.00)
mai-image-2.7-flash350 crédits ($1.75)500 crédits ($2.50)2,000 crédits ($10.00)

Notre test du jour du lancement (API de production PoYo, 19 novembre 2026) montre ce que cela donne en pratique. La même requête du café en 2K 16:9 a renvoyé 2720x1536 sur les deux niveaux et, aux tarifs actuels, revient à 27.802 crédits (environ $0.139) sur mai-image-2.7 et 8.1803 crédits (environ $0.041) sur mai-image-2.7-flash. Estimation dérivée : 2720x1536 font 4,177,920 pixels, soit environ 4,080 tokens de sortie, ce qui explique 27.744 et 8.16 crédits ; le petit reste correspond dans chaque cas à environ 58 tokens de prompt. L’article sur les prix donne des tableaux de coûts pour chaque taille.

Questions fréquentes

La MAI Image 2.7 API est-elle compatible avec le SDK OpenAI ? Non. C’est une API de tâches asynchrones : soumettez à /api/generate/submit, puis interrogez /api/generate/status/{task_id} ou recevez un callback. Un simple requests, fetch ou cURL suffit.

Comment éditer une image avec la MAI Image 2.7 API ? Ajoutez image_urls avec une URL d’image publique et décrivez la modification dans prompt. Avec 2 à 5 URL, les images sont combinées.

Puis-je définir une taille exacte en pixels dans la MAI Image 2.7 API ? Oui, envoyez size au format WIDTHxHEIGHT avec les deux côtés divisibles par 16, chacun d’au moins 768, et au plus 4,194,304 pixels au total.

Combien d’images renvoie une requête à la MAI Image 2.7 API ? Une seule. Soumettez plusieurs tâches en parallèle pour obtenir des variantes.

La MAI Image 2.7 API renvoie-t-elle du JPEG ? Oui, avec "output_format": "jpeg", tant que background vaut opaque. Le PNG est le format par défaut et le WebP est aussi disponible.

Share: