Como usar a API gpt-image-2.5 (Flare e Sunburst) com curl, Python e Node

OpenAI lançou o ChatGPT Images 2.5 em 8 de setembro de 2026, com dois novos modelos de API: gpt-image-2.5-flare e gpt-image-2.5-sunburst. Ambos utilizam os mesmos endpoints do gpt-image-2, então se você seguiu nosso guia da API gpt-image-2, a maior parte do seu código sobreviverá a uma troca de ID de modelo. O que mudou é a escala de qualidade e como a API Responses permite que você escolha um modelo por chamada de ferramenta.

Este guia abrange apenas o caminho do desenvolvedor: gerações, edições multipartes com imagem de referência e máscara, a ferramenta da API Responses, streaming e leitura de usage para custo real. Para o que o lançamento significa para os usuários do ChatGPT, leia nossa visão geral do ChatGPT Images 2.5; a publicação de lançamento da OpenAI apresenta o enquadramento do produto. Cada número abaixo vem da documentação da OpenAI, página de preços ou calculadora, conforme lido em 9 de setembro de 2026.

API gpt-image-2.5 em um relance

As taxas por token correspondem ao gpt-image-2; o custo por imagem ainda varia porque a contagem de tokens por nível de qualidade mudou.

Pré-requisitos

• Uma conta de desenvolvedor OpenAI em um nível de uso pago. Endpoints de imagem exigem Tier 1 ou superior, o que significa adicionar um método de pagamento; uma assinatura do ChatGPT não conta. Nosso passo a passo da chave de API OpenAI cobre chaves com escopo de projeto.
• O SDK oficial openai para Python ou Node.
• Uma forma de pré-visualizar respostas de imagem. O curl imprime base64, o que é doloroso para iteração; o Apidog renderiza a imagem decodificada inline, e a última seção move o fluxo de trabalho para lá.

Exporte a chave uma vez:

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

Gerar uma imagem com curl

Use Flare primeiro; a página do modelo da OpenAI o chama de “a escolha padrão para a maioria das aplicações”.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

A resposta contém um array data com um b64_json por imagem, mais um objeto usage com input_tokens e output_tokens. Mantenha usage; é o único sinal de custo preciso que você obtém. Notas de parâmetros do guia de geração de imagens: output_format padroniza para png e a OpenAI diz “Usar jpeg é mais rápido que png”; output_compression (0-100) aplica-se apenas a jpeg e webp; background: "transparent" falha em jpeg.

Python: gerar, depois editar com uma imagem de referência

A chamada do SDK espelha o corpo do curl. Decodifique b64_json e escreva os bytes.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

As edições são onde os modelos 2.5 justificam seu valor; a publicação de lançamento diz que eles são “melhores em editar apenas o que você pediu, mantendo o resto dos detalhes intactos”, e a OpenAI posiciona o Sunburst para “controle mais rigoroso sobre as edições”. O endpoint de edições é multipart: uma imagem de referência, uma máscara opcional e um prompt. Onde a máscara é transparente, o modelo repinta; em todos os outros lugares, ele mantém o original.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

Remova mask e o modelo decide o que mudar apenas a partir do prompt. A imagem de referência é faturada como tokens de entrada de imagem a $8 por 1M; a OpenAI não publica uma contagem de tokens de entrada por imagem, então leia usage.input_tokens.

Node e TypeScript: escrever b64_json para o disco

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

Fixe gpt-image-2.5-flare-2026-09-08 em produção para manter a saída estável enquanto o alias se move.

API Responses: geração de imagem como ferramenta

Aqui, um modelo principal lê seu prompt, o revisa e chama a ferramenta image_generation. Você escolhe o modelo de imagem configurando model dentro da definição da ferramenta; o model de nível superior deve ser um modelo principal, e a documentação da ferramenta da OpenAI usa gpt-6-astra. Nosso guia da API Responses cobre o formato da requisição. O campo action aceita auto (padrão), generate ou edit; defina edit quando você passa uma imagem de referência e deseja que ela seja modificada, não reinterpretada.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

O acompanhamento previous_response_id mantém a primeira imagem em contexto, então “mesma cena” é resolvida sem o reenvio do arquivo. Tokens do modelo principal são cobrados além dos tokens de imagem, e a reescrita do prompt significa que você não pode reproduzir a saída apenas a partir do texto do prompt.

Streaming de imagens parciais

Ambas as APIs aceitam partial_images (0 a 3). Cada parcial custa 100 tokens de saída extras, então três adicionam 300 tokens, ou $0.009 por imagem. Vale a pena para uma UI que mostra progresso; desperdício em um trabalho em lote.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

As strings exatas dos tipos de evento estão no guia de geração de imagens; a verificação de sufixo mantém o loop funcionando em ambas as variantes da API. Para inspecionar eventos transmitidos fora do código, consulte nosso guia sobre como testar respostas SSE de APIs de IA.

Ler o uso e transformar tokens em dólares

A própria ressalva da OpenAI: “Taxas de token iguais não significam custo igual por imagem: o consumo de token pode diferir por modelo e configuração de qualidade.” A calculadora no guia de geração de imagens fornece essas estimativas apenas para tokens de saída de imagem, à taxa de $30 por 1M na página de preços:

