Blog

Como Usar a API gpt-image-2?

Ashley Innocent

Ashley Innocent

22 abril 2026

Como Usar a API gpt-image-2?

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Agendar uma demo

A API gpt-image-2 é o novo endpoint de geração de imagens da OpenAI, lançado junto com o ChatGPT Images 2.0 em 21 de abril de 2026. Se você já utiliza as APIs de chat ou embeddings da OpenAI, adicionar a geração de imagens requer apenas um novo formato de requisição, uma chave de API com o escopo correto e cerca de dez minutos.

Este guia trata estritamente da API: autenticação, parâmetros de requisição, exemplos de código em três linguagens, modo de pensamento (thinking mode), geração em lote, tratamento de respostas, códigos de erro, limites de taxa (rate limits) e o fluxo de trabalho de teste que evita que você gaste créditos com prompts defeituosos. Para uma visão geral do produto sobre as 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 imagem clara do custo de cada parâmetro.

button

Pré-requisitos

Antes da sua primeira requisição, você precisa de quatro coisas:

Defina a chave uma vez no seu shell para que todos os exemplos neste guia sejam executados sem edições:

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

Endpoint e autenticação

O gpt-image-2 usa o mesmo endpoint de geração de imagens do modelo anterior:

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

A autenticação é um token bearer no cabeçalho Authorization. Cada requisição também carrega um corpo JSON com o ID do modelo, prompt e parâmetros de saída.

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

Se a chamada for bem-sucedida, você receberá um objeto JSON com um array data de imagens. Falhas retornam um envelope de erro padrão da OpenAI com um code e uma message legível; a tabela de erros mais adiante neste guia cobre os mais comuns.

Parâmetros de requisição

Cada campo no corpo da requisição altera o que você paga e o que você obtém. Aqui está o mapa completo de parâmetros 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 mais longos consomem mais tokens de entrada.
size string 1024x1024, 1024x1536, 1536x1024, 2000x1000, 1000x2000, 2000x667, 667x2000 Afeta a contagem de tokens de saída.
quality string standard, high high custa cerca de 2×, mas lida melhor com texto fino e elementos de UI.
n integer 1–10 Requisições em lote compartilham o estilo entre o conjunto.
thinking string off, low, medium, high Orçamento de raciocínio antes da renderização.
response_format string url, b64_json URLs expiram em uma hora.
user string Formato livre Usado para detecção de abuso; passe um ID de usuário hashed.
background string auto, transparent, opaque A saída transparente é enviada como PNG com alfa.
seed integer Qualquer int32 Controle flexível; a mesma semente mais o mesmo prompt é próximo, não idêntico.

Os três parâmetros que mais alteram o custo são size, quality e thinking. Uma imagem de 2000 pixels de largura com qualidade high e thinking: "high" pode custar 4–5× mais do que uma renderização standard de 1024x1024.

Exemplo em Python

O SDK oficial (openai>=1.50.0) adiciona suporte nativo para 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()}")

Duas coisas que valem a pena destacar:

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 o SDK oficial em vez de fetch puro, a menos que você tenha uma razão para não fazê-lo. O SDK lida com retentativas, cabeçalhos de idempotência e streaming, e rastreia alterações de esquema que quebram a compatibilidade entre as revisões do modelo.

Modo de pensamento (Thinking mode): quando usar

thinking controla a quantidade de processamento que o modelo gasta planejando o layout antes de renderizar. Quatro valores, aproximadamente:

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

O modo de pensamento (thinking mode) adiciona tokens de raciocínio à fatura, além dos tokens de saída de imagem. A página de preços da OpenAI lista as taxas atuais por token; preveja 1.2–2× o custo base da sua imagem quando medium ou high estiver ativado.

Geração em lote

