Blog

Tutoriel

Comment appeler gpt-image-2.6-flare/text-to-image via l'API HiAPI : curl, Python et requêtes exécutables

Nov 10, 2026
Illustration de couverture abstraite composée de feuilles de verre translucides superposées faisant glisser un champ pâle vers des bandes bleu froid, aspect mat et architectural, sans texte.
Sur cette page

Ce que construit ce tutoriel

La plupart des tutoriels de génération d'images à partir de texte s'arrêtent à une capture d'écran d'une réponse réussie. Cela ne suffit pas pour mettre quoi que ce soit en production. Ce tutoriel vous guide de zéro jusqu'à une intégration réutilisable et opérationnelle via l'API unifiée HiAPI et le modèle gpt-image-2.6-flare/text-to-image.

À la fin, vous disposerez de trois choses :

  • Une requête confirmée fonctionnelle, d'abord présentée sous forme de commande curl, puis sous forme de script Python équivalent.
  • Un modèle mental clair de la façon dont HiAPI organise les appels de génération d'images à partir de texte — chemin du point de terminaison, en-têtes d'authentification, charge utile du prompt et corps de la réponse — afin que vous puissiez adapter les exemples à vos propres prompts plutôt que de les mémoriser.
  • Des modèles pour étendre cet appel unique au traitement par lots, ainsi qu'une méthode pour déterminer quels échecs doivent être réessayés et lesquels doivent être corrigés.

Nous garderons le code concis avec un minimum de dépendances. L'exemple Python n'utilise que la bibliothèque standard, vous pouvez donc l'exécuter dans tout environnement disposant de Python ; une fois la structure de la requête maîtrisée, adaptez-le à requests ou à un client asynchrone. Si vous souhaitez aller directement à l'appel exécutable, sautez à la section curl puis revenez lire les explications.

Prérequis et identifiants

Avant le premier appel, vérifiez que vous disposez des éléments suivants :

  1. Un compte HiAPI. Connectez-vous au tableau de bord pour générer et gérer vos identifiants.
  2. Une clé API. Créez-en une dans la section des clés API du tableau de bord. Traitez-la comme un mot de passe : elle autorise chaque requête facturée sur votre compte.
  3. Un moyen d'envoyer des requêtes HTTP. Soit un shell avec curl installé, soit Python 3 avec sa bibliothèque standard (urllib et json sont fournis avec Python).

Gérer la clé via des variables d'environnement

Ne collez jamais la clé directement dans un fichier source susceptible d'être commité. Exportez-la plutôt dans votre shell :

export HIAPI_API_KEY="your-api-key-here"

Sous Windows PowerShell, utilisez $env:HIAPI_API_KEY = "your-api-key-here". Dans un CI, injectez-la comme secret. Dans un service de longue durée, chargez-la au démarrage depuis un gestionnaire de secrets.

Savoir où se trouve l'URL de base

HiAPI expose une surface d'API unifiée unique, l'URL de base reste donc stable entre les modèles. Conservez-la dans une valeur de configuration — une variable d'environnement convient parfaitement — plutôt que de la disperser dans le code. Ainsi, basculer entre préproduction et production, ou faire pointer les tests vers un serveur mock, ne nécessite qu'une seule ligne à changer.

L'identifiant du modèle que vous allez appeler est gpt-image-2.6-flare/text-to-image. Notez qu'il contient une barre oblique ; conservez l'identifiant intact et placez-le à l'emplacement de chemin attendu par votre constructeur de requête, exactement comme dans les exemples ci-dessous.

La clé étant exportée et l'URL de base notée, vous pouvez examiner la requête elle-même.

Anatomie d'une requête de génération d'images à partir de texte

Chaque appel de génération d'images HiAPI comporte les mêmes quatre composants. Une fois qu'ils sont compris, changer de modèle ou de prompt devient mécanique.

1. Le chemin du point de terminaison

La requête utilise l'identifiant du modèle comme une partie du chemin : gpt-image-2.6-flare/text-to-image, ajouté après votre URL de base. C'est l'adresse qui route votre appel vers le bon modèle derrière l'interface unifiée.

2. L'en-tête d'authentification

L'authentification se fait via un jeton bearer dans l'en-tête Authorization :

Authorization: Bearer $HIAPI_API_KEY

Chaque requête doit inclure cet en-tête. Son absence ou un format incorrect est la cause la plus fréquente d'échec lors du premier appel.

3. Le corps de la requête

