Pular para o conteúdo
quebragalho/docs

Referência da API

Responses

POST/v1/responses

O formato Responses da OpenAI, com e sem stream. É a rota do Codex, no terminal e no app, com a mesma key e o mesmo saldo do chat.

Um bloco no config.toml

Cole o bloco em ~/.codex/config.toml. O mesmo arquivo vale para o Codex no terminal e para o app do Codex.

config.toml
# ~/.codex/config.tomlmodel = "glm-5.3-flash"model_provider = "quebragalho"[model_providers.quebragalho]name = "Quebra-Galho"base_url = "https://api.quebragalho.dev/v1"env_key = "QUEBRAGALHO_API_KEY"wire_api = "responses"
  • wire_api = "responses" e a base terminando em /v1 são obrigatórios.
  • A key fica na variável QUEBRAGALHO_API_KEY. O app lê as variáveis do perfil do seu shell (por exemplo ~/.zshenv): exporte lá e reabra o app.
  • Desde a 0.134, um perfil é um arquivo próprio, ~/.codex/<nome>.config.toml, usado com codex --profile <nome>.
  • O aviso de modelo sem metadados é esperado para ids que o Codex não conhece. Ele segue com valores padrão.
  • No app, o título de cada conversa nova sai de um pedido à parte, hoje para gpt-6-luna, cobrado no preço dele.

Ids gpt-*: o Codex recente troca as ferramentas desses modelos por um modo próprio (code mode), e por aqui as chamadas de ferramenta ainda falham de vez em quando. Para tarefas com ferramentas, prefira por enquanto ids de outras famílias.

Chamada direta

Sem o Codex, a rota aceita o corpo da Responses API da OpenAI. A key vai em Authorization: Bearer.

cURL
curl https://api.quebragalho.dev/v1/responses \  -H "Authorization: Bearer $QUEBRAGALHO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "glm-5.3-flash",    "input": "explica RAG em 3 linhas"  }'

No SDK da OpenAI, é client.responses.create com a base em https://api.quebragalho.dev/v1.

O que muda em relação à OpenAI

Por dentro, o pedido vira o mesmo pedido de chat. Quase tudo atravessa. O que não atravessa:

  • Ferramentas de função funcionam. Ferramentas hospedadas pelo provedor, como busca na web, são ignoradas.
  • max_output_tokens acima do teto do seu plano volta 400.

Erros

No formato da OpenAI, com os códigos que o Codex usa para decidir se para ou repete.

SituaçãoRespostaO que o cliente faz
Saldo insuficiente429 insufficient_quotaO Codex para. Um 402 ele repetiria.
Conversa maior que o contexto400 context_length_exceededReconhece o contexto cheio e compacta.
Key ausente ou inválida401 invalid_api_keyPara.
Limite por minuto ou de concorrência429 rate_limit_errorEspera o Retry-After.
Falha ou demora do provedor5xx api_errorRepete sozinho.

As respostas 502 e 504 chegam como 503: a Cloudflare, na frente da API, troca esses status. Leia o tipo e o code no corpo, não só o status.