Comment appeler gpt-image-2.5-sunburst/text-to-image via l'API HiAPI : curl et Python

Ce que ce point de terminaison de modèle vous apporte

gpt-image-2.5-sunburst/text-to-image est un modèle de génération d'images exposé via l'API unifiée HiAPI. Vous l'appelez par son ID de modèle, vous envoyez votre prompt dans un corps de requête de forme chat-completions identique à celui des modèles texte, puis vous récupérez les données d'image générées dans la réponse.

Conséquence pratique : si votre base de code passe déjà par HiAPI pour le texte, vous n'avez pas besoin d'un second SDK, d'un schéma d'authentification distinct, ni d'apprendre une nouvelle famille de points de terminaison. Seul l'ID de modèle change.

Choisissez ce point de terminaison lorsque votre tâche est la génération d'image à partir d'un prompt — créer une nouvelle image à partir d'une description textuelle, éventuellement guidée par une image de référence fournie dans la requête. Si vous devez analyser ou décrire une image existante plutôt que d'en générer une, un modèle de chat doté de capacités visuelles conviendra mieux ; réservez la génération d'images à ce point de terminaison et placez la compréhension d'images ailleurs.

Une attente à fixer dès maintenant : les appels d'image sont plus lents que les complétions texte. Des temps de réponse de l'ordre de quelques secondes sont normaux ; le délai d'attente de votre client doit être ajusté à cette réalité, et non hérité d'une configuration purement texte.

Avant d'envoyer la première requête

Trois éléments sont nécessaires.

Une clé API

Créez une clé dans votre compte HiAPI et stockez-la dans une variable d'environnement plutôt que dans le code source :

export HIAPI_API_KEY="your-key-here"

L'ID de modèle exact

La chaîne est gpt-image-2.5-sunburst/text-to-image. Traitez-la comme un identifiant opaque — copiez-la, ne la retapez pas de mémoire. La barre oblique fait partie de l'ID. Une faute de frappe ici est la cause la plus fréquente d'un premier appel échoué, et elle se manifeste par une erreur du type modèle introuvable, et non par un problème de payload.

Un client capable d'envoyer des requêtes HTTPS

