Tutoriel
Comment appeler flux-2/text-to-image via l'API HiAPI : tutoriel curl et Python
Un exercice de requête fonctionnel : identifiant de modèle, paramètres de prompt et de ratio d'aspect, champs de réponse et gestion des erreurs
Sur cette page
Ce que flux-2/text-to-image expose via l'API
Avant d'écrire la première ligne de code, il est utile de bien comprendre ce à quoi vous vous connectez. Sur HiAPI, flux-2/text-to-image n'est pas un SDK distinct à installer, ni un nouveau service nécessitant une authentification séparée. C'est un identifiant de modèle, transmis avec le prompt décrivant l'image souhaitée à un endpoint partagé de génération d'images.
Ce modèle mental est important car il délimite les frontières de l'intégration. Votre code a besoin de trois choses :
- Des identifiants d'authentification pour l'API HiAPI.
- Un endpoint qui accepte les requêtes de génération d'images.
- Une charge utile JSON contenant
model(défini surflux-2/text-to-image) etprompt.
Tout le reste — ratio d'aspect, préférences de sortie et tout autre paramètre exposé par le modèle — existe comme champs supplémentaires dans cette charge utile. C'est aussi pourquoi passer d'un autre modèle texte-vers-image à flux-2/text-to-image ne demande généralement qu'une modification d'une ligne de configuration, et non une réécriture du code : l'enveloppe de la requête reste identique, seule la valeur de model change.
L'endpoint reçoit votre requête, l'exécute via le modèle, puis renvoie une réponse structurée contenant l'image générée (généralement une URL ou une charge utile encodée) ainsi que les métadonnées de la tâche. Pour un appel basique, vous n'avez pas besoin d'interroger une file de tâches séparée — du point de vue du client, le cycle requête/réponse est synchrone, mais la génération sous-jacente prend du temps, donc le délai d'expiration de votre client HTTP doit être généreux.
Retenez ce tableau : un endpoint, une charge utile, une chaîne de modèle. Le reste de ce tutoriel consiste à remplir la charge utile et à fiabiliser l'appel.
Construire une requête fonctionnelle avec curl
Le moyen le plus rapide de vérifier que les identifiants et la structure de la charge utile sont corrects est un appel curl. Obtenez d'abord une réponse réussie dans le terminal avant de toucher à Python — cela isole les problèmes d'authentification et de charge utile des bugs propres au langage.
Commencez par définir la clé comme variable d'environnement, afin qu'elle ne reste pas en clair dans l'historique du shell :
export HIAPI_API_KEY="your_api_key_here"
Puis envoyez la requête :
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/text-to-image",
"prompt": "un phare usé par les intempéries sur une falaise de granite à l'aube, brouillard léger, plan large",
"aspect_ratio": "16:9"
}'
Points à vérifier lors de l'exécution :
- L'endpoint et la clé proviennent du tableau de bord de votre compte HiAPI. Copier l'endpoint depuis le tableau de bord plutôt que le retaper évite l'échec silencieux le plus courant — une requête envoyée à un endroit inattendu.
-sSgarde la sortie propre tout en exposant les erreurs de curl, comme les échecs DNS ou TLS.- L'en-tête
Authorizationutilise le schéma bearer standard. Pas d'espace ni de guillemets parasites autour de l'expansion de la variable. Content-Type: application/jsonest obligatoire ; sans lui, le corps de la requête peut être rejeté avant même que le modèle ne le voie.
Si l'appel réussit, vous verrez le corps de réponse JSON dans le terminal. Faites-le passer par un formateur pour plus de lisibilité :
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"flux-2/text-to-image","prompt":"un renard roux dans la neige fraîche, à hauteur des yeux","aspect_ratio":"1:1"}' \
| python3 -m json.tool
Une fois que cela fonctionne, vous disposez d'une base de référence fiable. Tout échec ultérieur en Python pourra être comparé à cet appel que vous avez confirmé valide.
Paramètres de prompt et de ratio d'aspect
Deux champs de requête influencent le plus la sortie : prompt et aspect_ratio. Modifiez-en un seul à la fois, sinon vous ne saurez pas lequel a causé le changement observé.
Prompt
Le prompt est la description en langage naturel de l'image. Écrivez-le comme une description de scène compacte plutôt qu'une liste de mots-clés — en gros dans l'ordre sujet, décor, éclairage et composition. Comparez :
- Vague :
un phare - Précis :
un phare usé par les intempéries sur une falaise de granite à l'aube, brouillard léger, plan large
Pendant l'expérimentation, gardez la formulation explicite et stable. Si vous réécrivez à la fois le prompt et le ratio d'aspect dans la même itération, vous avez deux variables et une seule observation. Figez le prompt, ajustez un mot à la fois et notez les changements réels.
Bonnes habitudes :
- Placez le sujet le plus important au début de la chaîne.
- Décrivez l'éclairage et l'ambiance avec des mots concrets plutôt qu'abstraits.
- Conservez dans votre base de code un petit ensemble de prompts de référence et relancez-les à chaque modification d'autre chose, afin de distinguer un changement de comportement du modèle d'un changement de prompt.
Ratio d'aspect
aspect_ratio contrôle la forme de la sortie — large pour les paysages et les bannières, carré pour les avatars et les vignettes, portrait pour les affiches et les mises en page mobiles. Le modèle accepte des chaînes de ratio telles que 16:9, 1:1 ou l'équivalent en portrait ; utilisez les ratios documentés pour le modèle, plutôt que d'en inventer.
Comme le ratio d'aspect est un champ discret unique, c'est le paramètre le plus facile à balayer. Écrivez une boucle qui garde le prompt inchangé, demande la même image dans trois ratios, puis comparez les compositions côte à côte. Vous apprendrez vite quels ratios recadrent le sujet et lesquels lui laissent de l'espace.
Une mise en garde : le ratio d'aspect change la composition effective, pas seulement le canevas. Un prompt écrit pour un plan large peut paraître maigre dans un cadre carré. Une fois le ratio fixé, révisez une fois le prompt pour compenser.
Porter l'appel en Python
L'appel curl se transpose directement en Python. L'objectif est une petite fonction qui prend un prompt et un ratio d'aspect, lit la clé depuis l'environnement et renvoie le JSON analysé — une forme de production, pas un script jetable.
import os
import requests
IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # échouer vite si non défini
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
IMAGE_ENDPOINT,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
Remarques sur les raisons de cette écriture :
- Utilisez des variables d'environnement, pas des littéraux.
os.environ[...]lève immédiatement uneKeyErrorsi la variable manque, ce qui est bien préférable à l'envoi d'un bearer token vide suivi d'une erreur d'authentification déroutante à décoder plus tard. json=payloadlaisserequestssérialiser le corps pour vous et définirContent-Type. Ne construisez pas de chaîne JSON à la main.- Délai d'expiration explicite. La génération d'images n'est pas instantanée ; le délai par défaut du client vous posera problème sous charge. Fixez-le délibérément.
raise_for_status()transforme les réponses non-2xx en exceptions capturables et classables, plutôt qu'en un corps d'erreur qui ressemble à des données.
Appelez-la :
result = generate_image(
"un phare usé par les intempéries sur une falaise de granite à l'aube, brouillard léger, plan large",
aspect_ratio="16:9",
)
print(result)
Si vous préférez httpx, la forme est identique — changez l'import et conservez les mêmes en-têtes, la charge utile json= et le paramètre de délai d'expiration. Ce qui compte, c'est la charge utile, qui reste identique à la version curl.
Lire la réponse
Un appel réussi renvoie un objet JSON. Plutôt que de deviner les noms de champs, inspectez d'abord une vraie réponse, puis écrivez l'analyseur en fonction de ce que vous voyez réellement. Exécutez votre fonction et affichez les clés de premier niveau :
result = generate_image("un renard roux dans la neige fraîche, à hauteur des yeux", "1:1")
print(result.keys())
Les champs que vous utiliserez généralement se répartissent en deux groupes :
- L'image elle-même. La réponse contient l'image générée — généralement une URL que vous pouvez télécharger ou servir, parfois des données d'image encodées. Lisez le nom exact du champ dans votre propre réponse, stockez la valeur et traitez-la selon sa forme. S'il s'agit d'une URL, considérez-la comme éphémère : téléchargez-la ou copiez-la dans votre propre stockage rapidement, au lieu de stocker le lien en base et de supposer qu'il sera encore résolvable le mois prochain.
- Les métadonnées. Attendez-vous à des champs d'accompagnement décrivant la génération — modèle utilisé, ratio d'aspect ou dimensions demandés, et identifiant de la requête. Consignez-les avec l'image. Lorsqu'un utilisateur signale qu'une image « ne semble pas correcte », les métadonnées vous indiquent quel prompt et quel ratio l'ont produite, sans que vous ayez à le redéduire depuis l'état de l'application.
Un modèle d'extraction sûr :
image_ref = result.get("image") or result.get("data")
if not image_ref:
raise ValueError(f"aucune image dans la réponse ; keys={list(result.keys())}")
C'est volontairement défensif. Les noms de champs sont stables au sein d'un modèle, mais écrire l'accesseur de façon à échouer bruyamment en listant les clés réelles évite qu'un None silencieux ne se propage dans votre UI. Une fois les noms de champs confirmés depuis une vraie réponse, resserrez le code pour les lire directement.
Enfin, ne jetez pas la réponse brute. Stockez-la (ou journalisez-la pour une partie des requêtes) jusqu'à ce que votre intégration soit stable — en cas d'anomalie en aval, c'est la source de vérité.
Erreurs courantes et comment les corriger
La plupart des échecs lors du premier essai appartiennent à quelques catégories. Traitez-les par classe de statut HTTP, plutôt que par correspondance de texte de message, qui change sans préavis.
Échecs d'authentification (401 / 403)
Clé manquante, mal formée ou sans droits d'accès. Vérifiez dans l'ordre : HIAPI_API_KEY est-elle réellement définie dans l'environnement visible par votre processus ; l'en-tête est-il exactement Authorization: Bearer <key>, sans espace superflu ni guillemets ; n'avez-vous pas envoyé par erreur une clé issue d'un autre environnement. Si curl fonctionne mais pas Python, affichez l'en-tête que vous envoyez et comparez caractère par caractère.
Charge utile malformée (400)
Le corps de la requête est rejeté avant la génération. Causes fréquentes : JSON invalide (chaîne construite à la main avec une virgule finale), prompt manquant, ou Content-Type incorrect. Le correctif consiste à utiliser json=payload en Python et -d avec du JSON valide en curl. Affichez dans les logs la charge utile sur le point d'être envoyée et lisez-la comme un humain.
Paramètres non pris en charge ou invalides (400 / 422)
Noms de champs ou valeurs non acceptés par le modèle — aspect_ratio mal orthographié, ratio non documenté pour le modèle, ou champ supplémentaire copié depuis un exemple d'un autre modèle. Réduisez la charge utile au minimum (model, prompt), puis ajoutez les champs un par un pour identifier le problème.
Limitation de débit (429)
Vous envoyez des requêtes plus vite que la limite de votre compte ne le permet. C'est temporaire. Ne réessayez pas dans une boucle serrée — utilisez un backoff avec délai croissant et un plafond de tentatives. Si vous traitez par lots, ajoutez un petit délai entre les appels plutôt que tout envoyer d'un coup.
Erreurs côté serveur (5xx) et expirations
Celles-ci sont temporaires et hors de votre contrôle. Réessayez avec backoff et assurez-vous que le délai d'expiration est suffisamment long pour qu'une génération lente ne soit pas classée à tort comme un échec. Une expiration de lecture déclenchée pendant que le modèle travaille encore génère une nouvelle tentative et gaspille une requête.
Regrouper la classification au même endroit facilite la maintenance :
def classify(status: int) -> str:
if status in (401, 403):
return "auth" # corriger la config, ne pas réessayer
if status in (400, 422):
return "payload" # corriger la requête, ne pas réessayer
if status == 429:
return "rate_limit" # réessayer avec backoff
if status >= 500:
return "server" # réessayer avec backoff
return "other"
Encapsuler l'appel pour la production
La fonction ci-dessus fonctionne, mais une intégration réelle a besoin de trois choses qu'elle n'a pas encore : des tentatives qui distinguent les échecs temporaires des échecs permanents, des délais d'expiration réalistes et des logs qui vous permettent de reconstituer ce qui s'est passé. Un petit wrapper couvre ces trois besoins.
import logging
import time
log = logging.getLogger(__name__)
def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, aspect_ratio)
except requests.HTTPError as exc:
status = exc.response.status_code
kind = classify(status)
log.warning("échec de l'appel flux-2", extra={
"attempt": attempt, "status": status,
"kind": kind, "aspect_ratio": aspect_ratio,
})
if kind in ("auth", "payload"):
raise # réessayer ne servira à rien
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
Pourquoi chaque partie compte :
- Ne réessayez que ce qui peut l'être. Les erreurs d'authentification et de charge utile sont déterministes — les réessayer fait perdre du temps et masque le vrai bug. Les limitations de débit, erreurs serveur et expirations bénéficient d'un backoff exponentiel.
- Consignez des champs structurés, pas de la prose. Le numéro de tentative, le statut, la catégorie d'erreur et les paramètres utilisés vous permettent de regrouper les échecs ensuite. Ne consignez jamais la clé API.
- Limitez le nombre de tentatives. Une boucle de tentative non bornée transforme une défaillance en processus de travail bloqué.
- Gardez le délai d'expiration explicite et généreux. Passez-le depuis la configuration, afin de pouvoir l'augmenter lors de périodes creuses connues sans modifier le code.
Deux autres habitudes qui rapportent : persister un hachage de (model, prompt, aspect_ratio) pour chaque image générée, afin de pouvoir reproduire n'importe quelle sortie ; et conserver un petit ensemble de prompts de référence dans la suite de tests, à exécuter après toute modification du wrapper. Ensemble, elles transforment un extrait de tutoriel en quelque chose d'exploitable en production.
Une fois la forme de la requête fixée et la gestion des erreurs en place, changer de modèle ne demande plus qu'une modification d'une ligne sur le champ model — c'est tout l'intérêt d'appeler flux-2/text-to-image via une interface unifiée.
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