Lucas

Posted on Apr 22 • Originally published at apidog.com

Como Usar a API gpt-image-2?

A API gpt-image-2 é o novo endpoint de geração de imagens da OpenAI, lançada junto com o ChatGPT Images 2.0 em abril de 2026. Se você já usa as APIs de chat ou embeddings da OpenAI, adicionar geração de imagens é uma questão de ajustar a requisição, garantir uma chave de API com escopo correto e configurar o ambiente em poucos minutos.

Experimente o Apidog hoje

Este guia é focado em implementação: cobre autenticação, parâmetros, exemplos de código em três linguagens, uso do modo de pensamento (thinking mode), geração em lote, tratamento de respostas e erros, limites de taxa e fluxo de teste para evitar desperdício de créditos com prompts defeituosos. Para uma visão geral do produto e novidades do ChatGPT Images 2.0, consulte nossa análise do ChatGPT Images 2.0.

Ao final, você terá chamadas funcionando, uma coleção Apidog reutilizável para iteração e uma visão clara do custo dos principais parâmetros.

Pré-requisitos

Antes de começar, garanta estes quatro itens:

Conta OpenAI com acesso à API. Contas de desenvolvedor são separadas do ChatGPT Plus; assinatura ChatGPT não inclui créditos de API.
Nível de uso faturável. O gpt-image-2 está disponível a partir do Nível 1. Novas contas começam como Gratuito e precisam adicionar pagamento para liberar endpoints de imagem.
Chave de API com escopo images:write. Prefira chaves de projeto para produção.
Ferramenta de teste que visualize respostas de imagem. O terminal (curl) serve para a primeira chamada; depois disso, use um cliente de API real.

Configure a chave de API no shell para executar todos os exemplos sem alterações:

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

Endpoint e autenticação

O gpt-image-2 utiliza o mesmo endpoint do modelo anterior:

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

Autentique usando token Bearer no cabeçalho Authorization. O corpo da requisição é JSON, incluindo modelo, prompt e parâmetros.

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

Em sucesso, você recebe JSON com um array data de imagens. Em falha, um envelope de erro padrão com code e message. Veja a tabela de erros mais abaixo.

Parâmetros de requisição

Cada campo do corpo altera custo e resultado. Veja o mapa completo para gpt-image-2:

Parâmetro	Tipo	Valores	Notas
`model`	string	`gpt-image-2`	Obrigatório.
`prompt`	string	Até 32.000 caracteres	Obrigatório. Prompts longos consomem mais tokens.
`size`	string	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Afeta tokens de saída.
`quality`	string	`standard`, `high`	`high` custa ~2x mais, mas lida melhor com texto fino e UI.
`n`	inteiro	1–10	Imagens em lote compartilham estilo.
`thinking`	string	`off`, `low`, `medium`, `high`	Orçamento de raciocínio antes da renderização.
`response_format`	string	`url`, `b64_json`	URLs expiram em 1 hora.
`user`	string	Livre	Para detecção de abuso; passe um ID de usuário hashed.
`background`	string	`auto`, `transparent`, `opaque`	Transparente retorna PNG com alfa.
`seed`	inteiro	Qualquer int32	Mesma seed + prompt gera imagem próxima, não idêntica.

Os parâmetros que mais impactam o custo: size, quality e thinking. Exemplo: imagem 2000px-wide, high e thinking: "high" pode custar 4–5x mais que uma renderização standard 1024x1024.

Exemplo em Python

O SDK oficial (openai>=1.50.0) já suporta o gpt-image-2:

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"Generated {len(response.data)} images into {out_dir.resolve()}")

Dicas:

response.data é sempre uma lista, mesmo com n=1. Sempre itere.
b64_json facilita scripts locais; url é melhor para upload direto (CDN, S3).

Exemplo em 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(`Saved ${response.data.length} images`);

Use sempre o SDK oficial — ele cuida de retentativas, cabeçalhos e mudanças de schema.

Modo de pensamento (Thinking mode): quando usar

O parâmetro thinking define o quanto o modelo planeja o layout antes de renderizar. Valores:

off: sem raciocínio. Rápido, barato, bom para prompts criativos livres.
low: planejamento leve. Padrão para fotos de produtos e hero images.
medium: mais planejamento. Ideal para diagramas, infográficos, slides e prompts com contagem (“quatro painéis”).
high: máximo raciocínio. Use só para layouts multilíngues complexos ou diagramas técnicos estritos; aumenta latência e custo.

Regra prática: se o prompt cita número, rótulo ou restrição posicional, suba um nível. Se for “uma cena aconchegante”, desça.

O modo de pensamento adiciona tokens além dos de saída. Veja preços atuais da OpenAI; use 1.2–2x o custo base com medium/high.

Geração em lote

Defina n > 1 para receber múltiplas imagens coerentes em uma resposta, compartilhando composição e estilo. Não é igual a chamadas paralelas — saídas em lote são visualmente consistentes.

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",
)

Você paga por imagem (n=4 ≈ 4× n=1), o ganho é consistência entre as imagens.

Formato de resposta e armazenamento

Dois formatos principais:

b64_json: imagem embutida (base64). Prático para scripts, mas respostas ficam grandes.
url: imagem hospedada no CDN da OpenAI por 1 hora. Ideal para pipelines e serverless; baixe para seu próprio storage imediatamente.

Nunca exponha URLs da OpenAI para usuários finais; sempre salve em S3, R2 ou similar antes de servir.

Tratamento de erros e limites de taxa

O gpt-image-2 retorna erros padrão OpenAI. Veja os principais:

HTTP	`code`	Causa	Solução
400	`invalid_request_error`	Tamanho ou proporção inválida, prompt longo	Revise tamanho e encurte prompt.
401	`invalid_api_key`	Chave ausente/incorreta	Reexporte `OPENAI_API_KEY`.
403	`insufficient_quota`	Sem créditos, nível Gratuito	Adicione pagamento/verifique nível.
429	`rate_limit_exceeded`	Muitas requisições/minuto	"Backoff" com jitter; use `Retry-After`.
429	`image_generation_user_error`	Recusado por política de conteúdo	Reescreva o prompt.
500	`server_error`	Erro transitório OpenAI	Tente novamente com backoff exponencial.
503	`overloaded`	Pico de uso na região	Aguarde e tente novamente.

No Nível 1, o limite é cerca de 50 requisições/minuto. Sempre monitore x-ratelimit-remaining-requests e x-ratelimit-remaining-tokens e ajuste a taxa antes de atingir o limite.

Retente apenas erros transitórios:

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

Nunca tente novamente erros 400, 401 ou 429 de política de conteúdo — eles são fatais.

Testando a API com Apidog

Iterar prompts de imagem via terminal é lento e ineficiente. Use um cliente de API visual para acelerar o ciclo.

Apidog trata o endpoint gpt-image-2 como requisição nativa. Siga este fluxo:

Crie uma nova requisição na coleção OpenAI: método POST, URL https://api.openai.com/v1/images/generations.
Adicione Authorization: Bearer {{OPENAI_API_KEY}} no cabeçalho; defina OPENAI_API_KEY como variável de ambiente.
Cole o JSON com seu prompt. O Apidog valida contra a especificação OpenAPI e aponta erros antes de enviar.
Clique em Enviar. Imagens são renderizadas inline; salve as boas, marque as ruins, ramifique variantes.
Salve ambientes para thinking: off, medium, high e compare rapidamente o mesmo prompt em diferentes níveis.

A comparação visual do Apidog é o diferencial: ajuste um parâmetro, veja antes e depois lado a lado e salve prompts vencedores para a equipe. O terminal não oferece esse fluxo.

Se você usa Postman ou outro cliente genérico, baixe o Apidog e aponte para sua chave OpenAI. A configuração é rápida. Equipes podem consultar também nosso guia de teste de API sem Postman e a visão geral da extensão Apidog para VS Code.

Armadilhas comuns

Evite estes erros que desperdiçam créditos na primeira semana:

Usar quality: "standard" para prompts com texto: distorce textos pequenos. Use high para rótulos, ícones ou textos de UI.
Excesso de prompting: 32k caracteres é o limite, não objetivo. Após algumas centenas, instruções são ignoradas. Mantenha os prompts curtos e use thinking para restrições complexas.
Esperar reprodutibilidade de seed: reduz variância, mas não fixa a saída. Para obter a mesma imagem, armazene os bytes; não regenere.
Enviar URLs da OpenAI para downstream: expiram em 1 hora. Sempre copie para storage próprio.
Loop apertado no endpoint: geração de imagens é lenta. Paralelize entre workers, respeite limites de taxa; loops sequenciais só causam timeout.

Perguntas Frequentes (FAQ)

Como o gpt-image-2 difere do gpt-image-1 na API? Mesmo endpoint e autenticação. Novos parâmetros: thinking (off/low/medium/high), valores extras de size até 2000px, n até 10. SDKs existentes funcionam trocando o modelo; adicione novos parâmetros conforme necessário. Veja a visão geral do ChatGPT Images 2.0.
Qual a forma mais rápida de prototipar integração com gpt-image-2? Crie uma requisição Apidog, salve ambientes (padrão vs. pensando), itere nos prompts sem tocar código. Exporte como curl ou código SDK quando finalizar.
A API suporta edição ou inpainting? Endpoints de edição/variação seguem o padrão anterior com novo ID de modelo. Veja referência do modelo gpt-image-2 para detalhes de máscaras/imagem de entrada.
Posso usar o gpt-image-2 para produção comercial? Sim, sob as políticas padrão da OpenAI. Você possui as imagens geradas; a OpenAI retém direito de monitorar para abuso. Marcas registradas e figuras públicas ativam salvaguardas.
E quanto ao custo para produção? Cerca de $0.21 por imagem 1024×1024 de alta qualidade no modo padrão; 10.000 imagens/mês = ~$2.100 sem thinking. Adicione 20–80% para thinking mode. Compare com alternativas auto-hospedadas como nosso guia da API GLM 5V Turbo e integração Qwen 3.5 Omni se custo for prioridade.
Existe alternativa mais barata com renderização de texto similar? Não ainda com a mesma qualidade para texto multilíngue. Modelos open-weight melhoraram, mas ainda ficam atrás em scripts CJK e Índicos.