API GPT Image 2 : guide complet (Python, Node.js, Curl)

Si vous voulez intégrer GPT Image 2 dans votre propre produit, pipeline d'automatisation ou workflow de génération par lot, l'API est la seule voie. Ce guide couvre tout ce dont vous avez besoin — authentification, paramètres, exemples de code pour Python et Node.js, édition d'images, gestion des erreurs et optimisation des coûts.

À la fin, vous aurez une intégration GPT Image 2 fonctionnelle capable de gérer un vrai trafic de production.

Prérequis

Avant de commencer :

1. Un compte développeur OpenAI (platform.openai.com)
2. Un compte de facturation alimenté (la génération d'images est payante ; les nouveaux comptes peuvent recevoir des crédits d'essai)
3. Une clé API — générez-en une sur platform.openai.com/api-keys
4. Python 3.8+ ou Node.js 18+ selon le SDK que vous voulez utiliser

Accès API stable pour les équipes en production

Si votre équipe est dans une région où l'accès direct à OpenAI est instable, ou si vous avez besoin d'un relais unique qui gère le failover, l'agrégation de facturation et les garanties SLA, vous pouvez aussi obtenir une clé API GPT Image 2 managée en écrivant à support@gpt-image2.art. Le relais prend en charge le même nom de modèle gpt-image-2, les mêmes paramètres décrits ci-dessous, et le même format de réponse — votre code n'a donc pas besoin de changer.

Étape 1 : Installer le SDK

Python

pip install openai pillow

pillow est optionnel, nécessaire uniquement si vous prévoyez de faire du post-traitement sur l'image retournée.

Node.js

npm install openai
# or
pnpm add openai

Étape 2 : Configurer votre clé API

N'écrivez jamais votre clé API en dur. Utilisez une variable d'environnement.

Créez un fichier .env :

OPENAI_API_KEY=sk-proj-your-key-here

Puis chargez-le dans votre code (Python utilise python-dotenv, Node.js charge .env nativement ou avec dotenv).

Étape 3 : Générer votre première image

Python — exemple minimal fonctionnel

import os
from openai import OpenAI
import base64

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

result = client.images.generate(
    model="gpt-image-2",
    prompt="A white stainless steel water bottle on a beige linen tablecloth, premium product photography, 1:1 aspect ratio.",
    size="1024x1024",
    quality="medium",
    n=1,
)

# Image is returned as base64
image_b64 = result.data[0].b64_json
with open("output.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

print("Saved to output.png")

Node.js — exemple minimal fonctionnel

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt:
    'A white stainless steel water bottle on a beige linen tablecloth, premium product photography, 1:1 aspect ratio.',
  size: '1024x1024',
  quality: 'medium',
  n: 1,
});

const imageB64 = result.data[0].b64_json;
fs.writeFileSync('output.png', Buffer.from(imageB64, 'base64'));
console.log('Saved to output.png');

Curl — pour scripts shell et tests rapides

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 white stainless steel water bottle on a beige linen tablecloth.",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

Tous les paramètres expliqués

Édition d'images — la fonctionnalité tueuse

L'édition dirigée de GPT Image 2 est son plus gros avantage API sur les modèles de diffusion. Vous uploadez une image existante et un prompt décrivant ce qu'il faut changer.

Python

result = client.images.edit(
    model="gpt-image-2",
    image=open("original.png", "rb"),
    prompt="Change the bottle's color from white to navy blue. Keep everything else identical.",
    size="1024x1024",
    quality="medium",
)

with open("edited.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

Node.js

import { toFile } from 'openai';

const result = await client.images.edit({
  model: 'gpt-image-2',
  image: await toFile(fs.createReadStream('original.png'), 'original.png'),
  prompt:
    "Change the bottle's color from white to navy blue. Keep everything else identical.",
  size: '1024x1024',
  quality: 'medium',
});

La phrase "Keep everything else identical" dans le prompt est critique — sans elle, le modèle peut régénérer des zones non liées.

Génération par lot avec concurrence sécurisée contre les rate limits

Ne faites pas naïvement Promise.all() sur 100 requêtes — vous allez taper le rate limit. Utilisez une concurrence bornée.

Python — avec asyncio et un semaphore

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def generate_one(prompt: str, semaphore: asyncio.Semaphore):
    async with semaphore:
        result = await client.images.generate(
            model="gpt-image-2",
            prompt=prompt,
            size="1024x1024",
            quality="medium",
        )
        return result.data[0].b64_json

async def batch_generate(prompts: list[str], concurrency: int = 5):
    semaphore = asyncio.Semaphore(concurrency)
    tasks = [generate_one(p, semaphore) for p in prompts]
    return await asyncio.gather(*tasks)

results = asyncio.run(batch_generate(["prompt 1", "prompt 2", ...]))

Node.js — avec p-limit

import pLimit from 'p-limit';

const limit = pLimit(5); // 5 concurrent requests

const tasks = prompts.map((prompt) =>
  limit(async () => {
    const result = await client.images.generate({
      model: 'gpt-image-2',
      prompt,
      size: '1024x1024',
      quality: 'medium',
    });
    return result.data[0].b64_json;
  })
);

const results = await Promise.all(tasks);

Gestion des erreurs en production

L'API peut échouer de plusieurs manières distinctes. Gérez chacune :

from openai import OpenAI, APIError, RateLimitError, APIConnectionError, BadRequestError

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def safe_generate(prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            result = client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="medium",
            )
            return result.data[0].b64_json

        except RateLimitError:
            # 429 — wait and retry
            wait = (2 ** attempt) * 5
            print(f"Rate limited; waiting {wait}s")
            time.sleep(wait)

        except BadRequestError as e:
            # 400 — usually a content policy violation, don't retry
            print(f"Bad request: {e}")
            return None

        except APIConnectionError:
            # network blip — retry
            time.sleep(2 ** attempt)

        except APIError as e:
            # 500-level — retry with backoff
            time.sleep(2 ** attempt)

    return None

Optimisation des coûts — tactiques concrètes

1. Choisir le bon tier de qualité

La plupart des équipes surpaient en mettant high par défaut. Utilisez medium pour environ 95 % du travail.

2. Itérez avec images.edit, pas images.generate

Une édition dirigée coûte autant qu'une génération, mais atterrit sur le bon résultat en 1 tentative au lieu de 5. Pour le raffinement multi-tours, c'est une économie de coût de 5×.

3. Cachez de manière déterministe quand les prompts se répètent

Si vous générez le même prompt à répétition (par exemple, des aperçus produit côté utilisateur), cachez par hash(prompt + size + quality) et servez depuis votre CDN.

4. Utilisez low pour l'exploration de prompts, puis upgrade

Un workflow courant :

# Step 1: try 5 prompt variants at low quality ($0.05 total)
candidates = [generate(p, quality="low") for p in variants]

# Step 2: pick the best, regenerate at high quality
best_prompt = pick_winner(candidates)
final = generate(best_prompt, quality="high")  # $0.167

Coût total : ~0,22 $ au lieu de ~0,84 $ si vous aviez lancé les 5 variantes en high.

5. Définissez des plafonds de dépense durs dans le dashboard OpenAI

Ne faites pas confiance à votre code pour ne jamais buguer — définissez un plafond d'usage sur platform.openai.com/account/billing/limits.

Statut de génération en streaming (optionnel)

Pour les longs batches, vous pourriez vouloir afficher la progression. L'endpoint de génération d'images n'est pas en streaming, mais vous pouvez envelopper votre batch dans un reporting de progression asynchrone :

let completed = 0;
const tasks = prompts.map((prompt) =>
  limit(async () => {
    const result = await client.images.generate({ /* ... */ });
    completed++;
    onProgress({ completed, total: prompts.length });
    return result.data[0].b64_json;
  })
);

Erreurs d'intégration courantes

Checklist prête pour la production

Avant de livrer une intégration GPT Image 2 :

• Clé API en variable d'environnement, jamais dans le code ou les logs
• Tier de qualité approprié au cas d'usage (par défaut medium)
• Concurrence bornée (p-limit / Semaphore) pour les jobs de batch
• La gestion des erreurs distingue 4xx vs 5xx
• Plafond de dépense dur défini dans le dashboard OpenAI
• Input utilisateur sanitisé pour les violations de politique de contenu
• Sortie stockée sur votre propre stockage (sans dépendre des URLs OpenAI)
• Couche de cache pour les prompts répétés
• Monitoring sur le coût par image et le taux d'erreur

Génération asynchrone avec polling de tâche (pour les setups haute concurrence)

Pour les workloads de production à fort volume, certains relais GPT Image 2 offrent un modèle de tâche async : vous soumettez la requête, recevez un ID de tâche immédiatement, et soit pollez la complétion soit recevez un callback. Cela évite les timeouts HTTP sur les grands batches.

Flux async typique :

# 1. Submit request → get task_id
response = client.images.generate(
    model="gpt-image-2",
    prompt="...",
    size="1024x1024",
    quality="high",
    callback_url="https://your-app.com/api/image-callback",  # optional
)
task_id = response.id

# 2. Poll task status every few seconds
while True:
    status = client.images.retrieve(task_id)
    if status.status == "completed":
        image_url = status.data[0].url
        break
    elif status.status == "failed":
        raise Exception(status.error)
    time.sleep(3)

Le mode async est idéal pour :

• Boutiques e-commerce générant des centaines de variantes produit pendant la nuit
• Équipes marketing lançant des tests A/B de prompts
• Apps où les utilisateurs demandent des images et reviennent plus tard (notifications)

FAQ de l'API GPT Image 2

Q : Quel est le nom du modèle de l'API GPT Image 2 ? gpt-image-2. Utilisez exactement cette chaîne pour toutes les requêtes.

Q : L'API GPT Image 2 prend-elle en charge l'image-to-image / édition d'image ? Oui. Utilisez images.edit avec le paramètre image, ou passez image_urls (tableau de 1-16 images de référence) aux relais qui le supportent. Les images de référence sont essentielles pour la cohérence de personnage, le design d'IP et la photographie produit.

Q : L'API GPT Image 2 est-elle gratuite ? Non, elle est payante par token. Les nouveaux comptes OpenAI peuvent recevoir des crédits d'essai. Certains relais tiers offrent des crédits d'essai gratuits.

Q : Combien coûte l'API GPT Image 2 par image ? Environ 0,011 $ / 0,042 $ / 0,167 $ par image 1024×1024 en qualité low / medium / high respectivement. Les plus grandes tailles et les images de référence coûtent plus cher.

Q : Quelle est la longueur maximale de prompt ? Jusqu'à 32 000 caractères. En pratique, les prompts au-dessus d'environ 1 500 caractères montrent des rendements décroissants.

Q : Comment générer des PNG à fond transparent avec l'API ? Définissez background: "transparent" et output_format: "png".

Q : Quelles résolutions GPT Image 2 prend-il en charge ? Presets courants : 1024x1024, 1536x1024, 1024x1536. Certains relais exposent des niveaux de résolution 1K / 2K / 4K pour un contrôle explicite.

Q : Quel est le rate limit ? Cela dépend de votre tier OpenAI. Le tier gratuit a les limites les plus strictes ; le tier d'usage augmente avec le temps. Utilisez une concurrence bornée (p-limit / Semaphore) pour rester sous la limite.

Q : Comment gérer les erreurs de l'API GPT Image 2 ? Distinguez 4xx (pas de retry — habituellement des violations de politique de contenu) de 5xx (retry avec backoff exponentiel). Voir la section gestion d'erreurs ci-dessus.

Q : Puis-je annuler une requête API GPT Image 2 en cours ? Pour les requêtes sync, uniquement en fermant la connexion. Les relais async exposent un endpoint cancel qui fonctionne tant que la tâche est encore en file d'attente.

Q : L'API prend-elle en charge le streaming ? La génération d'image elle-même n'est pas en streaming (vous obtenez l'image complète à la fin). Pour une UI de progression, enveloppez votre batch dans un reporter de progression personnalisé (voir "Statut de génération en streaming" ci-dessus).

Vous voulez un exemple d'application fonctionnel ?

Pour une implémentation de référence complète — Next.js + GPT Image 2 + Stripe + stockage d'images — explorez gpt-image2.art et la page explore qui montre de vrais rendus.

Besoin d'une clé API managée avec SLA ?

Si vous préférez sauter la configuration de compte, la facturation, les problèmes régionaux et le tuning de rate limit, vous pouvez acheter une clé API GPT Image 2 managée en écrivant à support@gpt-image2.art. Nous fournissons :

• Un endpoint API stable avec failover intégré
• Facturation agrégée dans votre devise locale (pas de virement USD requis)
• Mode tâche asynchrone + support de callback prêt à l'emploi
• Tarifs au volume pour les équipes générant > 10 000 images/mois
• Même nom de modèle gpt-image-2 et même spec de paramètres que l'API officielle — drop-in compatible

Pour aller plus loin

• Guide d'écriture de prompts GPT Image 2 — 7 règles qui font passer le taux de réussite de 30 % à 90 %
• Bibliothèque de styles GPT Image 2 — 12 prompts artistiques prêts pour la production
• Qu'est-ce que GPT Image 2 ? Une introduction complète