Comment utiliser gpt-image-2.5-sunburst via l'API hiapi : curl, Python et exemples de requêtes disponibles

Pour générer ou éditer une image avec gpt-image-2.5-sunburst, soumettez une tâche contenant le prompt à POST /v1/tasks, puis interrogez GET /v1/tasks/<id> (ou recevez un callback) jusqu'à ce que la tâche soit terminée, et lisez l'URL de l'image dans data.output[0].url. Ce guide couvre la requête minimale, l'ensemble complet des paramètres, ainsi que les patterns de production nécessaires avant la mise en ligne (callbacks, idempotence, gestion des erreurs).

Prérequis

Vous avez besoin d'une clé API hiapi. Créez-en une depuis la console — chaque requête est authentifiée avec Authorization: Bearer sk-<your-key>. Il n'existe aucun moyen d'appeler l'API depuis un navigateur avec un niveau gratuit, ni aucun moyen sans clé ; tous les exemples ci-dessous supposent que vous disposez déjà d'une clé.

Exemple minimal fonctionnel

gpt-image-2.5-sunburst/text-to-image ne nécessite que prompt dans input. Le ratio d'aspect par défaut est auto, la résolution par défaut est 1K.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

Il renvoie immédiatement un identifiant de tâche :

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

Interrogez le résultat :

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

Version Python du même aller-retour :

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url pointe vers un stockage temporaire — la réponse contient expireAt (en secondes Unix). Téléchargez les octets et persistez-les avant cette échéance (votre propre stockage, S3, R2, etc.) ; ne la traitez pas comme un lien permanent.

Référence complète des paramètres

gpt-image-2.5-sunburst dispose de deux identifiants de modèle : gpt-image-2.5-sunburst/text-to-image pour générer à partir d'un prompt, et gpt-image-2.5-sunburst/image-to-image pour éditer ou composer à partir d'images de référence. Les deux acceptent les mêmes champs, la différence étant que image_urls est obligatoire en image-to-image et inutilisé en text-to-image :

Champ	Type	Valeur par défaut	Description
prompt	string, 1–8000 caractères	—	Obligatoire. Pour l'édition, décrivez ce qui doit changer et ce qui doit rester strictement identique.
image_urls	tableau d'URL	—	Image-to-image uniquement, obligatoire, 1–16 images JPEG, PNG ou WebP, chacune jusqu'à 20 mégapixels et au maximum 30 Mo. Doit être une URL téléchargeable publiquement ou un data URI.
aspect_ratio	énumération	"auto"	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9.
resolution	énumération	"1K"	1K, 2K, 4K. Cela détermine le prix.
background	énumération	aucune	transparent, opaque, auto. transparent ne prend effet qu'en 1K, et renvoie alors un PNG avec canal alpha.

Exemple d'édition — passez une ou plusieurs images de référence et décrivez uniquement les modifications souhaitées :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

Le schéma est strict (additionalProperties: false) — les champs inconnus sont rejetés, donc ne réutilisez pas les paramètres d'autres modèles d'image (par exemple size, strength, n).

Patterns de production

Utilisez des callbacks plutôt que le polling dans un vrai backend. Ajoutez un bloc callback pour éviter la boucle de polling :

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" se déclenche exactement une fois lorsque la tâche atteint un état terminal (success ou fail). Votre endpoint doit répondre rapidement 2xx et effectuer le travail réel de manière asynchrone (télécharger la sortie, mettre à jour votre propre base de données) — hiapi réessaie les callbacks qui n'ont pas reçu d'acquittement rapide.

Rendez les tentatives idempotentes. Si la requête du client expire, vous ne pouvez pas savoir si la tâche a été créée. Envoyez l'en-tête Idempotency-Key dans la requête de création (255 octets max) et réutilisez la même clé lors des tentatives : une même clé sur un même compte ne crée qu'une seule tâche, et les tentatives renvoient le taskId d'origine. Sans cela, un même prompt traité en double sera facturé deux fois.

Gérez les états terminaux que vous rencontrerez réellement :

• success — lisez data.output[0].url et téléchargez rapidement (respectez expireAt).
• fail — vérifiez data.error pour connaître la cause avant de réessayer ; ne réessayez pas aveuglément à chaque échec, certains relèvent du prompt (par exemple une violation de politique) et échoueront toujours à l'identique.
• Interroger un identifiant de tâche inexistant (faute de frappe, expiré) renvoie HTTP 404 avec le contenu {"code":404,"message":"task not found"}.

Un échec d'authentification est un HTTP 401, et non une erreur au niveau de la tâche :

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

Vérifiez ce point dans votre gestion des erreurs avant de considérer la tâche comme échouée — une clé invalide ou révoquée n'atteint jamais l'étape de création de tâche.

Lectures associées

• Page du modèle GPT Image 2.5 Sunburst — exemples en direct et tarification actuelle.
• GPT Image 2.5 : génération, édition et migration — si vous migrez depuis une route Image 2 plus ancienne vers la série 2.5 (Flare ou Sunburst), cet article couvre les différences de paramètres.
• Comment restyler des images avec l'IA — si le mode édition de Sunburst ne représente qu'une partie de votre pipeline, vous y trouverez un parcours image-to-image plus complet.
• Documentation d'authentification et démarrage rapide, pour comprendre le cycle de vie complet des requêtes au-delà de ce seul modèle.

Questions fréquentes

gpt-image-2.5-sunburst prend-il en charge l'édition d'images, ou seulement la génération à partir de texte ? Les deux, via deux identifiants de modèle. Utilisez gpt-image-2.5-sunburst/image-to-image avec image_urls (1–16 images de référence) pour éditer ou composer, et gpt-image-2.5-sunburst/text-to-image pour générer uniquement à partir de texte.

Que se passe-t-il si j'envoie un tableau image_urls vide au lieu de l'omettre ? Ne faites pas cela. En image-to-image, image_urls est obligatoire et nécessite au moins une URL. Pour la génération purement textuelle, utilisez plutôt l'identifiant de modèle text-to-image.

Combien coûte une image ? Cela dépend de la resolution : 0,05 $ en 1K, 0,08 $ en 2K, 0,12 $ en 4K, identique en text-to-image et en image-to-image. Pendant la promotion de la Journée du programmeur (jusqu'au 9 novembre 2026 à 00:00 UTC+8), tous les paliers bénéficient de 50 % de réduction : 0,025 $, 0,04 $ et 0,06 $. Avant de monter en charge, consultez la page du modèle pour les tarifs actuels.

Puis-je obtenir une taille en pixels fixe plutôt qu'un ratio d'aspect ? Oui — outre les chaînes de ratio comme 16:9, aspect_ratio accepte aussi des dimensions littérales comme 1024x1024, 1536x1024 ou 3840x2160.

Pourquoi mon polling de tâche renvoie-t-il 404 ? Soit le taskId comporte une faute de frappe, soit l'endpoint/région que vous interrogez ne contient pas cette tâche. Vérifiez soigneusement l'identifiant que vous avez enregistré à partir de la réponse de création — hiapi n'expire pas silencieusement les enregistrements de tâches pendant une fenêtre de polling normale.

Puis-je l'appeler pour tester sans clé API ? Non. Chaque requête vers /v1/tasks nécessite Authorization: Bearer sk-<key> ; aucun mode anonyme ni purement navigateur n'existe.