MiniMax H3-Image API : comment générer et modifier des images

L'API MiniMax H3-Image génère et modifie des images via deux points de terminaison REST : POST /v1/images/generations pour le texte vers image et POST /v1/images/edits pour l'édition avec 1 à 16 images de référence. Vous envoyez une clé Bearer, l'ID du modèle MiniMax-H3-Image (ou MiniMax-H3-Image-Highspeed), un prompt et une taille, et vous recevez en retour des URL d'images ou des données base64. Elle repose sur la même plateforme de développeurs MiniMax que l'API MiniMax M3. La sortie atteint environ 16 mégapixels sans upscaler.

Au programme : la clé, les champs qui comptent, l'édition, la tarification avec la remise de lancement, et un test exécuté par un agent avec Apidog CLI. Le modèle est nouveau pour vous ? Commencez par qu'est-ce que MiniMax H3-Image.

Qu'est-ce que l'API MiniMax H3-Image ?

L'API MiniMax H3-Image est le point de terminaison hébergé par MiniMax pour son modèle à poids ouverts H3-Image, qui gère à la fois la génération de texte vers image et l'édition multi-références dans un seul checkpoint. Elle est servie à https://api.minimax.io, accepte des requêtes JSON et est compatible avec les appels images.generate et images.edit du SDK OpenAI, si bien que la plupart des codes images existants ne nécessitent qu'une nouvelle URL de base et un nouveau nom de modèle.

Les poids sont également publics : la fiche modèle sur Hugging Face répertorie un transformateur de diffusion de 33,1 milliards de paramètres sous la licence MiniMax-H3-Image Community License. L'auto-hébergement nécessite environ 69 Go pour le checkpoint plus un encodeur de texte de 66,7 Go, l'API reste donc la voie pratique pour la plupart des équipes.

Côté service hébergé, d'après la référence API de MiniMax, consultée le 11/11/2026 :

Obtenez votre clé API MiniMax

1. Connectez-vous sur la plateforme de développeurs MiniMax.
2. Ouvrez Account Management, puis API Keys, et créez une clé.
3. Rechargez votre solde. Une requête sans fonds échoue avec un HTTP 402 et le code d'erreur 1008 (solde insuffisant).
4. Exportez la clé pour que votre code et votre agent la lisent depuis l'environnement, jamais depuis un fichier que vous commitez :

export MINIMAX_API_KEY="your-key-here"

Chaque appel l'envoie via Authorization: Bearer $MINIMAX_API_KEY.

Votre première requête de texte vers image

Le plus petit appel utile nécessite model, prompt et soit une taille, soit un palier de surface :

curl https://api.minimax.io/v1/images/generations \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "aspect_ratio": "16:9",
    "area": "2K",
    "n": 1,
    "response_format": "url"
  }'

Avec le SDK Python OpenAI, pointez base_url vers MiniMax et désactivez les tentatives automatiques :

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_API_KEY"],
    timeout=600,
    max_retries=0,
)

result = client.images.generate(
    model="MiniMax-H3-Image",
    prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
    size="2720x1536",
    response_format="url",
)
for item in result.data:
    print(item.url)  # None for an image that failed

La ligne max_retries=0 est importante. Le point de terminaison n'est pas idempotent : le serveur termine et facture un job même si votre client dépasse le délai d'attente, de sorte qu'une relance automatique facture deux fois. Définissez plutôt un timeout de 600 secondes.

Les paramètres de requête qui comptent

Vous contrôlez la taille de sortie de deux façons, et vous ne pouvez pas les mélanger.

Pixels exacts. Définissez size sur LARGEURxHAUTEUR, par exemple 4096x4096. La surface totale doit être comprise entre 655 360 et 20 000 000 pixels et le ratio d'aspect entre 1:3 et 3:1. N'envoyez pas aspect_ratio ni area dans ce mode, pas même en auto, sinon vous recevez un 400.

Palier plus ratio. Laissez size en auto et définissez area (1K, 2K ou 4K, par défaut 4K) et aspect_ratio (tout X:Y de 1:3 à 3:1). Le serveur calcule les pixels ; 2K en 16:9 renvoie 2720 x 1536.

Les autres champs :

Deux règles piègent souvent les utilisateurs. D'abord, si vous désactivez l'amélioration de prompt, vous devez fournir un size exact ou un aspect_ratio explicite ; auto renvoie un 400. Ensuite, b64_json plafonne la surface totale de sortie : 20 000 000 pixels pour le PNG (une image de n'importe quelle taille) et 80 000 000 pour le JPEG ou le WebP (quatre images 4K ou dix images 2K). Pour des lots plus importants, utilisez des URL.

La fiche modèle indique que H3-Image fonctionne au mieux autour de 16 MP : 4096x4096 (1:1), 5472x3072 (16:9) ou 6272x2688 (21:9).

Modifier des images avec jusqu'à 16 références

L'édition utilise les mêmes champs plus un tableau images. Désignez les entrées par leur position dans le prompt (« image 1 », « image 2 ») :

import os, requests

resp = requests.post(
    "https://api.minimax.io/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
    json={
        "model": "MiniMax-H3-Image",
        "prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
        "images": [
            {"image_url": "https://example.com/cat.jpg"},
            {"image_url": "https://example.com/dog.png"},
        ],
        "size": "auto",
        "response_format": "url",
    },
    timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])

Le point de terminaison accepte aussi multipart/form-data, ce que le SDK OpenAI envoie via images.edit lors d'un téléversement de fichiers. Limites d'après la référence des éditions :

• 1 à 16 images en JPG, PNG, WebP, HEIC ou HEIF
• Chaque côté entre 128 et 8 192 pixels, ratio long/court au plus 4:1
• Corps de requête total jusqu'à 64 Mio ; le base64 ajoute environ un tiers, passez donc à des URL publiques pour les entrées volumineuses

