Tutoriel

Comment utiliser l'API GPT Image 2 : guide de génération d'images à partir de texte et à partir d'images

Nov 3, 2026

Ce que l'API GPT Image 2 apporte aux développeurs

L'API GPT Image 2 vous fournit une interface unifiée et cohérente pour générer des images à partir de prompts. Plutôt que d'assembler plusieurs fournisseurs ou de maintenir plusieurs SDK, vous envoyez une seule requête HTTP à HiAPI.ai et récupérez les données d'image. Cela compte lorsque vous construisez des fonctionnalités comme des générateurs de supports marketing, des illustrations d'accueil dans une application ou des outils créatifs destinés aux utilisateurs, car la latence, la disponibilité et une structure de requête prévisible sont essentielles.

Vous utiliserez deux modes de génération :

Texte vers image : vous fournissez un prompt et une taille cible, et le modèle génère l'image à partir de zéro.
Image vers image : vous fournissez un prompt plus une ou plusieurs images de référence, et le modèle génère l'image en s'appuyant sur ces références.

Les deux modes partagent la même authentification et la même structure de réponse, donc une fois que vous disposez d'un appel fonctionnel, le second ne représente qu'une modification mineure plutôt qu'une intégration entièrement nouvelle. Ce guide couvre, dans l'ordre : comment choisir entre les deux variantes, une requête curl minimale, le traitement des images de référence, la demande de sortie 4K, le portage en Python, et les schémas de gestion d'erreurs qui évitent les échecs silencieux dans un pipeline de production d'images.

Si vous construisez une fonctionnalité qui a besoin de la génération d'images via un contrat d'API stable, le reste de cet article est le chemin le plus court d'un point de départ à une requête opérationnelle.

Texte vers image ou image vers image : choisir la variante

Avant d'écrire du code, déterminez quelle variante votre produit a réellement besoin. Ce choix dépend principalement du niveau de contrôle que vous souhaitez sur la sortie et de la quantité de contenu que vos utilisateurs s'attendent à fournir.

Quand utiliser texte vers image

Texte vers image est le choix par défaut approprié dans les cas suivants :

L'utilisateur décrit en texte ce qu'il veut, sans fournir de source.
Vous générez des images de remplacement, des visuels principaux ou des variantes à partir de modèles de prompts fixes.
Vous voulez le corps de requête le plus simple possible — un prompt et une taille — pour garder la requête légère et la latence prévisible.

Quand utiliser image vers image

Image vers image est le bon choix lorsque la sortie doit rester proche de quelque chose qui existe déjà :

Restyler ou réinterpréter une photo de produit téléversée.
Appliquer un traitement visuel cohérent à un ensemble de références.
Guider la composition, la palette de couleurs ou le sujet afin que le résultat corresponde à une marque ou à un scénario existant.

Règle pratique

Si le prompt seul détermine entièrement la sortie, utilisez texte vers image. Si une partie de l'intention réside dans l'image plutôt que dans le texte — et que la décrire par un prompt serait préjudiciable, verbeux ou peu fiable — utilisez image vers image en passant une image de référence.

Une erreur courante consiste à recourir à image vers image alors qu'un meilleur prompt suffirait. Les images de référence ajoutent une surcharge de téléversement et augmentent les risques d'échec de validation de la requête. Commencez par texte vers image et ne passez à la variante avec référence que lorsque vous pouvez identifier un attribut visuel précis que le prompt ne peut pas capturer.

Envoyer votre première requête texte vers image avec curl

Commencez par curl. Il élimine la variable du comportement du SDK, ainsi, en cas d'échec, vous savez que le problème vient de l'authentification ou de la structure du corps de requête, et non de la bibliothèque cliente.

Définissez d'abord la clé d'API comme variable d'environnement, afin qu'elle n'apparaisse ni dans l'historique du shell ni dans le contrôle de version :

export HIAPI_API_KEY="your_api_key_here"

Envoyez ensuite une requête minimale :

curl -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",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

Points à vérifier dans la réponse :

