Antoine Laurent

Posted on Apr 22 • Originally published at apidog.com

Comment utiliser l'API gpt-image-2 ?

L'API gpt-image-2 est le nouveau point d'accès de génération d’images d’OpenAI, lancée avec ChatGPT Images 2.0 le 21 avril 2026. Si vous utilisez déjà les API de chat ou d'embeddings d’OpenAI, intégrer la génération d’images prend moins de dix minutes : il suffit d’ajouter une nouvelle requête, une clé API avec le scope adapté, et quelques ajustements de paramètres.

Essayez Apidog dès aujourd’hui

Ce guide se concentre sur l’implémentation API : authentification, paramètres de requête, exemples en Python/TypeScript/Bash, gestion du mode de réflexion, génération par lots, parsing des réponses, gestion des erreurs, limites de débit, et workflow de test pour éviter de gaspiller des crédits sur des invites mal formées. Pour une vue produit de ChatGPT Images 2.0, consultez notre analyse de ChatGPT Images 2.0.

À la fin, vous aurez des appels fonctionnels, une collection Apidog réutilisable, et une vision claire du coût de chaque paramètre.

Prérequis

Avant d’appeler l’API pour la première fois :

Compte OpenAI avec accès API : Les comptes développeurs sont distincts de ChatGPT Plus ; un abonnement ChatGPT ne donne pas accès à l’API.
Niveau d’utilisation facturable : gpt-image-2 nécessite le niveau 1 minimum. Passez du niveau Gratuit en ajoutant un moyen de paiement.
Clé API avec le scope images:write : Préférez les clés projet pour la production.
Outil de test d’API capable de prévisualiser les images : Un curl suffit pour débuter, mais un client API (voir plus bas) est recommandé ensuite.

Définissez la clé dans votre shell pour exécuter tous les exemples :

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

Point d’accès et Authentification

Envoyez une requête POST à l’endpoint images d’OpenAI :

POST https://api.openai.com/v1/images/generations

Authentifiez-vous via l’en-tête Authorization: Bearer $OPENAI_API_KEY. Le corps de la requête est en JSON, avec au minimum :

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A sharp product hero image for an API testing platform, dark background",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

Si la requête réussit, la réponse contient un objet JSON avec un tableau data d’images générées. En cas d’erreur, vérifiez le code et le message ; consultez la section erreurs plus bas.

Paramètres de requête

Chaque champ du JSON influence le rendu et la facturation. Voici la matrice des paramètres pour gpt-image-2 :

Paramètre	Type	Valeurs	Remarques
`model`	chaîne	`gpt-image-2`	Obligatoire.
`prompt`	chaîne	Jusqu’à 32 000 caractères	Obligatoire. Plus l’invite est longue, plus elle coûte de jetons d’entrée.
`size`	chaîne	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Influence le coût (jetons de sortie).
`quality`	chaîne	`standard`, `high`	`high` = coût x2, meilleur rendu de texte et UI.
`n`	entier	1–10	Génération en lot : cohérence de style.
`thinking`	chaîne	`off`, `low`, `medium`, `high`	Quantité de raisonnement préalable.
`response_format`	chaîne	`url`, `b64_json`	Les URL expirent en 1h.
`user`	chaîne	Forme libre	Pour détection d’abus : passez un ID haché.
`background`	chaîne	`auto`, `transparent`, `opaque`	PNG alpha si transparent.
`seed`	entier	int32	Non déterministe : même seed + même invite ≈ proche, pas identique.

Les paramètres qui impactent le plus le coût : size, quality, thinking. Par exemple, une image high de 2000px avec thinking: "high" coûte ~4–5× plus qu’un rendu 1024x1024 standard.

Exemple Python

Utilisez le SDK officiel openai>=1.50.0 :

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "A minimalist diagram of an OAuth 2.1 authorization code flow with PKCE. "
        "Five boxes labeled in English: User, Client, Auth Server, Resource Server, Token. "
        "Sharp sans-serif text, off-white background, teal accent arrows."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Généré {len(response.data)} images dans {out_dir.resolve()}")

Points clés :

response.data est toujours une liste, même si n=1 : bouclez systématiquement.
b64_json simplifie le stockage local ; utilisez url si vous transférez vers du CDN ou S3.

