> Índice: https://quebragalho.dev/docs/llms.txt

# 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**

```toml
# ~/.codex/config.toml
model = "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**

```bash
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ção | Resposta | O que o cliente faz |
| --- | --- | --- |
| Saldo insuficiente | `429 insufficient_quota` | O Codex para. Um 402 ele repetiria. |
| Conversa maior que o contexto | `400 context_length_exceeded` | Reconhece o contexto cheio e compacta. |
| Key ausente ou inválida | `401 invalid_api_key` | Para. |
| Limite por minuto ou de concorrência | `429 rate_limit_error` | Espera o `Retry-After`. |
| Falha ou demora do provedor | `5xx api_error` | Repete 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.

Versão para ler no navegador: https://quebragalho.dev/docs/api/responses
