Como Usar a API GPT-5.5

O GPT-5.5 foi lançado em 23 de abril de 2026, e a manchete para desenvolvedores é simples: a OpenAI abriu o modelo dentro do ChatGPT e do Codex no mesmo dia, e se comprometeu com as APIs de Respostas e Conclusões de Chat "muito em breve". Este guia cobre ambos os lados dessa linha; como chamar o GPT-5.5 assim que as chaves funcionarem, e como os primeiros testadores o estão usando hoje através do caminho de login do Codex.

Você terá os formatos dos endpoints, autenticação, exemplos em Python e Node, a tabela completa de parâmetros, cálculo de preços no modo de raciocínio, tratamento de erros e um fluxo de trabalho de teste no Apidog que economiza créditos ao iterar.

Para a visão geral do modelo em nível de produto, consulte O que é GPT-5.5. Para um caminho de nível gratuito puro, consulte Como usar a API do GPT-5.5 gratuitamente.

Em Resumo

• O GPT-5.5 é fornecido nos endpoints de Respostas e Conclusões de Chat; o ID do modelo é gpt-5.5. O Pro é gpt-5.5-pro.
• O preço da API é de $5 / M de entrada e $30 / M de saída; o Pro é de $30 / M de entrada e $180 / M de saída.
• A janela de contexto é de 1 M de tokens na API e 400 K dentro da CLI do Codex.
• Até que a implementação geral da API seja concluída, os desenvolvedores podem usar o GPT-5.5 através do Codex usando um login do ChatGPT.
• Use o Apidog para pré-construir a coleção; o formato da requisição corresponde ao GPT-5.4 com um novo ID de modelo e um bloco reasoning expandido.

Pré-requisitos

Antes de fazer a primeira requisição, prepare quatro coisas:

• Uma conta de desenvolvedor da OpenAI com um plano faturável. Uma assinatura do ChatGPT Plus ou Pro é separada da cobrança da API; você precisa de ambos se quiser acesso à interface do usuário e acesso programático.
• Uma chave de API com acesso à família de modelos GPT-5. Chaves com escopo de projeto são fortemente recomendadas em vez de chaves de usuário para qualquer carga de trabalho de produção.
• A versão do SDK que suporta gpt-5.5. Em Python, é openai>=2.1.0; em Node, é openai@5.1.0 ou mais recente.
• Um cliente de API que pode reproduzir requisições sem lotar o terminal. O curl funciona para uma única chamada; depois disso, mude para o Apidog ou similar.

Exporte sua chave uma vez:

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

Endpoint e autenticação

O GPT-5.5 reside nos mesmos dois endpoints que o restante da família GPT-5.

POST https://api.openai.com/v1/responses
POST https://api.openai.com/v1/chat/completions

A API de Respostas é a superfície mais recente e ciente de ferramentas da OpenAI, e é onde o modo de raciocínio, a pesquisa na web e o uso do computador se conectam de forma limpa. As Conclusões de Chat ainda funcionam e ainda carregam a maioria das integrações legadas.

A autenticação é um token de portador (bearer token). Cada requisição aceita um corpo JSON com o ID do modelo, o prompt ou array de mensagens, e quaisquer parâmetros que você desejar.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Summarize the last 10 releases of the openai/codex repo in three bullets.",
    "reasoning": { "effort": "medium" }
  }'

Se a chamada for bem-sucedida, você receberá um objeto JSON com um array output de mensagens e um bloco usage detalhado em tokens de entrada, saída e raciocínio. Falhas retornam o envelope padrão da OpenAI com um code e uma message legível por humanos; a tabela de erros no final deste guia cobre os que você encontrará primeiro.

Parâmetros da Requisição

Cada campo no corpo se relaciona com custo ou comportamento. Aqui está o mapa completo para gpt-5.5.

Os três campos que mais afetam o custo são reasoning.effort, max_output_tokens e tools. Execuções no estilo de Pensamento com reasoning.effort: "high" ou "xhigh" podem facilmente adicionar 3 a 8 vezes a contagem de tokens de saída de uma execução low (baixa).

Exemplo em Python

O formato do SDK para GPT-5.5 segue a API de Respostas do 5.4; a única diferença é o ID do modelo e a faixa expandida de reasoning.effort.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {
            "role": "system",
            "content": "You are a senior Go engineer. Answer in terse, runnable code.",
        },
        {
            "role": "user",
            "content": (
                "Write a worker pool with bounded concurrency and a context "
                "cancellation path. No third-party deps."
            ),
        },
    ],
    reasoning={"effort": "medium"},
    max_output_tokens=4000,
)

print(response.output_text)
print(response.usage.model_dump())

Duas coisas a serem observadas:

• response.output_text achata o array output para você. Se precisar dos eventos estruturados (chamadas de ferramentas, rastreamentos de raciocínio, citações), leia response.output diretamente.
• usage agora retorna input_tokens, output_tokens e reasoning_tokens como contadores separados. Fature com base nos três.

Exemplo em Node

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.5",
  input: [
    { role: "system", content: "You are a careful reviewer." },
    {
      role: "user",
      content:
        "Review this migration and flag any operation that would lock a write-heavy table for more than 200 ms.",
    },
  ],
  reasoning: { effort: "high" },
  tools: [{ type: "file_search" }],
  max_output_tokens: 6000,
});

console.log(response.output_text);
console.log(response.usage);

