Comment utiliser gpt-image-2.5-sunburst@pro via l'API hiapi : curl, Python et exemples de requêtes exécutables

gpt-image-2.5-sunburst@pro est la route Pro du modèle gpt-image-2.5-sunburst sur hiapi. Ce guide vous mène de zéro à une requête fonctionnelle : ce qu'est exactement l'id du modèle, quels champs input précis il accepte, un exemple curl/Python directement exécutable, et les schémas de production dont vous aurez besoin avant une exécution sans surveillance (idempotence, callbacks, gestion des erreurs).

Ce que vous devez préparer au préalable

• Un compte hiapi et une clé API provenant de la console. Chaque requête ci-dessous s'authentifie avec Authorization: Bearer sk-<your key>.
• C'est tout — aucun SDK séparé à installer. Chaque modèle sur hiapi est appelé via le même endpoint de tâche asynchrone, donc si vous avez déjà appelé un autre modèle hiapi, la structure de cette requête vous sera familière.

La seule spécificité de ce modèle : @pro est un suffixe de route, pas un surnom. hiapi expose plus d'un mode d'appel pour certains modèles, et gpt-image-2.5-sunburst en fait partie — l'id de modèle nu et l'id avec le suffixe @pro acceptent des champs input différents et sont facturés à des paliers tarifaires différents. Ce guide porte spécifiquement sur gpt-image-2.5-sunburst@pro ; avec l'id nu gpt-image-2.5-sunburst, vous obtiendrez un mode et un schéma différents (voir la FAQ).

Exemple minimal exécutable

Chaque modèle de génération de hiapi — image, vidéo ou audio — est appelé via le même endpoint unifié : POST /v1/tasks. Vous soumettez model et input, recevez immédiatement un taskId, et la génération s'exécute de manière asynchrone.

Pour gpt-image-2.5-sunburst@pro, input accepte :

Champ	Type	Obligatoire	Description
prompt	string	Oui	1 à 32 000 caractères
image_urls	string[]	Non	1 à 16 URL publiques JPEG/PNG/WebP ; incluez ce champ pour faire de l'image-vers-image plutôt que du texte-vers-image (SVG non pris en charge)
aspect_ratio	enum	Non	Par exemple 1:1, 16:9, 9:16, ou une dimension explicite comme 1536x1024 ; par défaut 1:1
quality	enum	Non	low / medium / high / xhigh / max / auto ; par défaut medium — consultez les notes de production ci-dessous avant d'augmenter
background	enum	Non	transparent, opaque ou auto ; par défaut auto
output_format	enum	Non	png, jpeg ou webp ; par défaut webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper on a light wood table, soft studio lighting",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

Cela renvoie immédiatement un taskId :

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

Interrogez ensuite le résultat par polling :

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Dès que data.status vaut success, l'image se trouve dans data.output[0].url. Téléchargez-la immédiatement — cette URL porte un expireAt et ne convient pas à une référence de lien externe permanente.

Python

import time
import requests

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

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper "
                      "on a light wood table, soft studio lighting",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

Schémas de production

Polling et callbacks. La boucle ci-dessus convient aux scripts et aux usages à faible trafic. Pour tout scénario côté serveur, privilégiez le callback au polling : ajoutez un objet callback à la même requête —

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url doit être HTTPS, et when: "final" (actuellement la seule valeur prise en charge) vous notifie une fois en cas de succès comme d'échec — pas de boucle de polling, pas de requêtes gaspillées. hiapi peut livrer un callback plusieurs fois, donc dédupliquez de votre côté par taskId.

Idempotence. Ajoutez l'en-tête Idempotency-Key sur POST /v1/tasks (une chaîne de 255 octets maximum, par exemple un id de commande). Si un timeout réseau amène votre client à retenter la même soumission, la plateforme renvoie le taskId d'origine (en-tête de réponse Idempotent-Replay: true) au lieu de créer — et facturer — une seconde tâche. Cette clé est limitée à votre compte et expire après 24 heures ; la réutiliser avec un corps de requête différent renvoie 422 IDEMPOTENCY_KEY_MISMATCH plutôt que de créer silencieusement une nouvelle tâche, donc une non-concordance est un signal qui vous invite à vérifier votre logique de retry plutôt qu'à réessayer aveuglément.

Erreurs d'authentification. Une clé API mal formée ou erronée échoue rapidement avec un 401 et le code d'erreur permission_denied, et ce avant toute création de tâche :

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

Si vous voyez cela, la correction concerne presque toujours la clé elle-même (variable d'environnement mal orthographiée, clé expirée, préfixe sk- manquant) — et non le corps de la requête. Traitez-la comme non réessayable jusqu'à ce que la clé soit corrigée.

À propos de quality. quality vaut medium par défaut, une valeur de départ raisonnable — l'augmenter augmente à la fois le coût et le temps de génération, donc ne passez à high/xhigh/max qu'après avoir confirmé dans vos propres tests qu'un prompt donné réussit encore de manière fiable à ce palier.

Pages associées

• Page du modèle gpt-image-2.5-sunburst — capacités de cette famille de modèles, exemples de sorties et tous les modes disponibles.
• Documentation de l'API asynchrone unifiée — le contrat complet /v1/tasks partagé par tous les modèles de génération hiapi (idempotence, callbacks, codes de statut).
• Documentation d'authentification — comment créer et gérer des clés API.
• Guide de l'API gpt-image-2.5-sunburst — si vous voulez le mode de base (non @pro), cet article détaille son schéma distinct basé sur resolution.
• Tarification — coût actuel par image selon le palier de quality.

FAQ

gpt-image-2.5-sunburst@pro et gpt-image-2.5-sunburst sont-ils des modèles différents ? Même famille de modèles, routes différentes. L'id nu gpt-image-2.5-sunburst (et son mode /text-to-image) accepte un champ resolution (1K/2K/4K) et n'a pas de champ quality ni image_urls. @pro le remplace par des paliers quality et ajoute un image_urls optionnel, donc utilisez cette route lorsque vous voulez contrôler le palier de qualité ou faire de l'image-vers-image dans le même appel.

Ai-je besoin d'une image de référence ? Non. Pour le texte-vers-image, omettez complètement image_urls. Inclure 1 à 16 URL d'images publiques conditionne la sortie sur des images de référence.

Puis-je utiliser ce modèle sans clé API ? Non — chaque requête nécessite un en-tête Authorization: Bearer valide avec une vraie clé API hiapi de votre compte. Il n'existe aucun palier non authentifié ou sans clé.

Combien cela coûte-t-il ? Le prix varie selon le palier de quality et est tenu à jour sur la page de tarification, plutôt que répété ici — consultez-la avant d'estimer les coûts à grande échelle.

Que faire si mon callback n'arrive jamais ? La livraison des callbacks n'est pas garantie immédiate, et hiapi peut réessayer la livraison (donc dédupliquez par taskId). Si vous avez besoin d'une limite stricte, conservez après le timeout un polling de secours sur GET /v1/tasks/:id plutôt que d'attendre indéfiniment le callback.

Pourquoi ai-je un statut fail au lieu d'une erreur à la soumission ? La soumission (qui renvoie 200/taskId) signifie seulement que la requête a été acceptée — la génération elle-même peut encore échouer de manière asynchrone. Vérifiez data.status après polling ou via callback, et examinez data.error pour en connaître la cause avant de resoumettre.