Intégration de l'API GPT Image 2.5 : génération, édition et migration depuis Image 2

Pour intégrer GPT Image 2.5 sur HiAPI, choisissez d'abord gpt-image-2.5-flare ou gpt-image-2.5-sunburst, puis soumettez une tâche via POST /v1/tasks. Les deux modèles prennent en charge la génération et l'édition ; la présence ou non de image_urls détermine si la requête comporte une image de référence.

Lors d'une migration depuis Image 2, il faut modifier à la fois le nom du modèle et les paramètres d'entrée. L'ancienne version utilisait des conventions différentes pour resolution, size, les champs d'image de référence et la configuration des routes ; remplacer uniquement la chaîne du modèle risque de laisser des paramètres inadaptés.

Les exemples de code ci-dessous sont rédigés d'après la documentation en ligne HiAPI du 9 septembre 2026 ; ils illustrent la requête et le traitement asynchrone, tandis que les sorties réelles et les coûts font foi dans l'enregistrement de la tâche. Les mises à jour de paramètres sont à consulter dans la documentation Flare et la documentation Sunburst.

Un seul ID de modèle pour la génération et l'édition

Flare et Sunburst utilisent les mêmes champs de requête sur HiAPI. Une fois le modèle choisi, la génération purement textuelle omet image_urls ; pour l'édition, ajoutez 1 à 16 images de référence et précisez dans le prompt ce qui doit être modifié et ce qui doit être conservé. N'envoyez pas de tableau vide pour une génération purement textuelle, et n'ajoutez pas vous-même de suffixe /edit ou /text-to-image. Chaque tâche produit une image.

Si vous disposez déjà d'un flux de travail d'images stable, vous pouvez commencer par migrer un type de tâche en conservant les entrées et les critères d'acceptation existants. Pour le positionnement des deux modèles, consultez d'abord les différences entre Image 2 et 2.5 ; cet article se concentre sur la mise en œuvre concrète des requêtes.

Soumettre une requête de génération

L'exemple ci-dessous génère une photo produit carrée d'une tasse. Enregistrez le JSON sous request.json. quality est explicitement défini sur medium pour faciliter la reproduction ultérieure des paramètres ; aspect_ratio est défini sur la dimension en pixels listée dans la documentation, 1024x1024.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

La clé API se place dans la variable d'environnement côté serveur HIAPI_API_KEY. La commande suivante lit le fichier, soumet la requête et enregistre la réponse de création de tâche. HIAPI_REQUEST_ID est généré par votre application pour cette requête logique ; réutilisez-le en cas de nouvelle tentative pour cause de problème réseau sur la même requête, et utilisez une nouvelle valeur en cas de modification de l'entrée ou de création d'une autre image.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

Après une création réussie, lisez l'ID de tâche dans data.taskId de created.json. À ce stade, l'image est encore en cours de génération asynchrone. Idempotency-Key sert à éviter que des soumissions répétées d'une même requête logique ne créent plusieurs tâches ; les conventions complètes sont décrites dans la documentation de création de tâche. Ne considérez pas une soumission réussie comme une image terminée.

Éditer une image avec la même interface

Voici une requête d'édition Sunburst indépendante. Remplacez l'adresse fictive dans image_urls par une URL d'image de référence réelle accessible par le service, enregistrez sous request.json, puis soumettez avec un nouvel ID de requête. L'adresse example.com ne fait qu'illustrer la structure du champ et ne peut pas être utilisée directement pour générer.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Avec plusieurs images de référence, précisez leur usage dans l'ordre du tableau : par exemple, la première fournit le produit et la seconde le fond. Pour des modifications successives, utilisez la sortie enregistrée de l'étape précédente comme image de référence de la requête suivante ; chaque étape reste une nouvelle tâche et nécessite de préciser les nouvelles exigences de modification. Ne supposez pas que l'interface conserve automatiquement la conversation ou l'image du tour précédent.

Pour un fond transparent, définissez background sur transparent et choisissez PNG ou WebP. JPEG ne prend pas en charge le canal alpha. Après la sortie du modèle, vérifiez toujours les contours et le sujet ; le réglage des champs ne remplace pas la validation visuelle de l'image.

Interroger le statut, puis enregistrer le fichier

GET /v1/tasks/:id renvoie les détails de la tâche. queued, handling et archiving sont des états non terminaux ; seul success indique que la sortie est disponible, tandis que fail fournit des informations d'échec via data.error. Le code: 200 externe indique seulement que l'interrogation a réussi ; il faut continuer à évaluer data.status. Documentation des détails de tâche

L'exemple Python ci-dessous utilise requests, lit le created.json précédent, attend d'abord 3 secondes, puis interroge toutes les 4 secondes. Il enregistre le JSON de détail et la première image. Les 10 minutes correspondent à la limite d'attente locale de l'exemple ; elles ne représentent ni un SLA du service, ni une annulation de la tâche côté serveur. En cas de dépassement, conservez le taskId pour continuer à interroger la même tâche plus tard.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Les sorties temporaires doivent être téléchargées ou copiées avant output[].expireAt. Pour un service en production, configurez callback au niveau supérieur de la requête afin de recevoir les notifications d'état final, en conservant l'interrogation périodique comme solution de repli ; ne placez pas les champs de callback dans input. La vérification de signature des callbacks et le traitement des notifications en double s'implémentent selon l'API asynchrone unifiée. L'exemple n'inclut ni file d'attente métier, ni service de callback, ni stratégie complète de nouvelle tentative réseau.

Migrer depuis Image 2 en vérifiant chaque entrée

L'ancienne version Image 2 utilisait des routes différentes ; lors de la migration, vérifiez d'abord laquelle vous utilisez actuellement. Les différences de paramètres ci-dessous concernent la documentation HiAPI et ne s'appliquent pas au transfert tel quel de requêtes SDK d'autres fournisseurs.

Ancien flux de travail	Adaptation pour Image 2.5
La génération et l'édition utilisaient des ID de modèle Image 2 différents	Utilisez l'ID complet Flare ou Sunburst ; distinguez par la présence ou l'absence de image_urls
L'édition Standard utilisait input_urls	Remplacez par image_urls ; l'ancienne édition ext utilisait déjà ce champ
Standard / ext utilisaient resolution	Choisissez à nouveau un ratio ou une énumération de pixels dans aspect_ratio selon la dimension cible ; ne conservez pas resolution
La génération Beta utilisait size	Remplacez par une énumération de pixels aspect_ratio prise en charge par la documentation ; ne copiez pas directement une dimension arbitraire
route: "beta" / "ext" explicite, ou nom de modèle avec suffixe de route	Reconstruisez la requête selon la documentation du modèle 2.5 ; ne réutilisez pas les anciennes routes
Ratios comme 4:5 pris en charge par l'ancienne version	Vérifiez un par un ; l'énumération actuelle de 2.5 ne contient pas 4:5 ; ne le remplacez pas silencieusement par un autre ratio
Dépendance aux valeurs par défaut de qualité, dimension ou format de sortie	Spécifiez explicitement, et revérifiez la sortie, les coûts et le traitement des fichiers en aval

Les options de ratio actuelles de 2.5 sont 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 et auto. En outre, aspect_ratio accepte les 10 dimensions en pixels listées dans la documentation. Lorsque vous avez besoin d'une dimension fixe, choisissez une valeur d'énumération ; ne déduisez pas du simple format de chaîne que n'importe quel widthxheight est disponible. En particulier, auto est décrit dans la nouvelle documentation comme un choix de composition appropriée par le modèle ; ne reprenez pas directement l'hypothèse « suivre l'image d'entrée » de l'ancienne route d'édition.

Les options de qualité sont low, medium, high, xhigh, max, auto, avec medium par défaut. Un même niveau de qualité ne garantit pas des coûts ou un rendu visuel identiques à ceux de l'ancien modèle. Le protocole complet de l'ancienne version est disponible dans les documentations génération Image 2 et édition Image 2.

Erreurs et budget, dans la même chaîne de validation

Lors de la soumission, un 400 doit faire vérifier le nom du modèle, les champs et les énumérations ; un 402, le solde ; un 415, le Content-Type. Si un fail apparaît après la création de la tâche, enregistrez data.error pour diagnostiquer et ne soumettez pas à nouveau la même entrée invalide. Un 503 peut être retenté plus tard avec un backoff ; si un POST interrompu par le réseau ne permet pas de savoir si la tâche a été créée, réutilisez la clé d'idempotence d'origine pour éviter les tâches en double. Description des erreurs de création de tâche

La vérification des coûts commence par la page des tarifs actuels HiAPI et la page du modèle concerné. Le dossier d'acceptation de la migration doit consigner le modèle complet, la dimension, la qualité, le nombre d'images de référence, la requête, la sortie et la facture réelle ; ne réutilisez pas le prix unitaire de l'ancien Image 2 et ne prenez pas le prix de départ d'autres plateformes pour le tarif HiAPI. Les exemples d'images du site web peuvent aider à évaluer le rendu, mais les durées API et la facturation nécessitent leurs propres relevés réels.

Après avoir intégré, enregistré et validé une tâche de génération et une tâche d'édition, élargissez au traitement par lots. Vous pouvez consulter le point d'entrée actuel sur la page du modèle Flare ou la page du modèle Sunburst, puis maintenir les paramètres selon la documentation correspondante.