API de génération d'images à partir de texte GPT Image 2.5 Sunburst : guide curl et Python fonctionnel

Si vous souhaitez générer des images via l'API hiapi avec gpt-image-2.5-sunburst/text-to-image, ce guide vous accompagne à travers une requête complète et fonctionnelle, en utilisant respectivement curl et Python — de la création de la tâche au téléchargement de l'URL finale de l'image. Chaque requête/réponse présentée ici a été réellement exécutée contre l'API en production avant publication.

Prérequis

• Disposer d'un compte hiapi et d'une clé API (sk-...). Disponible dans la console hiapi.
• curl, ou Python 3.8+ si vous suivez l'exemple Python.
• Un budget pour au moins une image de sortie. gpt-image-2.5-sunburst/text-to-image est facturé selon la résolution de sortie — consultez la tarification actuelle avant d'exécuter en production, car les tarifs peuvent changer.

Toutes les requêtes utilisent les en-têtes standard :

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

Exemple minimal fonctionnel

Les modèles d'image de hiapi fonctionnent tous sur la même API de tâches asynchrone : vous créez une tâche via POST, puis vous interrogez (ou recevez un callback webhook) jusqu'à ce qu'elle atteigne un état terminal, puis vous lisez l'URL de l'image dans output[0].url.

1. Créer une tâche (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product shot of a ceramic coffee dripper on a marble counter, soft morning light, 35mm lens look",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

Un appel réussi retourne uniquement un ID de tâche — la génération est asynchrone :

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

2. Interroger le résultat

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

Continuez à interroger toutes les quelques secondes jusqu'à ce que data.status devienne un état terminal. En cas de succès, la réponse ressemble à ceci (taskId/URL raccourcis pour la lisibilité) :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

Récupérez l'image depuis data.output[0].url. Cette URL expire (voir expireAt, un horodatage Unix) — téléchargez les octets et stockez-les vous-même dès que la tâche réussit, ne la traitez pas comme un lien permanent.

3. Exemple Python de bout en bout

import time
import requests

API_KEY = "sk-your-api-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("A minimalist product shot of a ceramic coffee dripper on a marble counter")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

Champs réellement acceptés par input

Le schéma de gpt-image-2.5-sunburst/text-to-image est petit et strict. Seuls les champs suivants sont acceptés — tout autre champ (quality, size, n, output_format, style, seed) sera rejeté avec une erreur 400 :

Champ	Obligatoire	Valeurs
prompt	Oui	Chaîne quelconque
resolution	Non (par défaut 1K)	1K, 2K, 4K
aspect_ratio	Non	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
background	Non	transparent, opaque, auto

Notez que cela diffère du schéma du modèle brut gpt-image-2.5-sunburst : ce dernier accepte des niveaux de quality (low/medium/high/xhigh/max/auto) et prend en charge l'édition image-vers-image via image_urls. La tarification diffère également entre les deux — avant de vous fier à des chiffres précis, vérifiez sur /en/pricing, car les tarifs peuvent changer.

Modes de production

Utiliser un callback webhook au lieu de l'interrogation

Pour tout usage au-delà d'un script rapide, évitez l'interrogation et laissez hiapi vous rappeler à la fin de la tâche. Ajoutez un objet callback au niveau supérieur de la même requête POST /v1/tasks :

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

when: "final" est actuellement la seule valeur prise en charge — lorsque la tâche atteint un état terminal (success ou fail), votre endpoint est appelé une fois, avec une structure de payload identique au résultat obtenu par interrogation.

Interrogation vs. callback : l'interrogation est plus simple à implémenter correctement dans un script ou un notebook, et ne nécessite pas d'endpoint public, mais elle gaspille des requêtes et ajoute de la latence (en moyenne la durée de votre intervalle d'interrogation) avant que vous sachiez que c'est terminé. Pour les intégrations côté serveur ou tout scénario à forte concurrence, le callback est préférable — vous évitez entièrement la boucle d'interrogation et êtes notifié dès que la tâche aboutit.

Idempotence lors des nouvelles tentatives

L'API de tâches accepte une chaîne idempotency_key au niveau supérieur, aux côtés de model/input/callback. Si votre client est susceptible de réessayer le POST après un timeout (vous avez envoyé la requête mais n'avez jamais reçu de réponse), ajoutez une clé stable, afin de disposer d'un signal clair à vérifier plutôt que de deviner si la requête d'origine a réellement abouti.

Gérer les erreurs

Une clé API invalide ou expirée renvoie un HTTP 401 avec un corps d'erreur structuré :

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "request_id": "2026...",
    "type": "hiapi_error"
  }
}

Des valeurs input incorrectes (membre d'énumération erroné, prompt manquant, champs non pris en charge) renvoient un HTTP 400 avant la création de la tâche — vous n'êtes donc pas facturé :

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Vérifiez explicitement ces deux cas : réessayez pour les erreurs réseau/5xx transitoires, mais traitez le 400 comme un signal pour corriger le corps de la requête, et non comme un objet à réessayer aveuglément.

Ressources associées

• Page du modèle gpt-image-2.5-sunburst — référence complète des paramètres et tarification en temps réel pour le modèle brut et la route /text-to-image.
• Tarification hiapi — tarifs actuels par résolution pour ce modèle et tous les autres.
• Recettes de prompts GPT Image 2.5 Sunburst — si vous cherchez l'inspiration avant d'écrire votre script, voici des exemples de prompts à consulter.

FAQ

Dois-je spécifier resolution ? Non — si vous l'omettez, la valeur par défaut est 1K. Si vous avez besoin d'une sortie 2K ou 4K, définissez-la explicitement, car le prix augmente avec la résolution.

Puis-je passer quality comme dans la documentation des autres modèles GPT Image ? Non sur cette route. gpt-image-2.5-sunburst/text-to-image rejette complètement quality — ce paramètre n'existe que sur l'ID de modèle brut gpt-image-2.5-sunburst, qui a un schéma et une tarification différents.

Pourquoi ma requête renvoie-t-elle un ID de tâche plutôt que directement l'image ? Chaque modèle d'image sur hiapi fonctionne via la même API de tâches asynchrone (POST /v1/tasks → interrogation ou callback → output[0].url), quelle que soit la vitesse réelle du modèle sous-jacent. Construisez une intégration autour de ce schéma une fois, et chaque modèle que vous remplacerez ensuite fonctionnera de la même manière.

Que se passe-t-il si je ne télécharge pas l'URL de sortie à temps ? Elle expire — le champ expireAt dans la réponse de la tâche est l'horodatage Unix à partir duquel l'URL temporaire cesse de fonctionner. Dès que status vaut success, téléchargez et stockez les octets vous-même immédiatement.

Puis-je utiliser ce modèle pour l'édition image-vers-image ? Non sur la route /text-to-image. Pour l'édition d'images, utilisez l'ID de modèle brut gpt-image-2.5-sunburst et passez le champ d'entrée image_urls — consultez sa page du modèle pour le schéma exact.

Prêt à essayer par vous-même ? Récupérez une clé API dans la console hiapi et remplacez le prompt dans l'exemple Python ci-dessus.