Blog

Tutoriel

Comment utiliser gpt-image-2.6-sunburst/image-to-image via l'API HiAPI : pratique avec curl et Python

Soumettre une image de référence, interroger des tâches asynchrones et déboguer les requêtes de bout en bout

Nov 10, 2026
Illustration de couverture pour un tutoriel HiAPI : de fines couches de papier s'éloignant en faible profondeur, en crème, graphite et une seule feuille terracotta.
Sur cette page

Cas d'usage de gpt-image-2.6-sunburst/image-to-image

Le texte-à-image vous donne ce que le modèle produit librement à partir d'un prompt. L'image-à-image part de matériel que vous possédez déjà : vous fournissez une image de référence et une instruction au point de terminaison, et le modèle génère une nouvelle image dérivée de cette référence. Sur HiAPI, gpt-image-2.6-sunburst/image-to-image est le point de terminaison dédié à ce second mode.

Choisissez-le lorsque l'image source fait partie de l'exigence elle-même — par exemple pour restyler du matériel existant, ajuster la lumière ou la composition, appliquer un traitement visuel à une photo produit, ou générer des variantes contrôlées d'un design. L'image de référence est l'ancre : elle porte le sujet, la palette et la mise en page, et votre prompt décrit la transformation, pas la scène depuis zéro. Si vous n'avez pas de matériel source et voulez simplement une image à partir d'une description, le point de terminaison texte-à-image est plus simple et laisse plus de liberté au modèle.

Deux conséquences pratiques déterminent tout ce qui suit. Premièrement, la requête transporte une entrée quasi binaire (une référence d'image), ce qui influence la construction du corps de requête. Deuxièmement, la génération d'image n'est pas instantanée, donc ce point de terminaison fonctionne en tâche asynchrone plutôt que de renvoyer l'image en ligne. Planifiez deux étapes — « soumettre » et « récupérer » — plutôt qu'un appel bloquant.

Prérequis et configuration de l'authentification

Avant votre première requête, il vous faut trois choses : un compte HiAPI, une clé d'API, et un moyen de référencer l'image source accepté par le point de terminaison. Créez la clé dans la console HiAPI et traitez-la comme un mot de passe — elle autorise chaque appel débité sur votre compte.

Transmettez la clé sous forme de jeton bearer dans l'en-tête Authorization. Ne la codez jamais en dur dans un fichier source, un notebook ou l'historique de commits. Exportez-la en variable d'environnement pour les tests shell, et lisez-la depuis l'environnement (ou un gestionnaire de secrets) dans le code applicatif :

export HIAPI_API_KEY="your_api_key_here"

Décidez à l'avance comment fournir l'image de référence. En général, vous pouvez téléverser le matériel à un emplacement temporaire et passer une URL, ou envoyer l'image en données encodées en base64 dans le corps de requête. L'URL rend la requête plus légère et plus facile à journaliser ; le base64 évite un hébergement supplémentaire mais gonfle le corps de requête. Dans les deux cas, gardez le fichier dans un format pris en charge par le point de terminaison et vérifiez les limites de taille avant l'envoi. Notez aussi l'URL de base de l'API HiAPI de votre compte — chaque chemin ci-dessous doit être préfixé par elle.

Soumettre une image de référence avec curl

Commencez dans le shell, pour voir exactement ce qui est envoyé. L'appel prend la forme d'un POST vers le point de terminaison image-à-image, avec un corps JSON contenant l'image de référence et l'instruction.

curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst/image-to-image",
    "image": "https://your-bucket.example.com/reference.png",
    "prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
    "n": 1
  }'

Champ par champ : model sélectionne le point de terminaison ; image porte l'image de référence (ici une URL, ou une chaîne de données base64 si vous n'hébergez pas le fichier) ; prompt est l'instruction d'édition, qui doit décrire le changement plutôt que redécrire le sujet ; n est le nombre de sorties souhaitées. Rendez le prompt précis et bien délimité — les instructions qui contredisent l'image de référence produisent facilement des résultats confus.

Envoyez la requête et examinez le corps de la réponse. Pour un point de terminaison asynchrone, vous ne recevez pas l'image terminée ; vous recevez un identifiant de tâche ou un objet d'état. Enregistrez cette réponse avant de continuer — c'est le handle de toutes les opérations suivantes. Un curl -i permet aussi de voir rapidement le code de statut HTTP, le moyen le plus rapide de distinguer un problème d'authentification (4xx à la soumission) d'un problème de contenu.

Exécuter le même appel en Python

Une fois l'appel shell réussi, portez-le en Python. La bibliothèque standard suffit, mais requests rend l'exemple plus lisible :

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2.6-sunburst/image-to-image",
    "image": "https://your-bucket.example.com/reference.png",
    "prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
    "n": 1,
}

resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)

Les différences avec curl sont mécaniques : la clé vient de os.environ, le corps est un dict sérialisé en JSON, et raise_for_status() transforme une soumission échouée en exception plutôt qu'en erreur silencieuse. La dernière ligne compte — la plupart des souffrances de débogage viennent du traitement d'une réponse 4xx comme un succès, puis de l'interrogation d'un identifiant de tâche qui n'a jamais existé.

Pour une entrée binaire, lisez le fichier, encodez-le en base64, puis placez la chaîne dans image au lieu de l'URL. Le reste du corps de requête ne change pas, donc vous pouvez passer d'un mode à l'autre sans modifier la logique de requête.

Gérer le cycle de vie des tâches asynchrones

La génération d'image prend du temps, donc le point de terminaison suit le schéma « soumettre puis interroger ». Comprenez les trois états, le reste est du travail d'enregistrement.

1. Soumettre et capturer la tâche

Votre POST renvoie un identifiant de tâche. Extrayez-le immédiatement et persistez-le quelque part — une ligne de base de données, un message de file d'attente, une ligne de journal interrogeable. Si votre processus plante entre la soumission et l'interrogation, cet identifiant est le seul moyen de récupérer le travail que vous avez payé.

2. Interroger jusqu'à l'achèvement de la tâche

Interrogez le point de terminaison d'état avec l'ID de tâche à intervalle fixe. Commencez prudemment — quelques secondes entre chaque vérification — et reculez progressivement pour les tâches longues afin de ne pas marteler l'API. Arrêtez-vous à un état terminal : succès, échec, ou votre propre délai d'expiration. Ne faites jamais d'interrogation en boucle serrée.

import time

def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/v1/images/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        interval = min(interval * 1.5, 15)
    raise TimeoutError(f"job {job_id} not finished in time")

3. Récupérer et stocker le résultat

En cas de succès, la réponse pointe vers l'image générée. Si l'URL est temporaire, téléchargez-la rapidement et écrivez-la dans votre propre stockage sous un nom que vous contrôlez, afin que les consommateurs en aval ne dépendent jamais d'un lien temporaire. Enregistrez l'ID de tâche avec le matériel stocké — c'est votre aide au débogage la moins coûteuse.

En production, l'interrogation doit être pilotée par un worker en arrière-plan, pas par le gestionnaire de requêtes. Une requête web qui bloque pendant toute la durée de la génération d'image est fragile et immobilise inutilement une connexion.

Erreurs courantes et comment les corriger

En cas d'échec, parcourez cette liste de haut en bas ; le premier point capte la plupart des problèmes.

401 / 403 à la soumission

Problème d'authentification. Vérifiez que la clé est présente dans l'en-tête Authorization, que le schéma Bearer est utilisé, et qu'aucun espace parasite ou saut de ligne n'a été introduit par le copier-coller. Confirmez que la variable d'environnement est bien définie dans le shell ou le processus qui exécute la requête.

400 / 422 sur le corps de requête

Corps de requête mal formé ou champ erroné. Causes fréquentes : erreur de syntaxe JSON due à une chaîne curl manuelle, valeur image qui n'est ni une URL accessible ni du base64 valide, prompt manquant, ou format d'image non pris en charge. Validez le JSON localement et confirmez que l'image de référence se charge bien dans un navigateur.

404 sur le modèle ou le chemin

Erreur de frappe dans le chemin ou le nom du modèle. L'identifiant de modèle est une chaîne exacte — gpt-image-2.6-sunburst/image-to-image diffère de la variante texte-à-image, et la casse est sensible.

Délais d'expiration et interrogation bloquée

Distinguez une tâche lente d'une tâche défaillante. Définissez un timeout pour chaque appel HTTP, fixez votre propre échéance globale, et journalisez le dernier état de tâche observé lorsque vous abandonnez. Si les tâches dépassent régulièrement votre échéance, augmentez-la plutôt que de passer à une boucle de nouvelles tentatives serrée.

Sortie vide ou inutilisable

La tâche a réussi mais l'image n'est pas celle souhaitée. C'est généralement un problème de prompt : instruction trop vague, ou en conflit avec l'image de référence. Rendez l'instruction d'édition plus précise sur ce qui doit changer et ce qui doit rester identique.

Recommandations de production pour un pipeline image-à-image

Une fois le prototype fonctionnel, le travail restant porte sur la fiabilité et la prévisibilité.

  • Ne réessayez que les erreurs réessayables. Utilisez un backoff exponentiel pour les échecs de soumission dus à des 5xx et des erreurs réseau ; ne réessayez pas aveuglément les 4xx, ils échoueront à nouveau. Suivez vous-même l'idempotence en liant la tâche à votre propre ID de requête, afin que les nouvelles tentatives ne dupliquent pas le travail.
  • Séparez la soumission et l'interrogation. Placez la soumission et l'interrogation dans des workers ou des étapes différents. Cela rend votre latence API indépendante du temps de génération et vous permet de scaler l'interrogation indépendamment.
  • Maîtrisez votre propre stockage. Téléchargez le résultat dans votre propre bucket dès que la tâche est terminée. Traitez l'URL renvoyée comme un lien temporaire.
  • Versionnez vos prompts. Les prompts sont des actifs de production. Stockez le prompt, l'image de référence et l'ID de tâche avec chaque sortie, afin de pouvoir reproduire ou expliquer un résultat des mois plus tard.
  • Surveillez la latence et le coût. Les tâches d'image sont facturées à la sortie, donc limitez la concurrence par utilisateur et enregistrez l'usage par tâche. Surveillez la latence p95 de la soumission au stockage du matériel — c'est le chiffre que les utilisateurs ressentent réellement.

Une fois la forme de la requête et le cycle de vie établis, le reste est de l'ingénierie classique. Vous trouverez les détails du modèle dans la documentation HiAPI, et de là vous pourrez brancher le point de terminaison dans votre pipeline.

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