Lire la réponse et gérer les erreurs

Un appel réussi renvoie un élément data par image demandée, dans l'ordre :

{
  "data": [
    {"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
    {"error": {"code": "1027", "message": "output image failed content safety check"}}
  ],
  "output_format": "jpeg",
  "usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
  "request_id": "0217..."
}

Trois bonnes pratiques pour fiabiliser votre intégration :

1. Vérifiez la présence d'un champ error dans chaque élément. Le statut HTTP est 200 si au moins une image réussit, donc un 200 ne signifie pas que les n images sont toutes revenues. Si toutes les images échouent, vous recevez plutôt 402, 422 ou 500.
2. Téléchargez les URL immédiatement. MiniMax indique que l'URL n'est pas garantie de rester disponible, copiez donc le fichier vers votre propre stockage.
3. Journalisez request_id. C'est l'ID de trace que le support vous demandera.

Les limites de débit renvoient un 429. Le code 1002 signifie que vous avez dépassé la limite d'images par minute, et chaque requête compte pour n images : un lot de 10 consomme donc 10 unités de votre quota d'un coup.

Tarification de MiniMax H3-Image et remise de lancement

La facturation est au token, et vous ne payez que les images réussies. D'après la page de tarification de MiniMax, consultée le 11/11/2026 :

MiniMax publie aussi des coûts exemples par image pour le modèle standard :

Highspeed coûte environ 1,6 à 2 fois plus par image (0,13001 $ pour du 4K, 0,06501 $ avec remise). La longueur du prompt influence le coût d'entrée : considérez ces montants comme des estimations.

Offre de lancement : jusqu'au 17 novembre 2026 à 16 h 00 UTC, MiniMax applique 50 % de remise sur le coût total de la requête pour les deux modèles lorsque l'image livrée contient au moins 16 600 000 pixels. Une image 4096x4096 (16 777 216 pixels) est éligible ; une image 2K ne l'est pas. Vous cherchez des solutions à 0 $ ? Consultez comment utiliser MiniMax H3-Image gratuitement.

Laissez votre agent de codage tester l'API avec Apidog CLI

Les API d'images échouent silencieusement : un 200 avec la moitié des images manquantes, une règle de taille oubliée. Laissez plutôt votre agent de codage (Claude Code, Codex, Cursor) construire un test répétable avec Apidog CLI au lieu de vérifier les réponses à la main.

Configuration en une fois :

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

Puis donnez à votre agent un seul prompt :

In Apidog project <projectId>, create an environment "MiniMax Global" with base URL
https://api.minimax.io. Add the endpoint POST /v1/images/generations from the MiniMax
H3-Image API reference, with Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case that sends model MiniMax-H3-Image, area 1K, aspect_ratio 1:1, n 1,
and asserts HTTP 200, data[0].url exists, and no item in data has an error field.
Run it and summarize any failures.

L'agent lit chaque schéma de payload, valide son JSON, crée les ressources et exécute le cas :

apidog environment create "MiniMax Global" --project <projectId> --base-url https://api.minimax.io
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "MINIMAX_API_KEY=$MINIMAX_API_KEY" -r cli,json

--env-var transmet votre clé au moment de l'exécution, elle n'atterrit donc jamais dans un fichier enregistré. Le rapporteur cli affiche chaque assertion en réussite ou échec ; json écrit un rapport que votre agent relit. Gardez le test en 1K : chaque exécution est une génération réelle et facturée. La même ligne s'exécute en CI avec -r junit (voir le guide CI/CD d'Apidog CLI et Apidog CLI dans Claude Code). Le plan gratuit d'Apidog couvre jusqu'à 4 utilisateurs.

Standard ou Highspeed : quel ID de modèle ?

Les deux IDs acceptent des paramètres identiques, changer n'est donc qu'une chaîne à modifier. Utilisez MiniMax-H3-Image pour les livrables finaux et les lots sensibles aux coûts, et MiniMax-H3-Image-Highspeed pour les aperçus interactifs où la latence prime sur le prix. La référence API ne fournit aucun chiffre de latence : chronométrez sur vos propres prompts. Vous évaluez des alternatives ? Lisez MiniMax H3-Image vs Nano Banana 2.1, le guide de l'API Nano Banana 2.1 ou le guide de l'API GPT Image 2.6.

FAQ

Quel est l'ID du modèle MiniMax H3-Image ? Utilisez MiniMax-H3-Image pour le modèle standard ou MiniMax-H3-Image-Highspeed pour la version plus rapide et plus chère. Les deux fonctionnent sur /v1/images/generations et /v1/images/edits avec les mêmes paramètres.

L'API MiniMax H3-Image est-elle compatible avec le SDK OpenAI ? Oui. Définissez base_url="https://api.minimax.io/v1" et appelez images.generate ou images.edit. Définissez max_retries=0, car les relances créent de nouvelles générations facturées.

Combien d'images de référence puis-je utiliser pour l'édition ? De 1 à 16 par requête, chacune de 128 à 8 192 pixels par côté, avec un corps de requête total sous 64 Mio.

Combien coûte une image MiniMax H3-Image ? Les exemples de MiniMax situent un appel standard texte vers image à environ 0,022 $ pour du 1K et 0,069 $ pour du 4K, le 4K étant divisé par deux à environ 0,034 $ jusqu'au 17 novembre 2026, 16 h 00 UTC.

Pourquoi ai-je reçu un 200 avec moins d'images que demandé ? Un succès partiel renvoie 200. Les éléments en échec, y compris ceux bloqués par le contrôle de sécurité, portent un objet error au lieu d'une url, et vous n'êtes pas facturé pour eux.