Observe a re-rotulação. high na versão 2.5 usa 1.756 tokens, o antigo orçamento medium no gpt-image-2; max usa 7.024 tokens, o antigo orçamento high. Mantenha quality: "high" durante uma migração e cada imagem fica cerca de 4x mais barata no antigo orçamento medium; para o antigo orçamento high, mude para max. Nossa comparação Flare vs Sunburst vs gpt-image-2 calcula o custo mensal completo.

Os números da calculadora são estimativas. O custo real vem da resposta:

OUTPUT_RATE = 30 / 1_000_000  # dollars per image output token
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

Registre por requisição; segundo a OpenAI, um tamanho não quadrado maior pode produzir menos tokens do que um quadrado menor. Uma questão em aberto: a aba Batch da página de preços lista apenas gpt-image-2, então considere o suporte da API Batch para a versão 2.5 como não confirmado.

Erros, limites de taxa e timeouts

• 429 limite de taxa. Recue com jitter e respeite Retry-After. As páginas do modelo 2.5 não publicam limites por nível. Para referência, gpt-image-2 opera no Tier 1 com 5 imagens por minuto e 100k TPM, escalando para o Tier 5 com 250 IPM e 8M TPM.
• insufficient_quota. Sem créditos ou ainda no nível gratuito. Adicione faturamento; não tente novamente.
• Recusas de moderação. O prompt ou a imagem de referência acionou o filtro. Reformule em vez de tentar novamente; moderation: "low" relaxa o limite.
• Timeouts. A OpenAI documenta que “Prompts complexos podem levar até 2 minutos para processar”. Defina os timeouts do cliente acima disso; o Sunburst leva mais tempo que o Flare por design.

Testar Flare e Sunburst lado a lado no Apidog

A iteração no terminal em prompts de imagem é lenta porque você não consegue ver a saída, e um valor de quality errado custa dinheiro real a cada envio. O Apidog é um cliente de API e plataforma de testes: ele envia as chamadas e verifica as respostas; os servidores da OpenAI fazem a renderização.

1. Armazene a chave uma vez. Adicione OPENAI_API_KEY como uma variável de ambiente e faça referência a ela como Bearer {{OPENAI_API_KEY}} no cabeçalho de Autorização; a chave nunca é salva em uma requisição.
2. Dois ambientes, uma requisição. Crie ambientes chamados flare e sunburst, cada um com uma variável MODEL, e defina "model": "{{MODEL}}" no corpo. Troque, reenvie e compare imagens e usage lado a lado. Para edições, use um corpo de form-data com image e mask como campos de arquivo.
3. Decodifique b64_json em um pós-processador. Um script curto extrai data[0].b64_json, o decodifica e salva o arquivo, de modo que cada envio resulta em uma imagem visualizável ao lado do JSON bruto.
4. Afirme sobre o custo, então agende. Afirme que usage.output_tokens permanece dentro de um orçamento, digamos 2.000 para uma renderização high 1536x1024, e execute a requisição como um teste de regressão cronometrado. Se alguém aumentar a qualidade para max ou um snapshot alterar a contagem de tokens, o teste falhará antes que a fatura chegue.

Baixe o Apidog, aponte-o para sua chave OpenAI e você terá uma biblioteca de prompts compartilhada com barreiras de custo.

FAQ

• Preciso mudar meu código gpt-image-2 para usar o 2.5? Troque o ID do modelo e verifique novamente quality. Endpoints, autenticação e formato de resposta permanecem inalterados, mas high agora mapeia para um orçamento de tokens menor. O guia da API gpt-image-2 ainda cobre o modelo mais antigo.
• Flare ou Sunburst para a API? Comece com o Flare. A OpenAI o posiciona como o padrão com “50% menos latência” do que o gpt-image-2 pelo mesmo preço por token. Mude para o Sunburst quando a precisão da edição importar mais do que a velocidade, como em imagens de produtos construídas a partir de fotos de referência. Ambos compartilham as mesmas contagens de tokens da calculadora, então a troca é tempo, não dinheiro.
• Posso usar esses modelos em Chat Completions? Não. A geração de imagens reside na Image API e na ferramenta image_generation da Responses API. Chat Completions não a expõe.
• Existe uma forma gratuita de experimentar o 2.5 através da API? Não há um nível de API gratuito perpétuo, e os endpoints de imagem precisam do Tier 1. O caminho real mais barato é quality: "low" a 196 tokens, cerca de $0.006 por imagem 1024x1024. O aplicativo do consumidor é outra questão; veja como usar o ChatGPT Images 2.5 gratuitamente.

Onde ir em seguida

Comece com a chamada curl, confirme usage.output_tokens com a tabela da calculadora e, em seguida, mova a requisição para um cliente onde você possa ver a imagem. O artigo de Simon Willison mostra o Sunburst mantendo um gráfico intacto enquanto adiciona um assunto; teste esse comportamento de edição em suas próprias imagens de referência antes de se comprometer.