Pour une première validation, curl suffit ; il est préinstallé sur la plupart des systèmes. Pour le code applicatif, Python avec la bibliothèque requests (ou n'importe quel client HTTP) fera l'affaire. Ce point de terminaison n'exige aucune bibliothèque d'image spécifique côté client ; vous envoyez simplement du JSON et lisez du JSON en retour.

Vous n'avez pas besoin de précharger des images ni de configurer du stockage avant le premier appel en texte seul. Commencez par la requête minimale ci-dessous et n'ajoutez des images de référence qu'une fois l'aller-retour de base fonctionnel.

Une requête minimale fonctionnelle avec curl

Voici l'appel minimal correct :

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

Champ par champ :

• URL — le chemin chat-completions standard de HiAPI. Les modèles d'image utilisent le même routage que les modèles texte.
• Authorization — le jeton bearer avec la clé API. Si cet en-tête est mal formé, vous recevez un 401 avant même l'appel au modèle.
• Content-Type — doit être application/json.
• model — l'ID de modèle exact de la section précédente.
• messages — le tableau standard d'objets role/content. Votre prompt est le content du message user.

En cas de succès, vous recevez une réponse JSON contenant les données d'image générées ainsi que les métadonnées habituelles de complétion. Enregistrez d'abord la réponse brute dans un fichier, inspectez-la, puis branchez la logique d'analyse dans votre script :

curl -sS ... -o response.json

Dès que cela renvoie une image, vos identifiants et la forme de votre payload sont corrects ; tous les problèmes ultérieurs relèveront de la logique applicative, et non de la configuration.

Écrire la même requête en Python

Le contrat de requête reste inchangé — seuls la configuration du client, les délais d'attente et le traitement de la réponse changent.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

response.raise_for_status()
data = response.json()
print(data)

Trois détails méritent attention :

Le délai d'attente est explicite et asymétrique

Le tuple (10, 180) définit un délai de connexion court et un délai de lecture plus généreux. La génération d'images prend naturellement du temps ; un délai unique et plat copié depuis un client texte produira de faux échecs. Gardez le délai de connexion court pour que les problèmes réseau échouent rapidement.

Utilisez json=payload plutôt que data=

Passer un dictionnaire via json= gère la sérialisation pour vous et définit le type de contenu. Si vous passez une chaîne déjà sérialisée via data=, définissez l'en-tête manuellement.

Analyse défensive

La réponse est du JSON ; avant d'indexer, journalisez le corps complet de la réponse en cas de forme inattendue. N'assumez pas une profondeur d'imbrication fixe avant d'avoir vu une vraie réponse — et ne supposez jamais une forme de succès pour un statut non 2xx.

Si vous préférez une bibliothèque client configurée pour HiAPI, le payload envoyé est identique ; seul l'emplacement de l'appel change.

Transmettre correctement une image de référence

L'image de référence doit être fournie à l'intérieur du contenu du message, et non comme un champ ad hoc de premier niveau. C'est la partie de l'intégration la plus facile à fausser subtilement, car une référence mal formée ne produit souvent aucune erreur — la requête réussit simplement et la sortie ignore votre image.

Gardez la structure du payload cohérente entre les langages : le message user porte un tableau de contenu où la partie texte contient le prompt et la partie image porte les données de référence. Le même corps de requête JSON que vous construisez en Python doit pouvoir s'exprimer octet pour octet en curl ; si vous ne parvenez pas à écrire l'équivalent curl de votre payload Python, la structure a dérivé.

Lorsque le résultat semble ignorer votre image de référence, vérifiez dans cet ordre :

1. L'emplacement. La partie image est-elle bien dans messages[].content, ou a-t-elle fui au niveau supérieur du corps de la requête ? Le modèle ne voit que ce qui se trouve dans les messages.
2. L'encodage. L'image de référence est transmise dans la requête sous forme de données encodées. Vérifiez que les données sont complètes et correctement formatées, et non tronquées par une concaténation manuelle ou un copier-coller approximatif.
3. Le couplage avec le prompt. L'image de référence guide la génération ; elle ne remplace pas les instructions. Indiquez explicitement le rôle de l'image — style, composition, sujet — au lieu de supposer que le modèle le déduira.
4. La taille. Une référence très volumineuse gonfle la requête et ralentit l'aller-retour. Réduisez-la avant l'encodage à la dimension réellement nécessaire à la tâche.

Une habitude de débogage utile

Construisez une fois un payload avec image de référence, enregistrez le corps JSON exact qui fonctionne et réutilisez-le comme échantillon de référence. Lorsqu'un appel ultérieur se comporte anormalement, différez le corps actuel avec l'échantillon de référence. La plupart des régressions liées aux images de référence sont structurelles et un diff les révèle en quelques secondes.

Gérer les erreurs, les délais d'attente et les tentatives

Les points de terminaison d'image échouent différemment des points de terminaison texte : ils sont plus lents, donc davantage d'appels tombent dans la fenêtre déclenchée par les délais d'attente, et réessayer aveuglément coûte plus cher car le travail est plus lourd.

Distinguer les erreurs client des échecs transitoires

• 4xx (sauf 429) — payload mal formé, ID de modèle erroné, authentification manquante. Réessayer la même requête échouera de la même façon. Corrigez la requête.
• 401/403 — problème d'identifiants. Vérifiez la clé et le format de l'en-tête Authorization.
• 429 — limitation de débit. Réessayez, mais avec un backoff et du jitter, pas immédiatement.
• 5xx et erreurs de connexion — transitoires. Réessayez.
• Délai de lecture dépassé — ambigu : la génération a peut-être abouti côté serveur. Ne considérez le délai comme réessayable que si votre flux de travail tolère d'éventuels doublons.

Ne réessayez que ce qui est sûr

Utilisez un backoff exponentiel avec jitter et fixez une petite limite au nombre de tentatives — trois suffisent généralement. Un schéma simple :

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

Ne réessayez pas les erreurs de payload 4xx dans cette boucle — exposez-les immédiatement, pour que les mauvaises requêtes échouent bruyamment au lieu de gaspiller des tentatives.

Dimensionner les délais d'attente selon le modèle

Le délai de lecture défini pour les appels d'image doit être plusieurs fois supérieur à la valeur par défaut du texte, et défini par appel plutôt que globalement, afin que le trafic texte ne soit pas pénalisé. Si votre plateforme impose une limite stricte de requêtes, gardez les prompts de génération et les images de référence dans un budget que vous pouvez réellement tenir.

Liste de vérification de production avant publication

Une courte liste qui prévient la plupart des incidents :

• L'ID de modèle à un seul endroit. Définissez gpt-image-2.5-sunburst/text-to-image comme constante ou valeur de configuration, et non comme littéraux de chaîne dispersés.
• La clé issue de variables d'environnement, jamais commitée. Faites-la tourner comme n'importe quel autre secret.
• Des délais d'attente explicites, avec une fenêtre de lecture généreuse, définis sur la requête et non sur les valeurs par défaut de session.
• Des tentatives uniquement sur 429/5xx/délais dépassés, avec backoff et jitter, et un nombre de tentatives limité.
• Journaliser la réponse complète en cas d'échec — statut, corps de réponse et ID de requête avant l'analyse, pour que le dialogue de support parte de preuves.
• Conserver des échantillons de payload fonctionnels, couvrant le cas ordinaire et le cas avec image de référence, à utiliser en diff lorsque le comportement change.
• Les images de référence à l'intérieur du contenu du message, réduites selon la tâche, avec leur rôle précisé dans le prompt.
• Un smoke test en CI qui effectue un vrai appel sur l'ID de modèle, pour qu'un modèle renommé ou retiré se manifeste avant les utilisateurs.

Aucune de ces habitudes n'est propre à la génération d'images, mais chacune cible un mode de défaillance que les appels d'image rencontrent plus souvent que les appels texte. Configurez-les une fois pour toutes et le point de terminaison se comportera comme n'importe quelle autre partie de votre stack. Pour les paramètres et limites actuels du modèle, consultez la page du modèle sur HiAPI avant de finaliser la configuration.