Tutoriel
Comment appeler gpt-image-2.6-flare/image-to-image via l'API HiAPI : curl et Python
Upload de l'image de référence, requêtes synchrones et asynchrones, et débogage d'un appel fonctionnel
Sur cette page
Ce que fait ce point de terminaison, et quand utiliser image-to-image
Les modèles de génération d'images à partir de texte excellent à créer des scènes de toutes pièces, mais de nombreuses tâches de production partent d'une image existante. gpt-image-2.6-flare/image-to-image est précisément le point de terminaison que HiAPI propose pour ce type de tâche : vous envoyez une image de référence et un prompt, et le modèle renvoie une image transformée qui suit vos instructions tout en restant fermement ancrée à l'image de référence.
Les cas d'usage typiques incluent :
- Transfert de style et repeinture — transformer une photo de produit en illustration stylisée, ou repeindre une photo dans un autre langage visuel.
- Édition et retouche — ajuster l'éclairage, l'arrière-plan ou la composition d'un visuel existant sans avoir à le reshooter.
- Génération de variantes — produire plusieurs variantes visuelles d'un design de base, pour des tests A/B ou l'exploration créative.
- Adaptation de visuels — redimensionner ou recadrer une image de référence pour différents canaux tout en préservant son sujet principal.
Si votre tâche consiste à « décrire quelque chose puis obtenir une image », la génération à partir de texte est le choix le plus simple. Utilisez image-to-image lorsque la sortie doit manifestement dériver d'une image d'entrée spécifique — cette image de référence est toute la raison d'être de l'appel. Dans la suite de cet article, nous allons construire une requête réelle de bout en bout : d'abord avec curl pour prouver qu'elle fonctionne, puis en Python, afin que vous puissiez l'intégrer à votre service.
Prérequis et structure de la requête
Avant d'appeler ce point de terminaison, assurez-vous que les conditions suivantes sont réunies :
- Un compte HiAPI et une clé API. La clé est envoyée sous forme de bearer token dans l'en-tête
Authorization. Ne la committez pas dans un dépôt de code source ; chargez-la plutôt depuis une variable d'environnement (par exempleHIAPI_API_KEY). - L'id du modèle. Utilisez strictement
gpt-image-2.6-flare/image-to-image— l'id du modèle est sensible à la casse, et la barre oblique fait partie de l'identifiant. - Le chemin du point de terminaison. La génération d'images se trouve sous la route de génération d'images de l'hôte de l'API HiAPI. Consultez la page du modèle pour obtenir l'URL de base et le chemin actuels, plutôt que de coder en dur un hôte vu dans d'anciens extraits de code.
- Un fichier d'image de référence, dans un format courant (PNG ou JPEG sont des choix par défaut sûrs). Gardez sa taille raisonnable ; les fichiers trop volumineux ralentissent l'upload et peuvent déclencher des limites de requête.
Une requête gpt-image-2.6-flare/image-to-image comporte trois parties essentielles :
- Le sélecteur de modèle — indique à HiAPI vers quel modèle router la requête.
- Le prompt — l'instruction textuelle décrivant la transformation souhaitée. Il n'est pas optionnel ; le prompt est ce qui guide l'édition.
- L'image de référence — l'image d'entrée sur laquelle le modèle doit travailler. La façon de la transmettre dépend du mode de requête (voir la section suivante).
En dehors de cela, ne transmettez que les paramètres documentés pour ce modèle sur sa page de modèle HiAPI. Si vous vous surprenez à inventer un champ parce que son nom « semble correct », arrêtez-vous et consultez la documentation — les paramètres inconnus sont une cause fréquente d'erreurs 4xx déroutantes.
Comment transmettre l'image de référence
Conceptuellement, l'image de référence n'est qu'un champ d'entrée de plus dans le corps de la requête — mais son volume la rend particulière. Il existe deux façons pratiques de transmettre les octets à l'API, et ce choix impacte bien plus votre code client que l'API elle-même.
Option A : intégrée dans le corps de la requête
Les petites images peuvent être intégrées directement dans la charge utile JSON, généralement sous forme de chaîne encodée en base64. Vous lisez le fichier, l'encodez, puis placez la chaîne dans le champ image de la requête. Tout tient dans une seule requête, ce qui est idéal pour les vignettes, les icônes et les fixtures de test.
Le coût : le base64 gonfle la charge utile d'environ un tiers, les encodeurs JSON peuvent ne pas gérer des chaînes très longues, et déboguer des corps de requête de plusieurs mégaoctets dans les logs est très pénible. L'intégration en ligne est une commodité, pas une solution pour les gros visuels.
Option B : upload puis référence par URL
Pour tout ce qui dépasse les petites images, uploadez d'abord le fichier vers un stockage que vous contrôlez, puis transmettez son URL comme référence. Votre corps de requête reste petit, les nouvelles tentatives sont peu coûteuses, et la même image peut être réutilisée sur plusieurs appels sans être réuploadée à chaque fois.
Quelques points à surveiller lors de l'utilisation d'URL :
- L'URL doit être publiquement accessible par l'API — pas derrière une authentification, pas en localhost, et pas un lien signé expirant qui casserait en cours de requête.
- Utilisez un type de contenu accepté par le modèle ; si l'URL renvoie du HTML au lieu d'une image, la validation échouera.
- Privilégiez des noms de fichier stables, afin de corréler les logs entre votre stockage et les requêtes HiAPI.
Quelle que soit l'option choisie, l'image de référence et le prompt sont transmis dans la même requête. L'API n'exige pas de handshake séparé « d'abord uploader, puis générer » — l'appel au modèle est une seule opération logique.
Appels synchrones et asynchrones
La génération d'images prend du temps, c'est pourquoi de nombreuses API d'images proposent à la fois un mode synchrone et un mode tâche asynchrone. Le même compromis s'applique ici.
Synchrone
Vous envoyez la requête et gardez la connexion ouverte jusqu'au retour de l'image. Votre code est une ligne droite : construire la requête, POST, lire la réponse, terminé.
Utilisez un appel synchrone lorsque :
- Vous prototypâtes ou déboguez et souhaitez voir le résultat complet en une étape.
- La requête s'exécute dans un environnement où un blocage temporaire est acceptable (outil CLI, worker en arrière-plan).
- Vous voulez le client le plus simple possible, sans logique de polling.
L'inconvénient est qu'une génération longue signifie maintenir la connexion longtemps, et tout proxy ou load balancer entre vous et l'API peut imposer ses propres timeouts.
Asynchrone
Vous soumettez la requête comme une tâche, obtenez immédiatement un identifiant de tâche, puis interrogez (ou recevez un callback) jusqu'à ce que la tâche soit terminée. Votre client a besoin d'une petite machine à états : soumettre, attendre, récupérer le résultat, gérer les échecs.
Utilisez un appel asynchrone lorsque :
- Vous servez du trafic orienté utilisateur et ne pouvez pas vous permettre de bloquer un thread de requête.
- Vous générez beaucoup d'images en batch et souhaitez distribuer en parallèle et collecter les résultats.
- Votre infrastructure a des timeouts de requête courts que vous ne contrôlez pas.
Comment choisir : si quelqu'un attend le résultat dans une requête web, utilisez l'asynchrone. Si un script ou un worker attend hors ligne, le synchrone est plus simple et convient. Ne surconcevez pas : commencez synchrone, et passez à l'asynchrone lorsque de vrais timeouts ou limites de concurrence vous y obligent.
La suite de cet article utilise le mode synchrone, car il rend chaque étape clairement visible, mais le corps de requête que vous construisez est identique dans les deux modes — seule la plomberie périphérique diffère.
Une requête curl fonctionnelle
Construisons cet appel depuis le terminal. Commencez par définir votre clé :
export HIAPI_API_KEY="your-api-key-here"
Étape 1 : préparer l'image de référence
Partez d'une image petite et sans ambiguïté, afin qu'un échec ne laisse aucune place au doute :
ls -lh reference.png
file reference.png
file doit rapporter PNG image data ou JPEG image data. S'il rapporte autre chose, corrigez-le avant de continuer.
Étape 2 : envoyer la requête
La requête est un POST vers le point de terminaison de génération d'images, avec un corps JSON contenant le modèle, votre prompt et l'image de référence. Selon l'option d'upload choisie, le champ image est soit une URL, soit une chaîne base64.
curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png"
}'
À propos de ces paramètres :
-sSmasque la barre de progression mais affiche toujours les erreurs — pratique pour les scripts.Authorization: Bearer $HIAPI_API_KEYévite que la clé apparaisse dans la commande elle-même.$HIAPI_BASE_URLest défini à partir de la page du modèle ; ne devinez pas l'hôte.- Ici, le champ
imageutilise l'option URL ; pour une image intégrée, remplacez-le par une chaîne base64.
Étape 3 : lire la réponse
Ajoutez -i pour inclure les en-têtes de réponse, et -w '\nHTTP %{http_code}\n' pour afficher le code de statut. Un appel réussi renvoie l'image (ou un lien vers l'image, selon le format de réponse) ainsi que des métadonnées. En cas d'échec, vous obtenez un statut 4xx ou 5xx et un corps d'erreur JSON — lisez le champ message avant de modifier quoi que ce soit d'autre.
Étape 4 : rediriger la sortie vers un fichier
Pour obtenir un fichier propre, redirigez stdout vers un fichier, puis vérifiez-le à nouveau avec file. Si la réponse est un JSON contenant une URL, extrayez cette URL et téléchargez-la avec un second curl. Avant de brancher cela dans un quelconque automatisme, vérifiez toujours que les octets téléchargés sont bien une image.
La même requête en Python
La base curl se traduit directement en Python. Cet exemple n'utilise que la bibliothèque standard plus requests :
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Traiter la réponse
Le format de réponse varie — il peut contenir directement l'image, ou une URL. Écrivez un petit helper pour unifier les deux cas, afin que le code en aval n'ait pas à se soucier duquel il s'agit :
def extract_image(data):
if "url" in data:
return requests.get(data["url"], timeout=60).content
if "image" in data:
import base64
return base64.b64decode(data["image"])
raise ValueError(f"Unexpected response shape: {list(data)}")
Gérer les erreurs
Ne laissez pas raise_for_status() être votre seule voie d'erreur. Encapsulez l'appel et exposez le message d'erreur de l'API :
try:
response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
image_bytes = extract_image(response.json())
except requests.HTTPError as e:
print("HTTP", e.response.status_code, e.response.text)
raise
except requests.Timeout:
print("Request timed out; consider the async job route instead")
raise
Variante asynchrone
Pour le mode asynchrone, soumettez la tâche avec la même charge utile, lisez l'id de tâche dans la réponse, puis interrogez le point de terminaison de statut de la tâche en dormant brièvement entre deux tentatives. Fixez une limite au nombre de pollings et traitez l'épuisement du budget comme un échec — ne faites jamais de polling infini dans un handler de requête.
Diagnostiquer les erreurs courantes
La plupart des échecs se rangent dans quelques catégories. Parcourez cette liste dans l'ordre ; chaque étape isole une variable.
Erreurs d'authentification (401 / 403)
HIAPI_API_KEYest-elle réellement définie dans le shell ou le processus ?echo $HIAPI_API_KEYdoit l'afficher.- L'en-tête est-il exactement
Authorization: Bearer <key>— A majuscule, B majuscule, un espace ? - La clé a-t-elle été révoquée ou renouvelée ? Régénérez-la et réessayez avec une requête minimale.
Charge utile d'image de référence invalide
C'est l'échec le plus courant, et ce n'est généralement pas la faute du modèle :
- URL inaccessible : ouvrez l'URL de l'image dans un navigateur sur un autre réseau. Si elle renvoie 404 ou redirige vers une page de connexion, l'API ne pourra pas non plus y accéder.
- Type de contenu incorrect : une URL qui renvoie du HTML ou du JSON sera rejetée. Utilisez
curl -I <url>pour confirmer que la réponse est bienContent-Type: image/.... - Fichier corrompu ou illisible : exécutez
file reference.pngen local. Vérifiez que la chaîne base64, une fois décodée, produit des octets identiques au fichier original. - Fichier trop volumineux : consultez la limite de taille documentée sur la page du modèle ; réduisez la taille avant de réessayer.
Erreurs de format de paramètre
- Faute de frappe dans l'id du modèle :
gpt-image-2.6-flare/image-to-imagedoit correspondre exactement, barre oblique comprise. - Prompt manquant : l'instruction textuelle est obligatoire et ne peut être omise.
- Champs superflus : retirez tout paramètre introuvable dans la documentation. Les clés inconnues déclenchent souvent des 4xx.
- Syntaxe JSON : validez votre corps de requête avec
jq . <<< "$BODY"avant de l'envoyer.
Timeouts
Si la requête est interrompue avant le retour de l'image, c'est que la connexion est maintenue trop longtemps. Raccourcissez le prompt, réduisez l'image de référence, augmentez le timeout client ; si le problème persiste, passez au mode tâche asynchrone — les générations longues sont précisément le cas d'usage de l'asynchrone.
Stratégie de débogage
Modifiez une seule variable à chaque tentative. Commencez par une image de référence très petite et sans ambiguïté et un prompt d'une phrase, prouvez que le pipeline fonctionne, puis introduisez progressivement les entrées réelles. Enregistrez le corps complet de la réponse à chaque échec ; le champ message pointe généralement directement la partie défaillante de la requête.
Intégrer à votre pipeline
Une fois la base fonctionnelle, quelques habitudes permettent de garder gpt-image-2.6-flare/image-to-image fiable en production.
Validez les entrées avant l'appel. Vérifiez que l'image de référence est dans un format pris en charge, sous la limite de taille, et si c'est une URL, qu'elle est accessible. Rejetez les mauvaises entrées à votre propre frontière plutôt que de payer pour un aller-retour échoué.
Validez les sorties après l'appel. Vérifiez que la réponse contient de vrais octets d'image (vérifiez les nombres magiques), et non une page d'erreur HTML intercalée. Une vérification d'en-tête peu coûteuse épargne beaucoup de débogage déroutant en aval.
Réessayez avec backoff, mais seulement pour les bonnes erreurs. Les 5xx transitoires et les timeouts réseau méritent une nouvelle tentative avec backoff exponentiel et jitter ; les erreurs 4xx dues à de mauvais paramètres échoueront à chaque fois de la même manière, il faut donc corriger la requête plutôt que la réessayer.
Privilégiez l'asynchrone pour le travail orienté utilisateur. Si quelqu'un attend sur une page, soumettez une tâche et faites du polling côté client — ne maintenez pas une requête web ouverte pour une génération longue.
Gardez l'id du modèle dans la configuration. Les ids de modèle changent avec le temps. Lisez-les depuis un point de configuration unique, de sorte que changer de modèle ne demande qu'une modification d'une ligne, pas un rechercher-remplacer global.
Combinez avec d'autres modèles HiAPI. Ce point de terminaison s'associe naturellement à la génération à partir de texte pour former des flux hybrides (générer d'abord une image de base, puis l'éditer) ; et, si votre pipeline en a besoin, à des étapes d'upscale ou de suppression d'arrière-plan. Comme tout passe par la même interface et la même authentification HiAPI, ajouter une étape revient à lancer un nouvel appel avec la même clé.
Commencez par la base curl, portez-la en Python, et passez à l'asynchrone lorsque le trafic l'exige. La page du modèle fournit les paramètres de requête et les limites actuels — consultez-la avant de supposer un nom de champ ou une taille maximale.
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