API MAI Image 2.6 : générer, retoucher et suivre les tâches

La première décision d’intégration de MAI Image 2.6 concerne le contrat de service utilisé par votre application. Microsoft documente la génération et la retouche via Foundry. Sur reAPI, les deux opérations passent par le point de terminaison de génération d’images : ajoutez des URL de référence pour une retouche, puis interrogez l’identifiant de tâche renvoyé. Les noms de modèle se ressemblent, mais l’authentification, les corps de requête et les réponses ne sont pas interchangeables.^[1]

Ce guide suit le contrat reAPI pour mai-image-2.6. Commencez par une requête textuelle avant d’ajouter les références ou le cadrage automatique. Vous aurez ainsi une intégration simple à examiner en cas d’échec. Gardez la référence complète des paramètres à côté de votre implémentation ; le playground MAI Image 2.6 propose les mêmes réglages et les estimations actuelles.^[2]

Les points essentiels

• Envoyez mai-image-2.6 avec un prompt non vide au point de terminaison d’images. Une requête produit une image.^[2]
• Utilisez un rapport d’aspect avec 1K ou 2K, ou une paire valide de dimensions en pixels. Ce point de terminaison n’accepte pas 4K.^[2]
• Fournissez jusqu’à cinq URL publiques d’images, ordonnées, pour la retouche avec références. Le modèle choisit alors les dimensions de sortie.^[2]
• Enregistrez l’identifiant de tâche et interrogez-le jusqu’à completed ou failed. L’envoi seul ne contient pas l’image terminée.^[2]
• Considérez le montant affiché comme une estimation. La réservation est régularisée à la fin ; ?include=billing donne accès à la facturation précise.^[2]

Envoyer votre première requête MAI Image 2.6

Créez une clé reAPI et stockez-la dans l’environnement de votre serveur sous REAPI_API_KEY. La requête exige un modèle et un prompt non vide. Cet exemple demande une image carrée avec des dimensions explicites pour faciliter la vérification du format souhaité. C’est une requête d’exemple, sans garantie que chaque objet généré respecte parfaitement le brief.

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer $REAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mai-image-2.6",
    "prompt": "A matte ivory ceramic teapot on a pale blue table, soft daylight, product photography.",
    "width": 1024,
    "height": 1024,
    "n": 1
  }'

L’identifiant API contient un point avant 6. L’URL de la page modèle utilise /models/mai-image-2-6 ; copier ce slug avec des traits d’union dans la requête donne une autre chaîne. Enregistrez l’id de tâche dès que l’envoi réussit. Il permet de récupérer le résultat, d’identifier un échec ou de reprendre après une déconnexion du client. Une requête produit une image ; augmenter n ne constitue pas un lot pris en charge.^[2]

Gardez votre clé hors du code exécuté dans le navigateur. Le frontend peut envoyer le brief au backend, qui ajoute le jeton Bearer et transmet la requête. Selon votre gestion des accès, renvoyez au frontend votre identifiant de traitement ou celui de la tâche. Ne placez pas la clé dans une chaîne de requête, une capture d’écran ou un rapport d’erreur copié.

Interroger la tâche déjà envoyée

Un envoi réussi est un accusé de réception, pas l’image terminée. Interrogez GET /api/v1/tasks/:id jusqu’au statut completed ou failed. Une tâche terminée expose l’image dans output.image_urls ; une tâche échouée expose error. L’ancienne valeur usage.credits est arrondie aux crédits entiers. Pour une comptabilité précise, utilisez ?include=billing et examinez billing.credits_exact et billing.cost_usd, ainsi que les éléments relatifs aux montants débités et aux insuffisances lorsqu’ils sont présents. Interroger la tâche initiale ne lance pas une autre génération.^[2]

