Tutoriel

Comment utiliser gpt-image-2.5-flare@pro via l'API hiapi : curl, Python et une requête exécutable

Sep 12, 2026

gpt-image-2.5-flare@pro est l'un des modèles d'image proposés via l'API de tâches unifiée de hiapi. Ce guide présente d'abord une requête minimale exécutable avec curl et Python, puis détaille les paramètres et les modes nécessaires en production : callbacks, idempotence et gestion des erreurs.

Ce qu'il vous faut

Une clé d'API hiapi. Vous pouvez l'obtenir depuis la console hiapi — chaque clé commence par sk-.
https://api.hiapi.ai comme URL de base. Chaque requête nécessite l'en-tête Authorization: Bearer sk-<your-key>.

La génération d'images sur hiapi (ainsi que tous les autres modèles asynchrones — vidéo, TTS, musique) s'exécute via le même endpoint : POST /v1/tasks. Vous créez d'abord une tâche, puis vous pouvez soit interroger GET /v1/tasks/:id, soit recevoir un callback lorsque la tâche est terminée. Référence complète : API asynchrone unifiée.

Exemple minimal exécutable

curl

Créer une tâche :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

Ce qui est renvoyé ici est un ID de tâche, pas une image — la génération d'images est asynchrone :

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

Interroger le résultat :

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status évolue dans l'ordre queued → handling → archiving → success (ou fail). Lorsque le statut est success, l'image se trouve dans data.output[0].url :

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt est un horodatage Unix — téléchargez le fichier ou réhébergez-le avant son expiration ; une fois expiré, l'URL cesse de fonctionner.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Installez l'unique dépendance avec pip install requests, exportez HIAPI_API_KEY, puis exécutez.

Paramètres clés

gpt-image-2.5-flare propose deux routes : la route par défaut (utiliser directement l'ID de modèle gpt-image-2.5-flare) et la route pro (ajouter @pro, comme dans tous les exemples ci-dessus). Il n'existe pas de suffixe explicite @default — le transmettre renvoie MODEL_UNAVAILABLE.

input accepte les champs suivants :

prompt (chaîne, obligatoire) — le seul champ obligatoire.
aspect_ratio — 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto, ou une dimension en pixels explicite comme 1536x1024, 2048x2048, 3840x2160.
quality — low, medium, high, xhigh, max ou auto.
output_format — png, jpeg ou webp.
background — auto, transparent ou opaque. Utilisez transparent avec output_format: png ou webp pour obtenir des ressources détourées.

Le schéma est strict — les champs inconnus (size, n, ou tout champ non listé) renvoient 400 INVALID_REQUEST avec additional properties '<field>' not allowed, au lieu d'être ignorés silencieusement. Si vous devez modifier une image existante plutôt que générer à partir d'un prompt vide, hiapi le propose comme un ID de modèle distinct — consultez la page du modèle pour la variante image-vers-image.

Modes de production

Utilisez les callbacks plutôt que l'interrogation répétée. Ajoutez un objet callback dans la requête de création :

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" est actuellement la seule valeur prise en charge — lorsque la tâche atteint success ou fail, hiapi envoie une requête POST à votre URL. Le corps du callback est exactement le champ data renvoyé par GET /v1/tasks/:id.

Envoyez l'en-tête Idempotency-Key. Si votre requête expire de votre côté et que vous réessayez, la clé d'idempotence empêche hiapi de créer (et facturer) une seconde tâche pour la même requête.

Gérez explicitement les erreurs. Une clé invalide ou révoquée renvoie HTTP 401 :

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

Un input mal formé renvoie HTTP 400, accompagné de error_code: "INVALID_REQUEST" et d'un message indiquant le champ en cause — vérifiez-le avant de réessayer ; réessayer un 400 avec le même corps de requête ne fera qu'échouer à nouveau.

La tarification de gpt-image-2.5-flare@pro (facturée par image générée avec succès, selon la résolution et le niveau de qualité) est disponible sur la page de tarification.

Documentation associée

Référence de l'API asynchrone unifiée — cycle de vie complet des tâches, tous types de modèles
Créer une tâche — structure de requête/réponse de POST /v1/tasks
Obtenir les détails d'une tâche — interroger GET /v1/tasks/:id
Authentification — format des clés d'API et en-têtes
Page du modèle gpt-image-2.5-flare@pro

Questions fréquentes

Quelle différence entre la route par défaut et @pro ? Ce sont deux routes distinctes de la même famille de modèles, choisies via l'ID de modèle que vous envoyez (gpt-image-2.5-flare vs gpt-image-2.5-flare@pro). Consultez la page du modèle et la tarification avant de choisir, pour connaître les différences actuelles de coût et de capacités.

Puis-je générer un PNG transparent ? Oui — définissez "background": "transparent" avec "output_format": "png" (ou "webp").

Pourquoi ai-je reçu additional properties 'size' not allowed ? Le schéma est strict. Utilisez aspect_ratio (qui accepte aussi des dimensions en pixels explicites comme 1024x1024) plutôt que le champ size.

Quelle est la durée de validité de l'URL de sortie ? Jusqu'à l'horodatage Unix expireAt de l'objet output[0]. Téléchargez ou copiez le fichier dans votre propre stockage avant cette date — hiapi ne servira plus le fichier ensuite.

Faut-il encore interroger la tâche si un callback est configuré ? Non, mais vous pouvez toujours le faire — GET /v1/tasks/:id fonctionne normalement, que le callback soit configuré ou non ; cela peut servir à vérifier manuellement si votre endpoint de callback a manqué une livraison.

Que se passe-t-il si ma requête contient à la fois input_urls et un prompt erroné ? La validation s'exécute sur l'ensemble du corps de requête avant la création de la tâche — tout champ invalide (y compris un tableau de médias mal formé) renvoie 400, et aucune tâche n'est créée (et rien n'est facturé).