Un appel de génération d'images à partir de texte est un POST avec un corps JSON. Le cœur est le prompt — votre description en langage naturel de l'image souhaitée. Le corps transporte également les paramètres de génération. HiAPI normalisant la structure des requêtes entre les modèles, vous pouvez réutiliser votre constructeur de requête et ne changer l'identifiant du modèle que lorsque vous voulez comparer des sorties.

4. Le corps de la réponse

Une réponse réussie renvoie l'image générée (ou une référence vers celle-ci) ainsi que des métadonnées sur la génération. Votre client doit vérifier le statut HTTP avant de tenter d'analyser l'image. Traitez la réponse comme des données, pas comme quelque chose à inspecter visuellement — pour l'automatisation, vous avez besoin des octets ou de l'URL de l'image, et vous devez stocker tout identifiant de requête avec eux afin d'associer le fichier à l'appel qui l'a produit.

C'est tout le modèle. Le reste n'est que des instanciations concrètes de ces quatre parties.

Lancer une requête exécutable avec curl

Voici l'appel complet. Remplacez le prompt par votre propre texte et exécutez :

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
  }' \
  --output response.json

Ligne par ligne :

  • -X POST — la génération est un appel qui change l'état, donc on utilise POST.
  • L'URL — l'URL de base issue de la variable d'environnement, suivie de l'identifiant du modèle et de /text-to-image. Les guillemets évitent que le shell interprète mal des caractères spéciaux.
  • Authorization: Bearer ... — les identifiants. La forme $HIAPI_API_KEY évite que la clé littérale n'apparaisse dans l'historique du shell.
  • Content-Type: application/json — indique au serveur d'analyser le corps comme du JSON. L'omettre est une cause fréquente d'erreurs 4xx déroutantes.
  • -d '{...}' — la charge utile JSON. Le champ prompt est celui que vous modifiez le plus souvent ; ajoutez-y les paramètres de génération pour affiner la sortie.
  • --output response.json — écrit le corps de la réponse dans un fichier, afin qu'une charge utile d'image binaire ne submerge pas le terminal. Ouvrez-le, ou si la réponse est encodée en JSON, traitez-le avec jq.

Vérification rapide

Si la commande renvoie rapidement et que response.json n'est pas vide, vous disposez d'une intégration fonctionnelle. Si vous obtenez plutôt un 4xx, examinez le corps de la réponse — HiAPI renvoie des erreurs descriptives, et la section sur la gestion des erreurs ci-dessous couvre les suspects habituels.

Une fois cela fonctionnel, enregistrez la commande dans un script shell à côté de votre projet. C'est le moyen le plus rapide de tester un changement d'identifiants ou de confirmer si une panne vient de votre côté.

Lancer la même requête en Python

L'appel curl se transpose directement en Python. Ce script n'utilise que la bibliothèque standard, lit la clé depuis les variables d'environnement et écrit la réponse image sur le disque :

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"

def generate_image(prompt: str, settings: dict | None = None) -> bytes:
    payload = {"prompt": prompt}
    if settings:
        payload.update(settings)

    request = urllib.request.Request(
        f"{BASE_URL}/{MODEL}",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            return response.read()
    except urllib.error.HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc

if __name__ == "__main__":
    body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
    with open("output.bin", "wb") as f:
        f.write(body)
    print(f"wrote {len(body)} bytes")

Quelques choix délibérés :

  • Un délai d'expiration généreux. La génération d'images est plus lente que la complétion de texte ; une limite de 120 secondes évite de rester bloqué indéfiniment tout en tolérant des appels lents mais réussis.
  • La fonction renvoie des octets, pas un chemin. Cela la rend réutilisable — vous pouvez téléverser les octets vers un stockage objet ou les renvoyer depuis un gestionnaire web.
  • Les erreurs sont encapsulées avec le corps de la réponse. En cas d'erreur, le message vous indique ce que le serveur a dit, pas seulement le code de statut.
  • Le constructeur de charge utile accepte des paramètres optionnels. Lorsque vous ajoutez des paramètres de génération, étendez le dictionnaire settings plutôt que de les coder en dur dans la fonction.

Après avoir exporté les deux variables d'environnement, exécutez-le avec python generate.py. Si vous préférez requests, remplacez la construction de la requête par requests.post(url, json=payload, headers=headers) ; la structure est identique.

Modèles de traitement par lots et de concurrence

Un prompt est une démonstration ; plusieurs prompts constituent un travail. Cette transition introduit deux problèmes : le débit et la capacité de débogage.

Itérer sur des prompts depuis un fichier

Placez les prompts dans un fichier séparé par des sauts de ligne ou dans un tableau JSON. Attribuez un ID à chaque prompt (slug, index ou hachage) et nommez le fichier de sortie avec cet ID. Lorsqu'un lot de centaines d'images est terminé, vous pouvez associer chaque fichier à son prompt sans deviner.

prompts = [
    ("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
    ("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
    body = generate_image(text)
    with open(f"out/{prompt_id}.bin", "wb") as f:
        f.write(body)

Contrôler explicitement la concurrence

Les appels de génération sont gourmands en E/S, la concurrence aide donc au débit — mais une concurrence non bornée déclenche des limitations de débit et vous enlise dans les erreurs. Commencez en série, mesurez la durée d'un appel unique, puis augmentez la concurrence avec un pool de travailleurs borné. Un simple pool de threads avec un petit nombre fixe de threads de travail (quatre à huit pour commencer) suffit généralement.

Pour des tâches plus importantes, utilisez un client asynchrone ou une file d'attente avec des threads de travail. La discipline clé reste la même : parallélisme borné, un fichier de sortie par ID de prompt, une ligne de journal par requête enregistrant l'ID, le statut et la durée.

Conserver un manifeste

Écrivez un petit manifeste JSON pendant l'exécution du lot, enregistrant chaque ID de prompt et son résultat. Si le processus meurt en cours de route, le manifeste vous indique où reprendre plutôt que de refacturer tout le lot. Cette pratique fait gagner plus de temps que n'importe quelle optimisation astucieuse.

Gérer les erreurs et les tentatives

Les échecs se divisent en deux catégories : ceux que vous corrigez et ceux que vous réessayez. Les confondre fait perdre du temps et, dans une tempête de tentatives, de l'argent.

À corriger

  • 401 / 403 — authentification. Clé manquante, expirée ou sans droits d'accès. Vérifiez que HIAPI_API_KEY est bien exportée dans le shell qui exécute la commande — le piège courant est de l'exporter dans un terminal et d'exécuter le script dans un autre.
  • 400 — charge utile mal formée. JSON invalide, prompt manquant ou types de champs inattendus. Le corps de l'erreur indique généralement le champ problématique. Faites attention au quoting de votre JSON dans l'appel curl.
  • 404 — chemin incorrect. Vérifiez que l'identifiant du modèle est orthographié exactement comme dans la documentation et que votre URL de base ne contient pas de segment de chemin dupliqué ou manquant.

À réessayer, avec backoff

  • 429 — débit limité. Ralentissez. Respectez toute indication retry-after présente dans la réponse et utilisez un backoff exponentiel avec gigue. À long terme, limitez votre concurrence.
  • 5xx — erreur serveur. Généralement temporaire. Réessayez un nombre limité de fois (trois est une valeur par défaut raisonnable), avec un délai croissant, puis échouez bruyamment.

Un wrapper de nouvelle tentative minimal

import random, time

def with_retries(fn, attempts=3):
    for i in range(attempts):
        try:
            return fn()
        except RuntimeError as exc:
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.uniform(0, 0.5))

Utilisez-le pour envelopper generate_image. L'essentiel est de rendre l'opération idempotente de votre côté : comme les fichiers de sortie sont indexés par ID de prompt, une nouvelle tentative écrase au lieu de dupliquer. Journalisez chaque échec avec l'ID de prompt et le message du serveur — lorsque vous devrez vraiment escalader, ce journal est exactement ce dont l'équipe de support a besoin pour reproduire le problème.

Prochaines étapes

Vous disposez maintenant d'une requête fonctionnelle, d'une fonction Python qui vaut la peine d'être conservée, et de modèles pour l'exécuter à grande échelle. Pour durcir en production, ajoutez une journalisation structurée avec des ID de requête, persistez le manifeste dans un stockage durable afin que les tâches par lots puissent reprendre après un crash, et validez les prompts avant l'envoi afin que les entrées mal formées échouent rapidement et à moindre coût.

L'étape suivante la plus utile est de réutiliser ce même client exact sur d'autres modèles de l'API HiAPI. Comme le chemin du point de terminaison, les en-têtes d'authentification et la structure de la charge utile sont partagés, adapter le script à un nouveau modèle signifie généralement changer l'identifiant du modèle, et occasionnellement un ou deux paramètres — un petit changement de code qui produit des sorties significativement différentes.

Commencez par un prompt, confirmez la génération du fichier, puis laissez le runner de traitement par lots s'occuper du reste.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API