Definir n > 1 retorna múltiplas imagens em uma única resposta que compartilham composição e estilo. Isso não é o mesmo que chamar o endpoint n vezes em paralelo; isso lhe daria quatro imagens não relacionadas. A saída em lote é coerente, o que corresponde à forma como uma equipe de design itera.

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, então n=4 custa aproximadamente 4× n=1. O ganho é a consistência, não o rendimento.

Formato de resposta e armazenamento

Dois formatos, dois casos de uso:

Para produção, baixe o URL e envie-o para seu próprio bucket S3, R2 ou Cloudflare Images imediatamente. Não envie URLs da OpenAI para usuários finais; eles expiram.

Tratamento de erros e limites de taxa

O gpt-image-2 retorna formatos de erro padrão da OpenAI. Aqui estão os que você encontrará:

HTTP code Causa Solução
400 invalid_request_error Tamanho incorreto, proporção não suportada, prompt com mais de 32 mil caracteres Verifique a lista de tamanhos e encurte o prompt.
401 invalid_api_key Chave ausente ou incorreta Re-exporte OPENAI_API_KEY.
403 insufficient_quota Sem créditos, ou nível Gratuito Adicione faturamento, verifique o nível.
429 rate_limit_exceeded Muitas requisições por minuto Faça um "back off" com "jitter"; tente novamente com Retry-After.
429 image_generation_user_error Recusa por política de conteúdo Reescreva o prompt.
500 server_error Problema transitório da OpenAI Tente novamente duas vezes com "backoff" exponencial.
503 overloaded Pico de uso em toda a região Aguarde e tente novamente.

Os limites de taxa no gpt-image-2 são baseados em níveis. No Nível 1, você começa com cerca de 50 requisições por minuto; níveis mais altos aumentam. Sempre leia os cabeçalhos x-ratelimit-remaining-requests e x-ratelimit-remaining-tokens em cada resposta e reduza a taxa antes de atingir o limite.

Erros retentáveis em produção:

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

Não tente novamente erros 400, 401 ou 429 de política de conteúdo; eles falham por um motivo e a retentativa desperdiça créditos.

Testando a API com Apidog

Iterar em prompts de geração de imagem a partir de um terminal é lento: você não consegue ver o resultado, não consegue diferenciar as mudanças de parâmetro e não consegue versionar os prompts bons. Um cliente de API feito sob medida resolve todos os três.

Apidog trata o endpoint gpt-image-2 como uma requisição de primeira classe. Fluxo de trabalho típico:

  1. Crie uma nova requisição na sua coleção OpenAI, método POST, URL https://api.openai.com/v1/images/generations.
  2. Adicione Authorization: Bearer {{OPENAI_API_KEY}} como um cabeçalho; defina OPENAI_API_KEY em uma variável de ambiente para que nunca esteja no código-fonte.
  3. Cole o corpo JSON com seu prompt; o Apidog valida contra a especificação OpenAPI e aponta incompatibilidades de tipo antes de você enviar.
  4. Pressione Enviar. As respostas de imagem são renderizadas inline; salve as boas, marque as ruins, ramifique a requisição para variantes.
  5. Salve ambientes para thinking: off, thinking: medium e thinking: high para comparar o mesmo prompt em diferentes níveis de raciocínio.

A comparação de requisições do Apidog é a parte mais importante aqui. Você ajusta um parâmetro; você vê a imagem antes e depois lado a lado; você comita o vencedor para uma biblioteca de prompts que toda a sua equipe compartilha. Este é o fluxo de trabalho que o terminal não pode lhe oferecer.

Se você está vindo de um cliente HTTP genérico ou de um workspace do Postman travado, Baixe o Apidog e aponte-o para sua chave OpenAI; a configuração leva menos de cinco minutos. Equipes avaliando alternativas também podem ler nosso guia de teste de API sem Postman e a visão geral da extensão Apidog para VS Code.

Armadilhas comuns

Alguns erros queimam créditos e tempo na primeira semana com o gpt-image-2.

Perguntas Frequentes (FAQ)

button

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar