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

# Messages

`POST /v1/messages`

O formato da Anthropic, com e sem stream. É a rota do Claude Code e do SDK da Anthropic, com a mesma key e o mesmo saldo do chat.

## Aponte o Claude Code para cá

Exporte as variáveis e rode `claude`. A base é a raiz da API, sem `/v1`.

**Terminal**

```bash
# raiz da API, sem /v1
export ANTHROPIC_BASE_URL=https://api.quebragalho.dev
export ANTHROPIC_AUTH_TOKEN=$QUEBRAGALHO_API_KEY
# ids do catálogo; o HAIKU pode ser um mais barato
export ANTHROPIC_MODEL=claude-sonnet-4.6
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-sonnet-4.6
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4.6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5.5

claude
```

- `ANTHROPIC_AUTH_TOKEN` manda a key como Bearer e vale mesmo com um login da Anthropic salvo.
- Os três `ANTHROPIC_DEFAULT_…_MODEL` cobrem subagentes e tarefas de fundo. Sem eles, o Claude Code pede ids que podem não existir no catálogo.
- Para conferir, rode `/status` dentro do Claude Code: ele mostra a base e a credencial em uso.

> Não defina `CLAUDE_CODE_MAX_OUTPUT_TOKENS`. O teto corta a resposta de modelos de raciocínio. Nos ids `claude-*`, o Claude Code pede até 128 mil tokens de saída e a reserva cobre esse teto; com pouco saldo, o pedido volta 402. No fim, você paga só o que foi gerado.

**Mais detalhes do Claude Code**

- `ANTHROPIC_MODEL` é o modelo da conversa.
- `ANTHROPIC_API_KEY` também funciona, mas o modo interativo pede uma aprovação antes de usá-la.
- O aviso `unrecognized_model` aparece para ids que não são da Anthropic. Pode ignorar.

## Chamada direta

Sem o Claude Code, a rota aceita o corpo da API da Anthropic. A key vai em `x-api-key` ou em `Authorization: Bearer`.

**cURL**

```bash
curl https://api.quebragalho.dev/v1/messages \
  -H "x-api-key: $QUEBRAGALHO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "explica RAG em 3 linhas"}]
  }'
```

| Rota | O que faz |
| --- | --- |
| `POST /v1/messages` | Messages da Anthropic, com e sem stream. |
| `POST /v1/messages/count_tokens` | Estima os tokens de entrada. Não é cobrada. |

No SDK da Anthropic, passe `https://api.quebragalho.dev` em `base_url`, sem `/v1`: o SDK acrescenta a rota.

## O que muda em relação à Anthropic

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

- Ferramentas de função funcionam. As hospedadas pelo provedor, como busca na web, são ignoradas.
- `max_tokens` acima do teto do seu plano é cortado para o teto.
- `cache_control` e a assinatura dos blocos de `thinking` não são preservados. O cache de prompt funciona como no chat.
- Bloco `document` é recusado com 400.

## Erros

No formato da Anthropic, com os tipos que o Claude Code usa para decidir se para ou repete.

| Situação | Resposta | O que o cliente faz |
| --- | --- | --- |
| Saldo insuficiente | `402 billing_error` | Para na hora, sem repetir. |
| Conversa maior que o contexto | `400 invalid_request_error` | Reconhece o contexto cheio e compacta. |
| Key ausente ou inválida | `401 authentication_error` | 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/messages
