API do GPT Image 2: Guia Completo (Python, Node.js, Curl)

Se você quer integrar a geração de imagens com IA do GPT Image 2 ao seu próprio produto, pipeline de automação ou workflow de geração em lote, a API é o único caminho. Este guia cobre tudo o que você precisa — autenticação, parâmetros, exemplos de código em Python e Node.js, edição de imagens, tratamento de erros e otimização de custos.

No final, você terá uma integração do GPT Image 2 funcionando que aguenta tráfego real de produção.

Pré-requisitos

Antes de começar:

1. Uma conta de desenvolvedor OpenAI (platform.openai.com)
2. Uma conta de cobrança com saldo (geração de imagem é paga; contas novas podem receber créditos de teste)
3. Uma chave de API — gere em platform.openai.com/api-keys
4. Python 3.8+ ou Node.js 18+ dependendo de qual SDK você quer usar

Acesso estável à API para times de produção

Se seu time está em uma região onde o acesso direto à OpenAI é instável, ou você precisa de um único relay que lida com failover, agregação de cobrança e garantias de SLA, você também pode obter uma chave de API gerenciada do GPT Image 2 mandando email para support@gpt-image2.art. O relay suporta o mesmo nome de modelo gpt-image-2, os mesmos parâmetros descritos abaixo e o mesmo formato de resposta — então seu código não precisa mudar.

Passo 1: Instale o SDK

Python

pip install openai pillow

pillow é opcional, só necessário se você planeja fazer pós-processamento na imagem retornada.

Node.js

npm install openai
# or
pnpm add openai

Passo 2: Configure sua chave de API

Nunca hard-code sua chave de API. Use uma variável de ambiente.

Crie um arquivo .env:

OPENAI_API_KEY=sk-proj-your-key-here

Em seguida carregue-o no seu código (Python usa python-dotenv, Node.js carrega .env nativamente ou com dotenv).

Passo 3: Gere sua primeira imagem

Python — exemplo mínimo funcional

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 — exemplo mínimo funcional

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 — para shell scripts e testes rápidos

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

Todos os parâmetros explicados

Edição de imagens — o recurso matador

A edição direcionada do GPT Image 2 é sua maior vantagem de API sobre modelos de difusão. Você sobe uma imagem existente e um prompt descrevendo o que mudar.

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

A frase "Keep everything else identical" no prompt é crítica — sem ela, o modelo pode regenerar regiões não relacionadas.

Geração em lote com concorrência segura para rate limits

Não dispare ingenuamente Promise.all() com 100 requisições — você vai bater rate limits. Use concorrência limitada.

Python — usando asyncio com semáforo

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

Tratamento de erros para produção

A API pode falhar de várias formas distintas. Trate cada uma:

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

Otimização de custo — táticas concretas

1. Escolha o tier de qualidade certo

A maioria dos times paga demais por usar high como padrão. Use medium para ~95% do trabalho.

2. Itere com images.edit, não com images.generate

Uma edição direcionada custa o mesmo que uma geração, mas chega no resultado certo em 1 tentativa em vez de 5. Para refinamento multi-rodada, isso é 5× de economia.

3. Faça cache determinístico quando prompts se repetem

Se você gera o mesmo prompt repetidamente (por exemplo, previews de produto para usuários), faça cache por hash(prompt + size + quality) e sirva da sua CDN.

4. Use low para exploração de prompt e depois faça upgrade

Um workflow comum:

# 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

Custo total: ~$0.22 em vez de ~$0.84 se você tivesse rodado todas as 5 variantes em high.

5. Defina limites duros de gasto no painel da OpenAI

Não confie que seu código nunca terá bug — defina um teto de uso em platform.openai.com/account/billing/limits.

Status de geração via streaming (opcional)

Para lotes longos, você pode querer mostrar progresso. O endpoint de geração de imagem não é streamed, mas você pode envolver seu lote em reporting assíncrono de progresso:

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

Erros comuns de integração

Checklist pronto para produção

Antes de publicar uma integração com o GPT Image 2:

• Chave de API em variável de ambiente, nunca em código ou logs
• Tier de qualidade apropriado ao caso de uso (padrão medium)
• Concorrência limitada (p-limit / Semaphore) para jobs em lote
• Tratamento de erros distingue 4xx vs 5xx
• Teto de gasto definido no painel da OpenAI
• Input de usuário sanitizado contra violações de política
• Saída armazenada no seu próprio storage (sem depender de URLs da OpenAI)
• Camada de cache para prompts repetidos
• Monitoramento de custo por imagem e taxa de erro

Geração assíncrona com polling de tarefa (para setups de alta concorrência)

Para cargas de trabalho de produção de alto volume, alguns relays do GPT Image 2 oferecem um modelo assíncrono de tarefa: você submete a requisição, recebe um ID de tarefa imediatamente, e ou faz polling pela conclusão ou recebe um callback. Isso evita timeouts HTTP em lotes grandes.

Fluxo assíncrono típico:

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

O modo assíncrono é ideal para:

• Lojas de e-commerce gerando centenas de variantes de produto durante a noite
• Times de marketing rodando testes A/B de prompts
• Apps onde usuários pedem imagens e checam depois (notificações)

FAQ da API do GPT Image 2

P: Qual é o nome do modelo da API do GPT Image 2? gpt-image-2. Use essa string exata em todas as requisições.

P: A API do GPT Image 2 suporta image-to-image / edição de imagem? Sim. Use images.edit com o parâmetro image, ou passe image_urls (array de 1-16 imagens de referência) para relays que suportem. Imagens de referência são essenciais para consistência de personagem, design de IP e fotografia de produto.

P: A API do GPT Image 2 é gratuita? Não, é paga por token. Contas novas da OpenAI podem receber créditos de teste. Alguns relays de terceiros oferecem créditos de trial.

P: Quanto custa a API do GPT Image 2 por imagem? Aproximadamente $0.011 / $0.042 / $0.167 por imagem 1024×1024 nos tiers baixo / médio / alto respectivamente. Tamanhos maiores e imagens de referência custam mais.

P: Qual o tamanho máximo do prompt? Até 32.000 caracteres. Na prática, prompts acima de ~1.500 caracteres têm retornos decrescentes.

P: Como gero PNGs de fundo transparente com a API? Defina background: "transparent" e output_format: "png".

P: Quais resoluções o GPT Image 2 suporta? Presets comuns: 1024x1024, 1536x1024, 1024x1536. Alguns relays expõem níveis de resolução 1K / 2K / 4K para controle explícito.

P: Qual é o rate limit? Depende do seu tier na OpenAI. O tier gratuito tem os limites mais rigorosos; o tier de uso escala com o tempo. Use concorrência limitada (p-limit / Semaphore) para ficar sob o limite.

P: Como trato erros da API do GPT Image 2? Distinga 4xx (não tente de novo — geralmente violações de política de conteúdo) de 5xx (tente de novo com backoff exponencial). Veja a seção de tratamento de erros acima.

P: Posso cancelar uma requisição em voo da API do GPT Image 2? Para requisições síncronas, apenas fechando a conexão. Relays com modo assíncrono expõem um endpoint cancel que funciona enquanto a tarefa ainda está na fila.

P: A API suporta streaming? A geração de imagem em si não é streamed (você recebe a imagem completa no final). Para UI de progresso, envolva seu lote em um reporter de progresso customizado (veja "Status de geração via streaming" acima).

Quer um app de exemplo funcionando?

Para uma implementação de referência completa — Next.js + GPT Image 2 + Stripe + storage de imagens — explore gpt-image2.art e a página explore mostrando saídas reais.

Precisa de uma chave de API gerenciada com SLA?

Se você prefere pular o setup de conta, cobrança, problemas de região e ajuste de rate limit, pode comprar uma chave de API gerenciada do GPT Image 2 mandando email para support@gpt-image2.art. Oferecemos:

• Um endpoint de API estável com failover embutido
• Cobrança agregada na sua moeda local (sem precisar de transferência em dólares)
• Modo de tarefa assíncrona + suporte a callback prontos
• Preço de volume para times gerando mais de 10K imagens/mês
• Mesmo nome de modelo gpt-image-2 e mesma especificação de parâmetros da API oficial — compatível drop-in

Leitura adicional

• Guia de Prompts do GPT Image 2 — 7 Regras Que Levam a Taxa de Acerto de 30% a 90%
• Biblioteca de Estilos do GPT Image 2 — 12 Prompts de Arte Prontos para Produção
• O Que é GPT Image 2? Uma Introdução Completa