Comment utiliser l'API gpt-image-2.5 (Flare et Sunburst) avec curl, Python et Node.js

OpenAI a lancé ChatGPT Images 2.5 le 8 septembre 2026, avec deux nouveaux modèles d'API : gpt-image-2.5-flare et gpt-image-2.5-sunburst. Tous deux utilisent les mêmes points de terminaison que gpt-image-2, donc si vous avez suivi notre guide de l'API gpt-image-2, la majeure partie de votre code survivra à un changement d'ID de modèle. Ce qui a changé, c'est l'échelle de qualité et la façon dont l'API Responses vous permet de choisir un modèle par appel d'outil.

Ce guide couvre uniquement le parcours du développeur : les générations, les modifications multipartites avec une image de référence et un masque, l'outil de l'API Responses, le streaming et la lecture de l'utilisation (usage) pour le coût réel. Pour savoir ce que cette version signifie pour les utilisateurs de ChatGPT, lisez notre aperçu de ChatGPT Images 2.5 ; la publication de lancement d'OpenAI présente le cadre du produit. Chaque chiffre ci-dessous provient de la documentation d'OpenAI, de la page des tarifs ou du calculateur, tels que lus le 9 septembre 2026.

L'API gpt-image-2.5 en un coup d'œil

Les tarifs par jeton correspondent à ceux de gpt-image-2 ; le coût par image varie toujours car le nombre de jetons par niveau de qualité a changé.

Prérequis

• Un compte développeur OpenAI sur un niveau d'utilisation payant. Les points de terminaison d'image nécessitent le Niveau 1 ou supérieur, ce qui implique l'ajout d'un mode de paiement ; un abonnement ChatGPT ne compte pas. Notre guide détaillé sur la clé API OpenAI couvre les clés à portée de projet.
• Le SDK officiel openai pour Python ou Node.
• Un moyen de prévisualiser les réponses d'image. curl imprime du base64, ce qui est fastidieux pour l'itération ; Apidog affiche l'image décodée en ligne, et la dernière section déplace le flux de travail à cet endroit.

Exportez la clé une fois :

export OPENAI_API_KEY="sk-proj-..."

Générer une image avec curl

Utilisez Flare en premier ; la page du modèle d'OpenAI le qualifie de « choix par défaut pour la plupart des applications ».

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

La réponse contient un tableau `data` avec un `b64_json` par image, plus un objet `usage` avec `input_tokens` et `output_tokens`. Conservez `usage` ; c'est le seul signal de coût précis que vous obtenez. Notes sur les paramètres du guide de génération d'images : `output_format` est par défaut `png` et OpenAI indique que « l'utilisation de jpeg est plus rapide que png » ; `output_compression` (0-100) s'applique uniquement à jpeg et webp ; `background: "transparent"` échoue sur jpeg.

Python : générer, puis éditer avec une image de référence

L'appel du SDK reflète le corps de la requête curl. Décodez `b64_json` et écrivez les octets.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

Les modifications sont ce qui fait la valeur des modèles 2.5 ; la publication de lancement indique qu'ils sont « meilleurs pour éditer uniquement ce que vous avez demandé, tout en conservant les autres détails identiques », et OpenAI positionne Sunburst pour un « contrôle plus strict des modifications ». Le point de terminaison d'édition est multipartite : une image de référence, un masque facultatif et une invite. Là où le masque est transparent, le modèle repeint ; partout ailleurs, il conserve l'original.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

Supprimez `mask` et le modèle décide quoi modifier à partir de l'invite seule. L'image de référence est facturée en tant que jetons d'entrée d'image à 8 $ par million ; OpenAI ne publie pas de nombre de jetons d'entrée par image, alors lisez `usage.input_tokens`.

Node et TypeScript : écrire b64_json sur le disque

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

Épinglez `gpt-image-2.5-flare-2026-09-08` en production pour maintenir la stabilité de la sortie pendant que l'alias change.

API Responses : la génération d'images comme outil

Ici, un modèle principal lit votre invite, la révise et appelle l'outil `image_generation`. Vous choisissez le modèle d'image en définissant `model` dans la définition de l'outil ; le `model` de niveau supérieur doit être un modèle principal, et la documentation des outils d'OpenAI utilise `gpt-6-astra`. Notre guide de l'API Responses couvre la forme de la requête. Le champ `action` accepte `auto` (par défaut), `generate` ou `edit` ; définissez `edit` lorsque vous transmettez une image de référence et que vous souhaitez qu'elle soit modifiée, et non réinterprétée.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

Le suivi `previous_response_id` maintient la première image dans son contexte, de sorte que la « même scène » est résolue sans recharger le fichier. Les jetons du modèle principal sont facturés en plus des jetons d'image, et la réécriture de l'invite signifie que vous ne pouvez pas reproduire la sortie à partir du texte de l'invite seul.

Streaming d'images partielles

Les deux API acceptent `partial_images` (0 à 3). Chaque image partielle coûte 100 jetons de sortie supplémentaires, donc trois ajoutent 300 jetons, soit 0,009 $ par image. Utile pour une interface utilisateur qui affiche la progression ; gaspillé dans un traitement par lots.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

Les chaînes de type d'événement exactes se trouvent dans le guide de génération d'images ; la vérification du suffixe permet à la boucle de fonctionner sur les deux variantes de l'API. Pour inspecter les événements diffusés en dehors du code, consultez notre guide sur le test des réponses SSE des API d'IA.

Lire l'utilisation et convertir les jetons en dollars

Avertissement d'OpenAI : « Des tarifs de jetons égaux ne signifient pas un coût égal par image : la consommation de jetons peut différer selon le modèle et le réglage de qualité. » Le calculateur du guide de génération d'images fournit ces estimations pour les jetons de sortie d'image seuls, au tarif de 30 $ par million sur la page des tarifs :