Exemple Node.js / TypeScript

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

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI mockup for a REST client, sentence-case labels, latency sparkline in the top-right, cool grey palette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Enregistré ${response.data.length} images`);

Utilisez le SDK officiel pour profiter de la gestion des retries, des en-têtes idempotents et du streaming. Evitez le fetch brut sauf besoin précis.

Mode de réflexion : quand l’utiliser

Le paramètre thinking module le temps de planification avant rendu :

off : Pas de raisonnement ; rapide et économique. Idéal pour créations libres.
low : Légère planification ; bon par défaut pour produits, headers.
medium : Raisonnement poussé ; pour diagrammes, infographies, contenus structurés.
high : Raisonnement maximal ; utile pour mises en page multilingues ou schémas techniques stricts.

Astuce : Si l’invite impose des contraintes (nombre, étiquette, disposition), montez d’un cran. Pour des scènes libres, restez bas.

Le mode thinking ajoute des jetons de calcul : prévoyez 1,2 à 2× le coût de base en medium/high. Consultez la tarification OpenAI.

Génération par lots

Spécifiez n > 1 pour générer plusieurs images partageant composition et style :

response = client.images.generate(
    model="gpt-image-2",
    prompt="Four different hero illustrations for an API documentation landing page, shared color palette, shared line weight.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

Le coût est multiplié par n (ex : n=4 = 4×). L’intérêt : cohérence du rendu, utile pour itérer ou choisir la meilleure version.

Format de réponse et stockage

b64_json : image encodée dans la réponse, idéale pour scripts et stockage local. Attention à la taille (>3 Mo pour du 2000px HQ).
url : image hébergée 1h sur le CDN OpenAI. À télécharger puis stocker sur S3, R2, Cloudflare Images, etc. N’exposez pas ces URL aux utilisateurs.

Gestion des erreurs et limites de débit

Principaux codes d’erreur :

HTTP	`code`	Cause	Correction
400	`invalid_request_error`	Taille non supportée, invite >32k caractères	Vérifiez taille/invite.
401	`invalid_api_key`	Clé absente ou incorrecte	Redéfinir `OPENAI_API_KEY`.
403	`insufficient_quota`	Pas de crédits, niveau Gratuit	Ajouter facturation.
429	`rate_limit_exceeded`	Trop de requêtes/min	Pause, puis retry avec `Retry-After`.
429	`image_generation_user_error`	Non-respect politique de contenu	Reformuler l’invite.
500	`server_error`	Incident transitoire OpenAI	Retry exponentiel.
503	`overloaded`	Surcharge régionale	Attendre, puis retry.

Limites de débit : au niveau 1, ~50 requêtes/minute. Consultez systématiquement les en-têtes x-ratelimit-remaining-requests/tokens pour adapter votre cadence.

Gestion automatique des retries (Python) :

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

Ne réessayez jamais les erreurs 400, 401 ou 429 (policy) : elles sont fatales et coûtent des crédits à chaque tentative.

Tester l’API avec Apidog

Itérer sur les invites via terminal est lent : pas de preview, pas de comparaison facile, difficile de versionner. Utilisez un client API graphique :

Apidog traite gpt-image-2 en requête native. Workflow type :

Créez une requête POST https://api.openai.com/v1/images/generations dans votre collection OpenAI.
Ajoutez l’en-tête Authorization: Bearer {{OPENAI_API_KEY}} et définissez la variable d’environnement.
Collez votre JSON ; Apidog valide le schéma avant envoi.
Cliquez sur Envoyer : les images s’affichent inline, versionnez les invites, dupliquez pour variantes.
Définissez plusieurs environnements (thinking: off, medium, high) pour comparer le même prompt selon le mode.

La comparaison directe d’images et la bibliothèque d’invites partagée accélèrent toute l’itération. Le terminal ne propose rien d’équivalent.

Si vous quittez Postman ou un client HTTP classique, téléchargez Apidog et configurez-le avec votre clé OpenAI : installation rapide. Pour aller plus loin, consultez notre guide sur le test d’API sans Postman ou notre aperçu de l’extension VS Code.

Pièges courants

Évitez ces erreurs lors des premiers tests avec gpt-image-2 :

Ne pas utiliser quality: "standard" pour du texte : Passez à high pour des labels, icônes ou textes UI nets.
Invites trop longues : Plafond à 32 k, mais ciblez <500 mots. Au-delà, le modèle ignore les instructions du début.
Espérer une reproductibilité parfaite avec seed : Mettez le fichier en cache si besoin, ne relancez pas la génération.
Livrer les URL OpenAI : Elles expirent sous 1h. Téléchargez et stockez vos images en interne.
Boucles séquentielles sans gestion de débit : Parallélisez ou respectez les headers de rate limit ; sinon, vous risquez timeout et files d’attente.

FAQ

En quoi gpt-image-2 diffère-t-il de gpt-image-1 côté API ?

Même endpoint, même auth. Nouveaux paramètres : thinking (off/low/medium/high), tailles supplémentaires (size jusqu’à 2000px), n jusqu’à 10. Les SDK existants fonctionnent après changement d’ID de modèle. Pour le détail : aperçu ChatGPT Images 2.0.

Comment prototyper rapidement une intégration gpt-image-2 ?

Créez une requête dans Apidog, paramétrez deux environnements (standard vs thinking), itérez visuellement, puis exportez en code une fois validé.

L’API supporte-t-elle l’édition ou l’inpainting ?

Les endpoints d’édition et variation suivent le même schéma sous le nouvel ID de modèle. Voir la référence du modèle gpt-image-2 pour les paramètres masques/images d’entrée.

Utilisation commerciale possible ?

Oui, selon les politiques OpenAI : vous possédez les images générées, OpenAI peut analyser entrées/sorties pour la détection d’abus. Les personnages sous copyright ou célébrités déclenchent toujours des garde-fous.

Quel coût pour la production ?

~0,21 $ par image HQ 1024×1024 en mode standard ; 10 000 images/mois ≈ 2 100 $ sans réflexion. Ajoutez 20–80 % pour le mode thinking. Comparez avec des alternatives auto-hébergées : GLM 5V Turbo, Qwen 3.5 Omni si budget serré.

Existe-t-il une alternative open source avec rendu texte équivalent ?

Pas encore au même niveau, surtout pour le texte multilingue : les modèles open-weight progressent sur la composition, mais restent inférieurs pour le texte CJK et indien.