const taskId = submittedTask.id;
const headers = { Authorization: `Bearer ${process.env.REAPI_API_KEY}` };
const deadline = Date.now() + 5 * 60 * 1000;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://reapi.ai/api/v1/tasks/${encodeURIComponent(taskId)}`,
    { headers },
  );
  if (!response.ok) {
    throw new Error(`Task lookup failed: HTTP ${response.status}; task ${taskId}`);
  }
  const task = await response.json();
  if (task.status === 'completed') {
    console.log(task.output.image_urls, task.usage);
    break;
  }
  if (task.status === 'failed') {
    throw new Error(JSON.stringify({ taskId, error: task.error }));
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

Ici, submittedTask est la réponse analysée d’un envoi réussi. La limite de cinq minutes est un exemple applicatif, pas une garantie de latence. À son expiration, conservez taskId et indiquez que l’application a cessé d’attendre. Ne qualifiez la génération d’échec que si la tâche signale un échec. Dans un client de production, renvoyez un état distinct de délai dépassé après la boucle et proposez de rafraîchir le statut de cette même tâche.

Une erreur réseau après l’envoi crée une autre ambiguïté : le serveur peut avoir accepté la requête avant la coupure. Répéter automatiquement chaque POST peut créer des tâches facturables supplémentaires. Séparez l’envoi des interrogations et sauvegardez tout identifiant renvoyé avant les opérations facultatives de l’interface.

Choisir une taille acceptée par le point de terminaison

Pour une requête MAI Image 2.6 textuelle, utilisez un rapport d’aspect associé à un niveau de résolution ou des dimensions explicites. Le point de terminaison accepte 1K et 2K, pas 4K. Chaque côté explicite doit mesurer au moins 768 pixels, et la surface totale ne peut dépasser 2 359 296 pixels. Les rapports utilisent des entiers positifs et vont de 1:4 à 4:1.^[2]

La largeur et la hauteur associées ont priorité sur les dimensions en pixels dans size, qui ont elles-mêmes priorité sur le rapport et la résolution. Utilisez si possible une seule méthode claire. Par exemple, width: 1024, height: 1024 avec size: "16:9" exprime des intentions contradictoires, même si la priorité documentée résout la requête. Votre formulaire peut éviter cette confusion.

Les dimensions sont arrondies au multiple de 32 inférieur. Une demande de 1000 × 1000 correspond donc à 992 × 992 selon cette règle. Si une mise en page exige une taille de livraison précise, demandez des multiples valides et examinez les dimensions du fichier téléchargé. Traitez le recadrage ou le redimensionnement ultérieur comme une étape distincte.^[2]

Passer de la génération à la retouche avec références

Ajoutez image_urls à la requête MAI Image 2.6 pour fournir des références visuelles. Le point de terminaison reAPI accepte jusqu’à cinq URL HTTP(S) publiques d’images. Le prompt reste obligatoire. Conservez un ordre stable et expliquez quelle image apporte la scène, le sujet ou le style.^[2]

{
  "model": "mai-image-2.6",
  "prompt": "Use the first image as the room and the second as the chair. Replace the chair beside the window. Preserve the floor, window, and camera view.",
  "image_urls": [
    "https://example.com/room.jpg",
    "https://example.com/chair.jpg"
  ],
  "web_grounding": false
}

Remplacez les URL d’exemple par des fichiers d’images accessibles, de préférence JPEG ou PNG. Une URL qui nécessite une connexion n’est pas une référence adaptée à cette requête. Vérifiez qu’elle renvoie les données de l’image attendue, plutôt qu’une visionneuse HTML ou une page d’accès expiré.

La retouche avec références suit une autre règle de taille : le modèle choisit les dimensions de sortie et size, resolution, width et height ne les contrôlent pas. Ajouter des références à une requête auparavant textuelle modifie donc plus que le contexte visuel. Cela change aussi ce que votre application peut promettre concernant le format renvoyé.^[2]

N’interprétez pas « garder la pièce inchangée » comme une garantie d’identité pixel par pixel. Examinez l’objet modifié, les contours proches, les reflets et les éléments à conserver. Pour un produit, vérifiez séparément logos, étiquettes et proportions physiques. Ce sont des contrôles d’acceptation suggérés ; ce guide ne prétend pas avoir mesuré la précision du modèle sur ces tâches.

Utiliser le cadrage automatique et le contexte web à bon escient

auto_aspect_ratio: true demande à MAI Image 2.6 de déduire un cadrage à partir du prompt, comme size: "auto". C’est utile pour explorer une composition, moins adapté lorsqu’une étape suivante exige un format fixe. Le choix automatique rend aussi le nombre final de pixels incertain avant la fin.

web_grounding est un booléen distinct, désactivé par défaut avec false. Microsoft présente le contexte web comme une entrée créative du modèle, mais activer ce réglage ne rend pas chaque étiquette ou fait représenté fiable. Vérifiez les informations importantes pour le visuel final.^[3]

Aucun de ces réglages ne remplace un prompt clair. Indiquez d’abord sujet, composition, matériaux et modification voulue. Activez ensuite les contrôles utiles au brief. Enregistrer les valeurs envoyées permet de distinguer une révision du prompt d’un changement de réglages.

Comprendre l’estimation avant d’automatiser les nouvelles tentatives

Les tarifs de MAI Image 2.6 dépendent des entrées et des pixels générés. reAPI réserve un montant estimé à l’envoi, puis régularise la facturation à la fin. Le montant final peut être inférieur ou supérieur. Les références et les dimensions choisies par le modèle empêchent de traiter l’estimation comme un prix fixe par image.^[2]

Utilisez l’estimation actuelle de la page modèle pour votre requête prévue. Le guide des tarifs et de Flash explique pourquoi image carrée, retouche avec références et image large représentent des budgets différents. Cet article ne fige pas un tarif dans le code d’exemple.

Les générations échouées sont remboursées selon le contrat des tâches. Une image terminée qui vous déplaît reste une génération terminée. Prévoyez donc les essais créatifs supplémentaires comme des tâches distinctes. Notez les résultats acceptés et le nombre de tentatives nécessaires pour comparer le coût d’un visuel utilisable plutôt que celui d’un seul envoi.

Questions fréquentes sur l’intégration de MAI Image 2.6

Quel identifiant de modèle envoyer ?

Envoyez mai-image-2.6, avec le point avant 6. Le slug mai-image-2-6 sert aux URL du site et n’est pas l’identifiant de modèle de la requête.^[2]

Une requête peut-elle générer plusieurs images ?

Non. Ce point de terminaison accepte n: 1. Envoyez des requêtes distinctes pour les tentatives supplémentaires et comptabilisez chaque tâche séparément.^[2]

MAI Image 2.6 peut-il créer une image 4K par ce point de terminaison ?

Non. Les niveaux documentés sont 1K et 2K. Les dimensions explicites exigent au moins 768 pixels par côté et une surface totale maximale de 2 359 296 pixels.^[2]

Pourquoi une retouche ignore-t-elle ma largeur et ma hauteur ?

Les références modifient le comportement de taille. Le modèle choisit les dimensions ; size, resolution, width et height ne contrôlent plus cette sortie. Examinez le fichier renvoyé avant de promettre une taille de livraison.^[2]

Le contexte web est-il obligatoire ?

Non. web_grounding vaut false par défaut. Activez-le quand il sert le brief et vérifiez toujours les faits et étiquettes représentés dans l’image terminée.^[2][3]

Un délai dépassé lors des interrogations signifie-t-il un échec de génération ?

Non. La limite du client signifie seulement qu’il a cessé d’attendre. Conservez l’identifiant et récupérez à nouveau le statut. La génération n’a échoué que lorsque la tâche indique failed.^[2]

Recherches de téléchargement et choix du modèle

Un client API n’est pas un checkpoint de modèle téléchargeable. Cette intégration appelle un service hébergé et n’installe pas de poids. Microsoft documente les déploiements Foundry du modèle standard et de Flash ; ces instructions sont distinctes du point de terminaison reAPI de cet article.^[1]

L’identifiant mai-image-2.6 sélectionne MAI Image 2.6 standard. N’ajoutez pas flash et ne substituez pas un nom de déploiement sauf si le service appelé documente explicitement ce modèle. Pour une première intégration, gardez identifiant, point de terminaison, corps de requête et analyseur de réponse dans un exemple vérifié. N’ajoutez des modèles alternatifs qu’après avoir examiné leurs contrats séparément.

Références

1. Microsoft Learn. Déployer et utiliser les modèles d’images MAI dans Microsoft Foundry. Consulté le 9 octobre 2026 sur learn.microsoft.com/azure/foundry/foundry-models/how-to/use-foundry-models-mai-image.
2. reAPI. Contrat de requêtes, tailles, interrogations et facturation de MAI Image 2.6. Examiné le 9 octobre 2026 : reapi.ai/docs/mai-image-2-6.
3. Microsoft AI. MAI-Image-2.6. Consulté le 9 octobre 2026 sur microsoft.ai/models/mai-image-2-6.