Remarquez le changement d'étiquette. `high` sur la version 2.5 utilise 1 756 jetons, soit l'ancien budget `medium` sur `gpt-image-2` ; `max` utilise 7 024 jetons, soit l'ancien budget `high`. Maintenez `quality: "high"` lors d'une migration et chaque image devient environ 4 fois moins chère avec l'ancien budget `medium` ; pour l'ancien budget `high`, passez à `max`. Notre comparaison Flare vs Sunburst vs gpt-image-2 effectue le calcul mensuel complet.

Les chiffres du calculateur sont des estimations. Le coût réel provient de la réponse :

OUTPUT_RATE = 30 / 1_000_000  # dollars par jeton de sortie d'image
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} jetons = ${usd:.4f}")

Enregistrez-le par requête ; selon OpenAI, une taille non carrée plus grande peut produire moins de jetons qu'une taille carrée plus petite. Une question ouverte : l'onglet « Batch » de la page des tarifs ne répertorie que `gpt-image-2`, donc le support de l'API Batch pour la version 2.5 doit être considéré comme non confirmé.

Erreurs, limites de débit et délais d'expiration

• 429 limite de débit. Reculez avec un jitter et respectez `Retry-After`. Les pages des modèles 2.5 ne publient pas les limites par niveau. À titre de référence, `gpt-image-2` fonctionne au Niveau 1 à 5 images par minute et 100k TPM, et évolue jusqu'au Niveau 5 à 250 IPM et 8M TPM.
• `insufficient_quota`. Pas de crédits ou toujours sur le niveau gratuit. Ajoutez une facturation ; ne réessayez pas.
• Refus de modération. L'invite ou l'image de référence a déclenché le filtre. Reformulez au lieu de réessayer ; `moderation: "low"` assouplit le seuil.
• Délais d'expiration. OpenAI indique que « Les invites complexes peuvent prendre jusqu'à 2 minutes à traiter ». Définissez des délais d'expiration client supérieurs à cela ; Sunburst est conçu pour fonctionner plus longtemps que Flare.

Tester Flare et Sunburst côte à côte dans Apidog

L'itération en terminal sur les invites d'images est lente car vous ne pouvez pas voir la sortie, et une valeur de `quality` erronée coûte de l'argent réel à chaque envoi. Apidog est un client API et une plateforme de test : il envoie les appels et vérifie les réponses ; les serveurs d'OpenAI effectuent le rendu.

1. Stockez la clé une fois. Ajoutez `OPENAI_API_KEY` en tant que variable d'environnement et référencez-la comme `Bearer {{OPENAI_API_KEY}}` dans l'en-tête d'autorisation ; la clé n'est jamais enregistrée dans une requête sauvegardée.
2. Deux environnements, une seule requête. Créez des environnements nommés `flare` et `sunburst`, chacun avec une variable `MODEL`, et définissez `\"model\": \"{{MODEL}}\"` dans le corps. Basculez, renvoyez et comparez les images et l'utilisation (`usage`) côte à côte. Pour les modifications, utilisez un corps de requête de type form-data avec `image` et `mask` comme champs de fichier.
3. Décodez `b64_json` dans un post-traitement. Un court script extrait `data[0].b64_json`, le décode et enregistre le fichier, de sorte que chaque envoi produit une image visualisable à côté du JSON brut.
4. Affirmez le coût, puis planifiez-le. Affirmez que `usage.output_tokens` reste en dessous d'un budget, par exemple 2 000 pour un rendu `high` en 1536x1024, et exécutez la requête comme un test de régression chronométré. Si quelqu'un augmente la qualité à `max` ou si un instantané modifie le nombre de jetons, le test échoue avant que la facture ne soit émise.

Téléchargez Apidog, pointez-le vers votre clé OpenAI, et vous disposerez d'une bibliothèque d'invites partagée avec des garde-fous de coûts.

FAQ

• Dois-je modifier mon code gpt-image-2 pour utiliser la version 2.5 ? Échangez l'ID du modèle et revérifiez `quality`. Les points de terminaison, l'authentification et la forme de la réponse sont inchangés, mais `high` correspond désormais à un budget de jetons plus petit. Le guide de l'API gpt-image-2 couvre toujours l'ancien modèle.
• Flare ou Sunburst pour l'API ? Commencez avec Flare. OpenAI le positionne comme le modèle par défaut avec une « latence 50 % inférieure » à celle de `gpt-image-2` au même prix par jeton. Passez à Sunburst lorsque la précision des modifications est plus importante que la vitesse, comme pour les images de produits construites à partir de photos de référence. Les deux partagent les mêmes nombres de jetons du calculateur, donc le compromis est le temps, pas l'argent.
• Puis-je utiliser ces modèles dans les complétions de chat (Chat Completions) ? Non. La génération d'images réside sur l'API Image et l'outil `image_generation` de l'API Responses. Les complétions de chat ne l'exposent pas.
• Existe-t-il un moyen gratuit d'essayer la version 2.5 via l'API ? Il n'y a pas de niveau d'API gratuit perpétuel, et les points de terminaison d'image nécessitent le Niveau 1. Le chemin réel le moins cher est `quality: "low"` à 196 jetons, soit environ 0,006 $ par image 1024x1024. L'application grand public est une autre question ; consultez comment utiliser ChatGPT Images 2.5 gratuitement.

Où aller ensuite

Commencez par l'appel curl, confirmez `usage.output_tokens` par rapport au tableau du calculateur, puis déplacez la requête dans un client où vous pouvez voir l'image. L'article de Simon Willison montre Sunburst conservant un graphique intact tout en ajoutant un sujet ; testez ce comportement d'édition sur vos propres images de référence avant de vous engager.