Tutoriel
Comment utiliser minimax-h3-image de génération d'images à partir de texte via l'API HiAPI : curl et Python
Sur cette page
Ce que couvre ce tutoriel et ce dont vous avez besoin au préalable
Ce tutoriel traite d'une seule chose précise : envoyer une invite de génération d'image au modèle de génération d'images à partir de texte minimax-h3-image via l'API HiAPI, d'abord avec une requête curl, puis avec une petite fonction Python que vous pouvez intégrer dans une application. Il couvre la structure de la requête, la lecture de la réponse, la façon dont les erreurs se manifestent et les points à durcir avant une mise en production.
Il ne traite volontairement ni de la théorie de l'ingénierie des invites, ni du post-traitement des images, ni de la construction d'une interface utilisateur. L'objectif est plus ciblé : à la fin de votre lecture, vous devez disposer d'une requête fiable et savoir précisément pourquoi la dernière a échoué.
Prérequis
- Un compte HiAPI. Avant toute chose, vous avez besoin d'un projet et d'une clé d'API — chaque requête ci-dessous nécessite une authentification.
- Stockez la clé en lieu sûr. Placez-la dans une variable d'environnement (
HIAPI_API_KEY) plutôt que dans un fichier source, afin que le même code fonctionne en local et en CI. - L'identifiant du modèle. Ce tutoriel utilise
minimax-h3-imageet sa capacitétext-to-image. Traitez le nom du modèle et le chemin de la tâche comme des valeurs de configuration dans le code, et non comme des chaînes magiques dispersées. - Outils.
curlpour la première requête, Python 3.9+ etrequestspour la seconde. Aucune autre bibliothèque n'est nécessaire. - Un moyen de consulter l'image. Vous lirez une charge utile de réponse contenant les données de l'image ou une référence à celle-ci — inspectez manuellement les champs de réponse une fois avant de supposer un quelconque schéma.
Une habitude à prendre dès maintenant
Obtenez une première requête réussie en dehors de votre code applicatif. Une commande curl qui fonctionne est la source de vérité : chaque fois que la version Python se comporte anormalement, comparez avec elle. Si l'appel curl réussit et que Python échoue, le problème vient de votre client, pas du modèle ni du réseau.
Construire une requête de génération d'image fonctionnelle avec curl
Commencez par la requête la plus simple possible, puis rajoutez les réglages un par un. Une requête de génération se compose de trois parties : le point de terminaison, l'en-tête d'authentification et le corps JSON.
La requête
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": "Un bol en céramique sur une nappe en lin, douce lumière d'une fenêtre au nord, objectif 50 mm, faible profondeur de champ",
"size": "1024x1024",
"n": 1
}'
Trois points méritent attention dans cette commande :
- La clé est transmise comme jeton bearer dans l'en-tête
Authorization. Ne la placez jamais dans l'URL ni dans le corps de la requête, sinon elle apparaîtrait dans les journaux et l'historique du shell. modelettaskdécrivent ce que vous voulez — la famille de modèles et la capacité. Indiquez les deux explicitement, même si des valeurs par défaut existent ; une requête explicite résiste mieux au temps.promptest une chaîne ordinaire. Tout le reste (size,n) constitue des réglages d'image, et non une description du sujet.
Interpréter la réponse
Formatez la sortie pour pouvoir réellement la lire :
curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Pendant l'itération, placez le corps de la requête dans un fichier (request.json) — l'invite reste ainsi lisible et la modifier devient un diff d'une ligne plutôt qu'un jeu de devinettes sur les guillemets.
Inspectez la charge utile avant d'écrire un parseur. Notez si l'image est renvoyée en ligne ou sous forme d'URL, quels champs portent l'identifiant de l'image et toute invite modifiée, et si la réponse contient des métadonnées d'utilisation. Notez ces noms de champs ; votre client Python en dépendra.
Confirmer l'ensemble du flux de bout en bout
Enregistrez l'image renvoyée, ouvrez-la et vérifiez que vous avez reçu ce que vous avez demandé. Une réponse 200 avec un corps JSON plausible ne signifie pas une image correcte — c'est précisément à ce stade que les problèmes d'invite et de paramètres se détectent le plus facilement.
Traduire la requête en Python
Portez maintenant exactement la même requête. Restez simple : une fonction, des délais d'attente explicites, aucune reprise masquée pour l'instant.
import os
import requests
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
"""Génère une image avec minimax-h3-image via HiAPI."""
payload = {
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
ENDPOINT,
headers={
"Authorization": f"Bearer {HIAPI_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 120), # délai de connexion, délai de lecture
)
response.raise_for_status()
return response.json()
Cette fonction comporte quatre choix délibérés :
- Délai d'attente sous forme de tuple. Le délai de connexion est court, car une connexion lente signale un problème ; le délai de lecture est plus large, car la génération d'image prend naturellement du temps. Une valeur unique oblige à mal gérer l'un des deux modes d'échec.
json=payload. Laissez la bibliothèque sérialiser le corps de la requête. Les chaînes JSON assemblées à la main sont un terreau à bugs de guillemets.raise_for_status()avant l'analyse. La vérification du statut n'est pas facultative — analyser un corps de réponse d'erreur comme s'il s'agissait d'un succès est le type de bug le plus déroutant dans ce genre d'intégration.- Retourner un simple
dict. Vous pourrez plus tard l'envelopper dans un modèle typé ; assurez-vous d'abord de connaître les champs réellement présents dans la réponse.
Isoler la récupération de la clé
Si la variable est absente, os.environ["HIAPI_API_KEY"] lève immédiatement une exception. C'est intentionnel : échouer au démarrage plutôt qu'à la première requête utilisateur. Dans une base de code plus grande, résolvez la clé une seule fois au chargement de la configuration, puis passez un client déjà configuré plutôt que de lire la variable d'environnement au point d'appel.
Effectuer l'exécution
if __name__ == "__main__":
result = generate_image("Un cerf-volant rouge au-dessus d'une plage mouillée à marée descendante, lumière couverte")
print(result)
Exécutez-le et comparez avec la sortie de curl. La structure de la charge utile doit être identique. Si ce n'est pas le cas, vous avez trouvé une divergence qu'il vaut la peine d'élucider avant de poursuivre le développement.
Traiter les erreurs plutôt que deviner
Le bug d'intégration le plus courant consiste à réessayer une erreur qui ne réussira jamais. Classez les échecs en trois catégories et traitez-les différemment.
Échecs d'authentification et d'autorisation
Ils se manifestent généralement par 401 ou 403. Causes : en-tête manquant, préfixe Bearer mal formé, clé révoquée ou mal configurée, ou projet sans accès au modèle. Ils ne sont pas réessayables. Réessayer ne fait que perdre du temps et polluer les journaux avec le même échec. Corrigez les identifiants et continuez.
Échecs de validation de la requête
Il s'agit généralement de réponses de niveau 400 : valeur de model ou task inconnue, size non prise en charge par le modèle, n hors limites, invite vide, JSON mal formé. Elles ne sont pas non plus réessayables — la même requête échouera de la même manière. Le travail utile consiste à présenter le message d'erreur tel quel au développeur qui a écrit la requête, et non à l'enfouir dans une exception générique.
Échecs transitoires du serveur et du réseau
Les réponses 429 et 5xx, ainsi que les réinitialisations de connexion et les délais de lecture, constituent la véritable catégorie réessayable. Gérez-les avec un backoff exponentiel plafonné et du jitter :
import time, random, requests
def post_with_retry(session, url, payload, max_attempts=4):
for attempt in range(max_attempts):
try:
r = session.post(url, json=payload, timeout=(5, 120))
if r.status_code in (429, 500, 502, 503, 504):
raise requests.HTTPError(f"Erreur transitoire {r.status_code}", response=r)
r.raise_for_status()
return r.json()
except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
if attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
Deux mises en garde. Premièrement, un HTTPError déclenché par un 4xx autre que 429 doit être propagé immédiatement — ne laissez pas la clause except absorber les échecs de validation. Deuxièmement, respectez les indications de reprise éventuellement présentes dans la réponse plutôt que d'inventer vos propres délais.
Les reprises ici ne sont pas idempotentes
Chaque génération réessayée est une nouvelle génération facturée. Si la requête expire, l'image a peut-être tout de même été générée et facturée. Limitez le nombre de reprises, enregistrez le nombre de tentatives dans les journaux avec les métadonnées de la requête, et privilégiez un échec explicite plutôt que de générer silencieusement quatre fois la même image.
Bonnes pratiques pour les invites et les paramètres
Ces habitudes visent la comparabilité : lorsque vous modifiez une chose, vous devez pouvoir déterminer si le changement de sortie en découle.
Écrire des invites qui précisent le contenu de l'image
Décrivez dans l'ordre le sujet, la scène, l'éclairage et la composition. Les noms concrets et les termes photographiques (comme « douce lumière d'une fenêtre au nord », « faible profondeur de champ ») portent plus de signal que l'empilement d'adjectifs esthétiques. Évitez d'abuser des invites négatives ; décrivez ce qui doit apparaître.
Ne changer qu'une variable à la fois
Conservez un petit fichier d'invites par projet et modifiez-le entre les exécutions plutôt que de le réécrire intégralement. Si une exécution déçoit, changez soit l'invite, soit les réglages — pas les deux. Sinon, vous ne saurez pas quel changement a eu un effet.
Traiter les réglages comme un contrat explicite
size et n influencent à la fois la sortie et le coût. Fixez-les dans un objet de configuration plutôt que de disperser des littéraux dans les points d'appel, afin que changer le format pour toute une fonctionnalité ne soit qu'une seule modification. Si vous avez besoin de plusieurs images à comparer, demandez-les en un seul appel plutôt qu'en plusieurs — moins d'allers-retours et des journaux plus lisibles.
Stocker les invites avec les sorties
Conservez durablement, à côté de chaque image générée, la chaîne d'invite exacte, les réglages et l'identifiant du modèle. Une invite impossible à reproduire est une image impossible à régénérer, déboguer ou améliorer. Cette seule habitude fait gagner plus de temps que n'importe quelle astuce d'invite.
Fixer une graine pour les comparaisons
La même invite peut produire des images différentes d'une exécution à l'autre. Lorsque vous évaluez un changement, comparez des résultats agrégés — plusieurs images par configuration — plutôt que de vous fier à un seul échantillon chanceux ou malchanceux.
Versionner les invites
Traitez le texte des invites comme du code : conservez-le dans des fichiers, révisez les modifications et enregistrez quelle version d'invite a produit quel actif. Cela fait de « pourquoi les images étaient-elles moins bonnes mardi dernier ? » une question à laquelle on peut répondre.
Liste de vérification avant la mise en production
Une requête qui fonctionne n'est que la partie facile. Les vérifications suivantes distinguent une démo d'une intégration.
- Définir un délai d'attente à chaque appel. Définissez explicitement les délais de connexion et de lecture, jamais les valeurs par défaut. Un point de terminaison de génération sans délai de lecture finira par bloquer un worker.
- Reprises plafonnées, uniquement pour les erreurs réessayables. Limitez le nombre de tentatives, ajoutez du jitter et assurez-vous que les échecs de validation et d'authentification contournent entièrement le chemin de reprise.
- Gestion des clés. Lisez la clé depuis l'environnement ou un coffre de secrets, jamais depuis le code source. Renouvelez-la sans modifier le code.
- Journalisation structurée. Enregistrez l'identifiant du modèle, l'invite (ou son hash et une référence), les réglages, le statut HTTP, le nombre de tentatives et tout identifiant de requête présent dans la réponse. Sans cela, les problèmes d'image seront impossibles à reproduire.
- Visibilité des coûts. La génération est facturée à la sortie, donc l'utilisation dépend du nombre d'images demandées et de la fréquence des reprises. Déterminez à l'avance si les requêtes sont par utilisateur, par tâche ou en arrière-plan, et suivez les volumes en conséquence — consultez le panneau de tarification en temps réel sur le site pour les tarifs actuels plutôt que de coder en dur des hypothèses.
- Définir le comportement en cas d'échec. Décidez ce que l'utilisateur rencontre si la génération échoue après la dernière tentative : état d'erreur, image de substitution ou nouvelle tentative en file d'attente. Un fallback non défini devient une expérience utilisateur non définie.
- Figer le schéma de la charge utile. Stockez et validez les champs de réponse dont vous dépendez, afin qu'un changement de charge utile se manifeste par une erreur explicite plutôt que par un
Nonesilencieux.
Étape de validation finale
Exécutez la commande curl, la fonction Python et une requête volontairement cassée (d'abord une mauvaise clé, puis un mauvais paramètre), et confirmez que chacune produit l'échec attendu. Cette dernière étape est celle qui vous dit que la gestion des erreurs est réelle et non décorative.
Une fois la requête authentifiée, portée, réessayée raisonnablement et journalisée, l'intégration peut passer derrière le reste de l'application.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage