Tutoriel
Comment appeler gpt-image-2.6-sunburst/text-to-image via l'API HiAPI : guide curl et Python
Authentification, structure de requête, exemples curl et Python exécutables, et dépannage
Sur cette page
À quoi ressemble cette intégration de bout en bout
Chaque appel de génération d'image à partir de texte sur HiAPI suit le même cycle de vie, et il vaut la peine de le comprendre avant d'écrire la moindre ligne de code. Votre application construit une requête JSON décrivant l'image cible, l'envoie avec vos identifiants API au point de terminaison HiAPI correspondant à gpt-image-2.6-sunburst/text-to-image, puis reçoit une réponse contenant les données de l'image générée ou une URL permettant de la récupérer. Une fois ces trois phases comprises, le reste de ce guide n'est plus qu'un complément de détails.
Voici le découpage des phases :
- Authentification — attachez votre clé API HiAPI à la requête, généralement sous forme d'en-tête HTTP. Aucune négociation de jeton n'est nécessaire à chaque appel.
- Construction de la requête — assemblez un corps de requête JSON contenant votre prompt, et éventuellement des paramètres comme les dimensions ou le nombre d'images.
- Transmission — envoyez le corps en POST vers le point de terminaison. L'appel est synchrone, le client attend donc que la génération de l'image soit terminée.
- Traitement de la réponse — l'API renvoie un JSON structuré. Selon la configuration du point de terminaison, les données de l'image arrivent sous forme d'URL ou de contenu d'image encodé, qu'il vous faut décoder et écrire sur le disque.
Un détail à relever dès maintenant : l'identifiant de modèle gpt-image-2.6-sunburst/text-to-image contient une barre oblique. Traitez-la comme une chaîne opaque. N'essayez pas de la séparer en nom de fournisseur et nom de modèle, et ne l'encodez ni ne la normalisez vous-même dans l'URL. Copiez-la exactement telle qu'elle figure dans la documentation et placez-la à un seul endroit dans votre code, afin de ne plus avoir à la chercher plus tard.
Les sections suivantes détaillent chaque phase dans l'ordre. Les parties curl et Python utilisent délibérément la même charge utile de requête, ce qui vous permet de les comparer ligne par ligne ; la partie dépannage associe quant à elle les erreurs les plus probables au champ de requête précis à corriger.
Authentifier les requêtes HiAPI
HiAPI utilise un schéma d'authentification basé sur une clé API. Vous récupérez la clé depuis le tableau de bord de votre compte et l'envoyez à chaque requête. La forme standard est un en-tête HTTP sur la requête :
Authorization: Bearer YOUR_API_KEY
Certains clients préfèrent envoyer la clé dans un en-tête dédié, mais sauf indication contraire dans la documentation de votre compte, utilisez la forme Authorization: Bearer, car elle correspond d'emblée à la plupart des outils HTTP.
Garder la clé hors du code source
L'erreur de sécurité la plus courante lors d'une première intégration consiste à coder la clé en dur dans le script puis à la versionner. Évitez cela dès le premier jour :
- Lisez la clé depuis une variable d'environnement, par exemple
HIAPI_API_KEY, et échouez immédiatement au démarrage si la variable est absente. - Ajoutez le fichier local
.envà.gitignoreavant même de le créer. - En CI ou en production, injectez la clé depuis le coffre à secrets de la plateforme plutôt que de la lire depuis un fichier versionné.
Une petite fonction utilitaire qui lit la clé une seule fois et lève une erreur claire si elle manque vous épargnera plus tard une séance de débogage déroutante :
import os
api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
raise RuntimeError("HIAPI_API_KEY is not set")
Traiter la clé comme un secret aussi au moment de la requête
Lors du diagnostic d'un appel échoué, ne cédez pas à la tentation d'afficher l'objet de requête complet avec ses en-têtes. Consignez plutôt le point de terminaison, l'identifiant de modèle et le code de statut. Si vous devez absolument capturer les en-têtes pour déboguer, masquez d'abord la valeur de Authorization. Une clé qui fuit dans un agrégateur de journaux est aussi exposée qu'une clé versionnée dans un dépôt de code.
Si vous faites tourner vos clés, l'ancienne devient immédiatement invalide une fois la rotation terminée : planifiez donc les rotations comme une opération régulière et non comme une urgence.
Anatomie d'une requête de génération d'image à partir de texte
Le corps de la requête est un objet JSON. Pour gpt-image-2.6-sunburst/text-to-image, le nombre de champs essentiels est réduit, et c'est précisément pourquoi il vaut la peine de comprendre exactement le rôle de chacun plutôt que de copier la charge utile à l'aveugle.
Le champ model
"model": "gpt-image-2.6-sunburst/text-to-image"
Ce champ sélectionne le modèle et est obligatoire. Gardez cette chaîne identique octet pour octet à l'identifiant de la documentation. Une barre oblique manquante, un espace en trop ou une modification de la casse entraînera le rejet de la requête pour modèle inconnu.
Le champ prompt
"prompt": "Une prairie alpine ensoleillée à l'heure dorée, des fleurs sauvages au premier plan, mise au point nette"
Il s'agit de la description en langage naturel de l'image, et le champ est obligatoire. Quelques conseils pratiques sur le prompt lui-même :
- Écrivez d'abord le sujet, puis la scène, enfin les indications de style ou de lumière.
- Privilégiez les noms concrets aux concepts abstraits ; « une tasse en céramique rouge sur une table en bois » vaut mieux que « une jolie scène de tasse ».
- Si vous avez besoin d'une sortie cohérente sur plusieurs appels, gardez la formulation des parties invariantes stable et ne remplacez par programme que les parties variables.
Paramètres facultatifs
Selon le point de terminaison, vous pouvez aussi envoyer des paramètres contrôlant la forme et le nombre de sorties, les plus courants étant :
- size — les dimensions de sortie, exprimées au format indiqué par la documentation, par exemple
1024x1024. Si vous l'omettez, la valeur par défaut s'applique ; si vous envoyez une valeur non prise en charge, attendez-vous à une erreur de validation. - n — le nombre d'images générées pour un prompt. Chaque image générée est facturée séparément, gardez donc cette valeur au minimum nécessaire à votre flux de travail.
N'envoyez que les paramètres dont vous avez réellement besoin. Les champs inconnus peuvent déclencher une erreur de validation stricte, qui pointera vers un champ que vous n'aviez aucune intention d'envoyer.
Un exemple de corps de requête complet
{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "Une prairie alpine ensoleillée à l'heure dorée, des fleurs sauvages au premier plan, mise au point nette",
"size": "1024x1024",
"n": 1
}
C'est tout le contrat. Le reste de ce guide porte sur le transport de cette charge utile, la gestion des erreurs et le cycle de vie.
Envoyer une requête fonctionnelle avec curl
Avant de construire un client Python, confirmez avec curl que le point de terminaison et les identifiants fonctionnent. Cela permet d'isoler les problèmes d'authentification des problèmes de code.
La commande d'appel
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "Une prairie alpine ensoleillée à l'heure dorée, des fleurs sauvages au premier plan, mise au point nette",
"size": "1024x1024",
"n": 1
}'
Quelques précisions sur ces options :
-sSgarde une sortie propre tout en affichant les erreurs de transport.-X POSTspécifie la méthode ; le corps est transmis via-d.- Les guillemets simples autour du corps JSON empêchent le shell de l'interpréter. Sous Windows
cmd, les règles de guillemets JSON diffèrent : utilisez donccurl.exeavec des guillemets doubles et échappez les guillemets internes, ou exécutez l'appel depuis un script shell ou Python.
Si vous utilisez le chemin exact du point de terminaison indiqué dans la documentation de votre compte, remplacez-le ici ; la forme de la requête ne change pas.
Inspecter la réponse brute
En cas de problème, il vous faut le code de statut et le corps de la réponse. Ajoutez -i pour inclure les en-têtes de réponse, ou -w "\nHTTP %{http_code}\n" pour afficher le statut à la fin :
curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json
Il est judicieux d'enregistrer la charge utile dans payload.json et de la référencer via @payload.json : vous évitez les erreurs de guillemets du shell et pouvez modifier le prompt sans réécrire la commande. Si le prompt contient du texte sensible, excluez ce fichier du contrôle de version.
Effectuer le même appel en Python
La version Python garde le corps JSON identique octet pour octet. Seul le mode de transmission change. L'utilisation de requests ajoute une dépendance, mais rend le code lisible ; cela vaut la peine de l'installer pour tout usage qui dépasse un simple script jetable.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "Une prairie alpine ensoleillée à l'heure dorée, des fleurs sauvages au premier plan, mise au point nette",
"size": "1024x1024",
"n": 1,
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
print(response.status_code)
response.raise_for_status()
data = response.json()
print(data)
Pourquoi utiliser json=payload plutôt que data=json.dumps(payload) : passer le dict au paramètre nommé json le sérialise et définit automatiquement l'en-tête Content-Type. Passer une chaîne à data fonctionne aussi, mais il est facile d'oublier de définir l'en-tête, ce qui se manifestera ensuite par une erreur de validation déroutante.
Si vous préférez la bibliothèque standard
Pour éviter une dépendance, vous pouvez utiliser urllib.request de la bibliothèque standard. Le dictionnaire de charge utile reste identique :
import json, os, urllib.request
payload = {
"model": "gpt-image-2.6-sunburst/text-to-image",
"prompt": "Une prairie alpine ensoleillée à l'heure dorée, des fleurs sauvages au premier plan, mise au point nette",
}
request = urllib.request.Request(
"https://api.hiapi.ai/v1/images/generations",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
},
data=json.dumps(payload).encode("utf-8"),
)
with urllib.request.urlopen(request, timeout=120) as response:
data = json.loads(response.read().decode("utf-8"))
Dans les deux cas, la génération d'image est plus lente qu'un appel d'API JSON classique. Réglez un délai d'attente généreux, sinon vous risquez d'expirer sur une requête sur le point d'aboutir et de la payer deux fois en la relançant.
Traiter la réponse et enregistrer l'image
Une réponse réussie est du JSON. La sortie image arrive généralement sous forme d'URL (que vous devez récupérer séparément) ou de contenu d'image encodé dans la charge utile. Consultez la documentation du point de terminaison pour savoir quelle forme s'applique, puis traitez les deux formes de manière défensive, car la forme exacte peut varier selon les paramètres.
Lire la structure de la réponse
La réponse est un objet JSON contenant la sortie générée et des métadonnées. Avant d'écrire le code d'analyse, inspectez-la une fois de manière interactive :
print(json.dumps(data, indent=2)[:2000])
Repérez où se trouve l'image. Si vous voyez un champ URL, téléchargez-la. Si vous voyez du contenu base64, décodez-le. Évitez de supposer qu'une URL reste valide indéfiniment — considérez-la comme de courte durée et copiez immédiatement les octets dans votre propre stockage.
Enregistrer un résultat basé sur une URL
image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
Enregistrer un résultat encodé
import base64
encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
with open("output.png", "wb") as f:
f.write(base64.b64decode(encoded))
Dans une charge de travail réelle, utilisez un nom de fichier différent à chaque appel — horodatage, ID de requête ou slug dérivé du prompt. Si vous prévoyez de régénérer ou d'auditer les sorties plus tard, conservez le prompt avec l'image dans un fichier JSON sidecar.
Traiter la réponse de succès à un seul endroit
Encapsulez l'analyse de la réponse dans une fonction qui renvoie une liste de chaînes d'octets, une par image. Chaque appelant n'a plus qu'à écrire ou téléverser les octets, sans savoir s'ils proviennent d'une URL ou d'un contenu encodé. Cette abstraction sera payante lorsque vous changerez de modèle plus tard.
Diagnostiquer les erreurs courantes
La plupart des échecs lors d'une première intégration relèvent de quelques catégories. Avant de modifier quoi que ce soit d'autre, associez le code de statut et le message à la correction ci-dessous.
Échecs d'authentification
Une requête rejetée pour identifiants manquants ou invalides signifie que l'en-tête Authorization est absent, mal formé ou porte une clé révoquée. Vérifiez dans cet ordre :
- Confirmez le nom de l'en-tête et le format de sa valeur, y compris le mot littéral
Bearersuivi d'un espace. - Confirmez que la variable d'environnement est bien renseignée dans le shell ou le processus qui exécute l'appel — une clé définie dans un terminal n'existe pas dans un autre.
- Confirmez que la clé n'a pas été renouvelée ni tronquée lors de la copie.
Erreurs de validation du corps de requête
L'API rejette les corps de requête auxquels il manque des champs obligatoires ou qui contiennent des valeurs invalides. Le message indique généralement le champ en cause :
- model ou prompt manquant — les deux sont obligatoires. Envoyez-les explicitement à chaque appel plutôt que de compter sur des valeurs par défaut.
- Modèle inconnu — vérifiez à nouveau l'identifiant
gpt-image-2.6-sunburst/text-to-image, y compris la barre oblique et la casse. N'insérez pas de caractères blancs autour. - Dimensions invalides — utilisez une chaîne de dimensions prise en charge au format indiqué par la documentation. Si vous omettez volontairement size, retirez-le plutôt que d'envoyer
null. - JSON mal formé — souvent un problème de guillemets du shell avec curl, ou d'encodage de chaîne en Python. Validez avec
json.dumps(payload)avant l'envoi et vérifiez ce qui est réellement transmis.
Limitation de débit et quotas
Si vous recevez une réponse de limitation, attendez avant de réessayer, avec un délai aléatoire (jitter), plutôt que de relancer immédiatement. Si le message indique un problème de quota, consultez l'offre et le tableau de bord d'utilisation de votre compte plutôt que le corps de la requête — la charge utile est probablement correcte.
Erreurs serveur
Les 5xx pendant la génération sont généralement temporaires. Réessayez une ou deux fois avec un délai exponentiel. Si l'erreur persiste avec des prompts et des charges utiles différents, le problème ne vient pas de vous ; capturez le corps de la réponse et contactez le support en fournissant l'heure de la requête et l'identifiant de modèle.
Erreur de type de contenu
Envoyer un corps de requête sans définir Content-Type: application/json peut produire des erreurs de validation déroutantes, car le serveur ne parvient pas à analyser la charge utile. En curl, définissez explicitement l'en-tête ; en Python, laissez le paramètre json= s'en charger.
Rendre l'intégration prête pour la production
Le premier appel réussi est la partie facile. Les ajustements suivants permettent à l'intégration de rester peu coûteuse, tant en exécution qu'en modifications.
Rendre l'identifiant de modèle configurable
Stockez l'identifiant de modèle dans une constante ou une valeur de configuration pilotée par l'environnement, jamais en ligne à plusieurs points d'appel. Lorsque vous évaluerez d'autres modèles plus tard, il suffira de changer une valeur et de relancer les tests. Conservez dans les journaux les champs de chaque requête et notez quel modèle a généré chaque image, afin de pouvoir comparer la qualité lors d'un changement de modèle sans tout relancer.
Réessayer avec stratégie
Réessayez les erreurs réseau, les expirations de délai et les réponses 5xx avec un délai exponentiel et du jitter. Ne réessayez jamais les erreurs de validation ou d'authentification — la requête échouera de la même manière et vous ne ferez que consommer votre limite de débit. Limitez le nombre de tentatives et consignez le numéro de chaque tentative ainsi que le statut final.
Choisir un délai d'attente adapté à la charge de travail
La génération d'image est lente. Un délai trop court fait échouer des requêtes qui auraient pu aboutir et, si vous relancez, vous risquez de payer une génération déjà effectuée. Réglez un délai par requête généreux et traitez les dépassements au-delà d'un seuil comme un signal à examiner sur la latence, non comme une raison de relancer agressivement.
Structurer le client en couches
Gardez trois parties distinctes : un constructeur de charge utile qui transforme les entrées de l'application en dictionnaire de requête ; une fonction de transport qui effectue l'appel HTTP ; un gestionnaire qui décode la réponse en octets. Tester le constructeur sans appel réseau est très simple ; remplacer le transport par un mock l'est tout autant. Cette séparation fait aussi d'un changement de modèle la modification d'un seul fichier, plutôt qu'une chasse à travers toute la base de code.
Journaliser les informations utiles lors d'un incident
Consignez l'horodatage, le point de terminaison, l'identifiant de modèle, le statut HTTP, une forme hachée ou tronquée du prompt et la durée de la requête. Ne journalisez jamais les clés API ni les en-têtes complets. Si vous stockez les images générées, organisez les chemins de stockage par ID de requête afin qu'un ticket de support puisse être rattaché à l'appel réel.
Avec une authentification gérée par variables d'environnement et une charge utile isolée dans une fonction constructeur, le modèle que vous avez pratiqué avec gpt-image-2.6-sunburst/text-to-image se transpose directement à tout autre modèle d'image du même point de terminaison HiAPI.
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