Defina reasoning.effort como high (alto) quando a tarefa for do tipo revisão e o custo de um problema não detectado for maior do que o custo de alguns centavos extras em tokens de raciocínio.

Modo de raciocínio

O Modo de Raciocínio do GPT-5.5 não é um ID de modelo diferente; é o modelo padrão gpt-5.5 executado com reasoning.effort em high (alto) ou xhigh (extra alto), juntamente com um orçamento maior de max_output_tokens. A interface do ChatGPT da OpenAI o expõe como um botão; na API, você o controla por requisição.

Duas regras gerais:

• Use medium (médio) como padrão. Ele cobre a maioria dos trabalhos de agente, depuração multi-arquivo e geração de documentos. Os custos permanecem próximos aos do GPT-5.4.
• Reserve high (alto) e xhigh (extra alto) para pesquisa, revisão crítica de correção e cadeias longas de ferramentas. Orce 3 a 8 vezes a contagem de tokens de saída e calcule o tempo da resposta em vez de assumir que ela retornará em menos de 30 segundos.

Se sua requisição envolve computer_use ou cadeias longas de pesquisa na web, o esforço de nível de Raciocínio vale o investimento; a redução de alucinações que a OpenAI citou no post de lançamento aparece principalmente nesses fluxos de trabalho.

Saída estruturada

A saída JSON estrita é o padrão no GPT-5.5. Passe um esquema e o SDK se recusará a retornar JSON malformado.

response = client.responses.create(
    model="gpt-5.5",
    input="Extract the title, speaker, and start time from this transcript chunk.",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "session_extract",
            "strict": True,
            "schema": {
                "type": "object",
                "required": ["title", "speaker", "start_time"],
                "properties": {
                    "title": {"type": "string"},
                    "speaker": {"type": "string"},
                    "start_time": {"type": "string", "format": "date-time"},
                },
            },
        },
    },
)

Para qualquer pipeline que alimenta código downstream, sempre defina um esquema. Isso não custa nada no nível de token e remove o loop de novas tentativas que você escreveria para lidar com saídas malformadas.

Uso de ferramentas e agentes

A API de Respostas expõe cinco tipos de ferramentas próprias:

• web_search — pesquisa em tempo real, agora com citações por resultado.
• file_search — pesquisa vetorial em arquivos enviados.
• code_interpreter — Python em ambiente de área restrita (sandbox).
• computer_use — mouse, teclado e navegador via a pilha Operator.
• function — suas próprias funções de callback.

A melhoria do GPT-5.5 em relação ao 5.4 aqui não é a lista de ferramentas; é a disposição do modelo em encadeá-las sem supervisão. Em testes contra a suíte de reprodução do The Decoder, o GPT-5.5 completou 11% mais cadeias de ferramentas multi-etapas sem intervenção do usuário do que o 5.4 sob o mesmo prompt.

Tratamento de erros e novas tentativas

Espere quatro códigos de erro com frequência suficiente para tratá-los pelo nome.

Os tokens de raciocínio contam para a janela de contexto. Uma chamada com reasoning.effort: "xhigh" em uma entrada de 900 K-tokens atingirá 400 por estouro de contexto, mesmo que sua mensagem de usuário seja curta.

Fluxo de trabalho de teste com Apidog

As chamadas do GPT-5.5 são caras o suficiente para que você não queira descobrir um bug de esquema refazendo o prompt 20 vezes. O fluxo de trabalho que desperdiça o menor número de tokens:

1. Construa a requisição uma vez no Apidog, salve-a como uma entrada de coleção e marque o ambiente (chave de desenvolvimento, staging, produção).
2. Use o servidor de mock integrado para reproduzir a última resposta real enquanto você itera no código downstream.
3. Mude para a chave ao vivo apenas quando o esquema estiver estável.

O Apidog também oferece uma integração com Claude Code e Cursor para que a mesma coleção seja acessível de qualquer agente de nível de editor que você use. Consulte nosso passo a passo do Apidog no VS Code e a comparação Apidog vs. Postman para a configuração completa.

Chamando o GPT-5.5 antes da API ser geral

Até que a OpenAI finalize a implementação da API de Respostas, o caminho prático para desenvolvedores que desejam ter experiência prática com o GPT-5.5 é o fluxo de login do Codex. O guia gratuito do Codex orienta a instalação da CLI, a autenticação com uma conta ChatGPT e a seleção do modelo.

FAQ

Existe um gpt-5.5-mini? Não no lançamento. A OpenAI manteve o gpt-5.4-mini como o SKU otimizado para custo.

Qual é a janela de contexto? 1 M de tokens na API. 400 K dentro da CLI do Codex. Ambos incluem tokens de raciocínio.

Preciso reescrever meu código GPT-5.4? Não. Troque o ID do modelo, amplie max_output_tokens se quiser saída em nível de Raciocínio, e ajuste novamente reasoning.effort para sua carga de trabalho.

Como eu reduzo o custo? Três alavancas: Lote (50% de desconto), Flex (50% de desconto, enfileiramento mais lento) e esquemas estritos para eliminar loops de retentativa. Cálculos de custo completos na análise de preços do GPT-5.5.

Onde devo acompanhar o anúncio da GA da API? A comunidade de desenvolvedores da OpenAI e a página de preços da API da OpenAI são os sinais públicos mais rápidos.