Code de statut HTTP. 200 signifie que la requête a été acceptée et traitée. Pour tout autre code, lisez d'abord le corps de la réponse d'erreur avant de modifier quoi que ce soit.
Authentification. 401 indique presque toujours une clé absente, mal formée ou expirée — vérifiez que l'en-tête Authorization est au format Bearer suivi de la clé.
Corps de requête. 400 pointe généralement vers un champ précis : faute de frappe dans un paramètre, chaîne de taille non acceptée par le modèle, ou prompt ne passant pas la validation.
Charge utile de l'image. Selon le mode de réponse, vous obtenez une URL récupérable ou des données d'image en base64. Gérez les deux, afin que votre client ne soit pas pris au dépourvu plus tard.

Une fois cet appel réussi, vous avez validé trois choses : la clé est valide, le chemin du point de terminaison est correct et la structure JSON est acceptée. Chaque modification ultérieure de ce guide part de cette base de référence fiable.

Guider la sortie avec des images de référence

Une requête image vers image conserve la même enveloppe que texte vers image et ajoute une entrée d'image de référence. Le prompt porte toujours les instructions — l'image de référence porte le contexte visuel.

Le changement dans le corps de requête est que vous fournissez désormais des données d'image en plus du prompt. Concrètement, cela signifie fournir soit une URL récupérable par le service, soit une image encodée en base64 en ligne, selon ce que votre intégration prend en charge. Gardez les règles suivantes en tête :

Le prompt et l'image de référence doivent concorder. Si le prompt décrit un produit rouge alors que la référence est bleue, le modèle reçoit des signaux contradictoires. Rédigez le prompt comme une instruction à propos de la référence (« retravaille cette scène en aquarelle douce »), et non comme une description qui la contredit.
N'envoyez que ce dont vous avez besoin. Une référence forte vaut généralement mieux que plusieurs références faibles. Plusieurs références augmentent le volume téléversé et rendent plus difficile de savoir laquelle a guidé la sortie.
Surveillez le volume de la requête. Les images encodées en base64 gonflent considérablement la charge utile. Si vous téléversez de grandes photos, c'est le premier endroit à examiner si la requête ralentit ou est rejetée.
Validez avant d'envoyer. Vérifiez que l'image est dans un format pris en charge et qu'elle se décode correctement. Une chaîne base64 mal formée produit des échecs difficiles à comprendre et longs à diagnostiquer.

La structure de requête utilisable est la suivante :

curl -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",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

Comme l'enveloppe de la requête ne change pas, l'appel curl que vous avez validé reste votre outil de débogage : remplacez le corps, conservez les en-têtes, comparez la réponse champ par champ.

Demander une sortie 4K

La résolution de sortie se spécifie dans la requête, plutôt que d'être supposée par le modèle. Si vous avez besoin d'une sortie haute résolution, indiquez-la explicitement via le paramètre size — ne comptez pas sur une valeur par défaut élevée.

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

Lorsque vous passez à une résolution supérieure, plusieurs points doivent être vérifiés :

Chaînes de taille prises en charge. Les valeurs de taille sont validées selon la plage acceptée par le modèle. Une taille refusée renvoie 400, sans dégradation silencieuse — vérifiez donc la chaîne exacte requise plutôt que de deviner une valeur proche mais erronée.
Volume de la réponse. Les données d'image 4K sont bien plus volumineuses que celles d'un résultat 1K. Si votre réponse contient du base64 ou une URL que vous téléchargez immédiatement, prévoyez ce budget dans la mémoire et les délais d'attente.
Latence. La génération à plus haute résolution prend plus de temps. Fixez généreusement les délais d'attente côté client, plutôt que de laisser expirer de votre côté une requête lente mais qui aurait réussi.
Modèle de coût. La facturation dépend de la taille et du nombre de sorties demandées ; faites donc des choix réfléchis : générez à la résolution réellement nécessaire pour la fonctionnalité, et sous-échantillonnez dans votre propre pipeline si l'interface n'a pas besoin de la pleine résolution. Consultez le panneau tarifaire du site pour les prix actuels.
Agrandissez avec prudence. Si vous avez besoin d'une sortie plus grande que ce que produit le modèle, l'agrandissement après génération est une étape distincte, avec ses propres compromis de qualité. Décidez consciemment de la voie à suivre.

Avant d'intégrer le 4K dans des tâches par lots, testez-le avec un prompt fiable, afin que les échecs liés à la résolution ne se confondent pas avec des problèmes d'authentification ou de corps de requête.

Porter la requête en Python

Ne réécrivez pas la requête de zéro en Python. Portez le corps de requête exact que vous avez validé en curl, puis vérifiez séparément le traitement de la réponse.

import os
import base64
import requests

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

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

Remarques sur le portage :

Gardez la clé dans les variables d'environnement, exactement comme avec curl. Ne l'inlinez jamais.
Définissez des délais d'attente explicites. La génération d'images est plus lente qu'un appel d'API JSON classique ; utiliser un délai par défaut trop court est une cause fréquente d'échecs fallacieux.
Gérez les deux modes de réponse. Un traitement conditionnel selon b64_json ou url permet au code de fonctionner quelle que soit la configuration de la réponse.
Réutilisez la fonction. Encapsulez cette logique dans une petite fonction utilitaire generate_image(prompt, size), afin que texte vers image et image vers image ne diffèrent que par le champ image optionnel du payload.

Comme le dictionnaire payload est exactement le même objet que celui testé en curl, tout changement de comportement observé en Python provient presque certainement du côté client — en-têtes, encodage ou délais d'attente — ce qui réduit considérablement le périmètre de débogage.

Gérer les erreurs et valider les réponses

La génération d'images est par nature un appel sujet aux échecs : plus lent que la plupart des points de terminaison d'API, il transporte des charges utiles volumineuses et dépend de la disponibilité du modèle. Traitez-le comme une opération qui échoue parfois et doit être retentée, plutôt que comme une opération ponctuelle.

Liste de vérification de la réponse

Vérifiez le statut avant d'analyser. Appelez raise_for_status() ou vérifiez le code de statut, et lisez le corps de la réponse d'erreur — il indique généralement le champ fautif.
Validez la structure. Vérifiez que data existe et n'est pas vide avant de l'indexer. Ne partez pas du principe que data[0] existe forcément.
Vérifiez les octets de l'image. Après décodage, vérifiez que la sortie n'est pas vide et commence par une signature d'image valide. Un fichier de zéro octet est un échec silencieux qui ne se révèle que bien plus tard.
Enregistrez l'ID de requête. Conservez l'identifiant de requête de la réponse dans les journaux, afin de pouvoir tracer une génération échouée sans la reproduire.

Stratégie de nouvelle tentative

Ne retentez que les échecs temporaires. Les délais d'attente, les réinitialisations de connexion et les réponses 5xx méritent une nouvelle tentative. 401 ou 400 échoueront de la même manière à chaque fois — corrigez la requête plutôt que de la retenter.
Utilisez un backoff exponentiel avec jitter. Commencez par un court délai et augmentez progressivement ; le jitter évite que des groupes de workers retentent en même temps.
Limitez le nombre de tentatives. Deux ou trois tentatives suffisent généralement. Au-delà, exposez l'erreur à l'utilisateur ou basculez la tâche vers un chemin de lettre morte.
Rendez l'opération idempotente. Comme les nouvelles tentatives peuvent produire des générations en double, stockez les résultats associés à l'ID de la tâche d'origine, afin qu'un nouvel essai ne facture jamais deux fois une action visible par l'utilisateur.

Adapter à l'asynchrone

La génération à haute résolution prend du temps ; si votre architecture le permet, n'occupez donc pas le thread de requête pendant ce temps. Placez la tâche dans une file, renvoyez un ID de tâche à l'appelant et laissez un worker exécuter l'appel avec la stratégie de nouvelle tentative décrite ci-dessus. Votre couche web reste ainsi réactive et le travail lent et sujet aux échecs est confiné là où les nouvelles tentatives coûtent peu.

Intégrez ces vérifications dès le premier appel fonctionnel, plutôt qu'après le premier incident de production — le coût d'une petite fonction de validation est bien inférieur à celui de déboguer un fichier image vide trois semaines plus tard. Une fois l'authentification, la structure du corps de requête, la résolution et les nouvelles tentatives vérifiées, l'API GPT Image 2 devient un bloc de construction fiable, et non une intégration réservée aux démonstrations.