API GPT Image 2: guida completa (Python, Node.js, Curl)

Se vuoi integrare GPT Image 2 nel tuo prodotto, in una pipeline di automazione o in un workflow di generazione in batch, l'API è l'unica strada. Questa guida copre tutto quello che ti serve — autenticazione, parametri, esempi di codice per Python e Node.js, modifica di immagini, gestione degli errori e ottimizzazione dei costi.

Alla fine avrai un'integrazione GPT Image 2 funzionante in grado di gestire traffico reale di produzione.

Prerequisiti

Prima di iniziare:

1. Un account sviluppatore OpenAI (platform.openai.com)
2. Un account di billing alimentato (la generazione immagini è a pagamento; i nuovi account possono ricevere crediti di prova)
3. Una chiave API — generane una su platform.openai.com/api-keys
4. Python 3.8+ o Node.js 18+ a seconda di quale SDK vuoi usare

Accesso API stabile per team di produzione

Se il tuo team è in una regione dove l'accesso diretto a OpenAI è instabile, o hai bisogno di un singolo relay che gestisca failover, aggregazione di billing e SLA, puoi ottenere anche una chiave API GPT Image 2 gestita scrivendo a support@gpt-image2.art. Il relay supporta lo stesso nome di modello gpt-image-2, gli stessi parametri descritti sotto e lo stesso formato di risposta — così il tuo codice non deve cambiare.

Step 1: Installa l'SDK

Python

pip install openai pillow

pillow è opzionale, serve solo se pianifichi un post-processing sull'immagine restituita.

Node.js

npm install openai
# or
pnpm add openai

Step 2: Configura la tua chiave API

Non scrivere mai la chiave API in chiaro nel codice. Usa una variabile d'ambiente.

Crea un file .env:

OPENAI_API_KEY=sk-proj-your-key-here

Poi caricala nel codice (Python usa python-dotenv, Node.js carica .env in modo nativo o con dotenv).

Step 3: Genera la tua prima immagine

Python — esempio minimo funzionante

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 — esempio minimo funzionante

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 — per script di shell e test veloci

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
  }'

Tutti i parametri spiegati

Modifica di immagini — la killer feature

L'editing guidato di GPT Image 2 è il suo più grande vantaggio API rispetto ai modelli diffusion. Carichi un'immagine esistente e un prompt che descrive cosa cambiare.

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 frase "Keep everything else identical" nel prompt è critica — senza, il modello può rigenerare aree non correlate.

Generazione in batch con concorrenza sicura rispetto ai rate limit

Non fare ingenuamente Promise.all() su 100 richieste — sbatti contro i rate limit. Usa concorrenza limitata.

Python — usando asyncio con un semaforo

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 — usando 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);

Gestione degli errori per la produzione

L'API può fallire in diversi modi distinti. Gestiscili tutti:

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

Ottimizzazione dei costi — tattiche concrete

1. Scegli il tier di qualità giusto

La maggior parte dei team paga di più perché va di default su high. Usa medium per ~95% del lavoro.

2. Itera con images.edit, non con images.generate

Una modifica guidata costa quanto una generazione, ma ottiene il risultato giusto in 1 tentativo invece che in 5. Per il rifinimento multi-round è un risparmio di costo 5×.

3. Fai cache in modo deterministico quando i prompt si ripetono

Se generi lo stesso prompt ripetutamente (es. anteprime di prodotto per utenti), fai cache con chiave hash(prompt + size + quality) e servi dal tuo CDN.

4. Usa low per l'esplorazione di prompt, poi fai l'upgrade

Un workflow comune:

# 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

Costo totale: ~0,22$ invece di ~0,84$ se avessi lanciato tutte e 5 le varianti in high.

5. Imposta tetti di spesa duri nella dashboard OpenAI

Non fidarti che il tuo codice non vada mai in bug — imposta un cap di utilizzo su platform.openai.com/account/billing/limits.

Stato di generazione in streaming (opzionale)

Per batch lunghi, potresti voler mostrare il progresso. L'endpoint di generazione immagini non è in streaming, ma puoi avvolgere il batch in un reporting di progresso asincrono:

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;
  })
);

Errori comuni di integrazione

Checklist pronta per la produzione

Prima di pubblicare un'integrazione GPT Image 2:

• Chiave API in variabile d'ambiente, mai nel codice o nei log
• Tier di qualità appropriato al caso d'uso (default su medium)
• Concorrenza limitata (p-limit / Semaphore) per i batch
• La gestione errori distingue 4xx vs 5xx
• Tetto di spesa duro impostato nella dashboard OpenAI
• Input utente sanificato per le violazioni della content policy
• Output salvato sul tuo storage (non affidato agli URL OpenAI)
• Layer di cache per i prompt ripetuti
• Monitoring su costo per immagine ed error rate

Generazione asincrona con polling dei task (per setup ad alta concorrenza)

Per carichi di produzione ad alto volume, alcuni relay GPT Image 2 offrono un modello di task asincrono: invii la richiesta, ricevi subito un task ID e poi fai polling per il completamento o ricevi una callback. Questo evita i timeout HTTP sui batch grandi.

Flusso asincrono tipico:

# 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)

La modalità asincrona è ideale per:

• E-commerce che generano 100 di varianti di prodotto in overnight
• Team marketing che fanno test A/B di prompt
• App dove gli utenti richiedono immagini e tornano dopo (notifiche)

FAQ API GPT Image 2

Q: Qual è il nome del modello API di GPT Image 2? gpt-image-2. Usa esattamente questa stringa per tutte le richieste.

Q: L'API di GPT Image 2 supporta image-to-image / modifica di immagini? Sì. Usa images.edit con il parametro image, o passa image_urls (array di 1-16 immagini di riferimento) ai relay che lo supportano. Le immagini di riferimento sono essenziali per coerenza dei personaggi, design IP e fotografia di prodotto.

Q: L'API di GPT Image 2 è gratis? No, è a pagamento per token. I nuovi account OpenAI possono ricevere crediti di prova. Alcuni relay di terze parti offrono crediti di prova gratuiti.

Q: Quanto costa per immagine l'API di GPT Image 2? Circa 0,011$ / 0,042$ / 0,167$ per immagine 1024×1024 a qualità low / medium / high rispettivamente. Dimensioni maggiori e immagini di riferimento costano di più.

Q: Qual è la lunghezza massima del prompt? Fino a 32.000 caratteri. In pratica, i prompt oltre i ~1.500 caratteri mostrano rendimenti decrescenti.

Q: Come genero PNG con sfondo trasparente con l'API? Imposta background: "transparent" e output_format: "png".

Q: Quali risoluzioni supporta GPT Image 2? Preset comuni: 1024x1024, 1536x1024, 1024x1536. Alcuni relay espongono i livelli di risoluzione 1K / 2K / 4K per controllo esplicito.

Q: Qual è il rate limit? Dipende dal tuo tier OpenAI. Il tier free ha i limiti più stretti; il tier d'uso scala nel tempo. Usa concorrenza limitata (p-limit / Semaphore) per restare sotto il limite.

Q: Come gestisco gli errori dell'API GPT Image 2? Distingui 4xx (non riprovare — di solito violazioni della content policy) da 5xx (riprova con exponential backoff). Vedi la sezione di gestione errori sopra.

Q: Posso cancellare una richiesta API GPT Image 2 in volo? Per le richieste sync, solo chiudendo la connessione. I relay asincroni espongono un endpoint cancel che funziona finché il task è ancora in coda.

Q: L'API supporta lo streaming? La generazione immagini in sé non è in streaming (ricevi l'immagine completa alla fine). Per una UI di progresso, avvolgi il batch in un reporter di progresso custom (vedi sopra "Stato di generazione in streaming").

Vuoi un'app di esempio funzionante?

Per un'implementazione di riferimento completa — Next.js + GPT Image 2 + Stripe + storage immagini — esplora gpt-image2.art e la pagina explore che mostra output reali.

Hai bisogno di una chiave API gestita con SLA?

Se preferisci saltare la configurazione dell'account, il billing, i problemi di regione e il tuning dei rate limit, puoi acquistare una chiave API GPT Image 2 gestita scrivendo a support@gpt-image2.art. Forniamo:

• Un endpoint API stabile con failover integrato
• Billing aggregato nella tua valuta locale (nessun bonifico in USD richiesto)
• Modalità task asincrona + supporto callback out-of-the-box
• Pricing a volume per team che generano > 10K immagini/mese
• Stesso nome di modello gpt-image-2 e specifica dei parametri dell'API ufficiale — compatibile drop-in

Approfondimenti

• Guida alla scrittura dei prompt per GPT Image 2 — 7 regole che portano il tasso di successo dal 30% al 90%
• GPT Image 2 Style Library — 12 prompt di stili artistici pronti per la produzione
• Cos'è GPT Image 2? Un'introduzione completa