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

# Chat completions

`POST /v1/chat/completions`

No formato da OpenAI, com e sem stream. O mesmo corpo e os mesmos SDKs; só a base URL e a key mudam.

## O mesmo corpo da OpenAI

SDK oficial, LangChain, fetch na mão: se monta o request da OpenAI, funciona aqui.

- `model`: Id do catálogo, exato. Veja em [Modelos](https://quebragalho.dev/docs/api/modelos.md).
- `messages`: O histórico: `system`, `user`, `assistant` e `tool`.
- `stream`: `true` para receber por SSE ([Streaming](#streaming)).
- `max_tokens`: Teto da resposta. Acima do teto do seu plano, volta 400 `max_tokens_exceeds_cap`.
- `tools`: Ferramentas de função, como na OpenAI.
- `temperature`: Amostragem, como na OpenAI.

**Resposta · 200**

```json
{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "gpt-6.2-astra",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Bora!…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 38 }
}
```

## Texto chegando em pedaços

Passe `stream: true` e a resposta vem por Server-Sent Events, pedaço a pedaço.

**text/event-stream**

```text
: heartbeat
data: {"choices":[{"delta":{"content":"Bora"}}]}
data: {"choices":[{"delta":{"content":"! Me"}}]}
: heartbeat
data: {"choices":[{"delta":{"content":" conta"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]
```

> Linhas que começam com `:` são heartbeat. Ignore e não feche a conexão por causa delas. Em raciocínio longo, pode vir só heartbeat por um bom tempo antes do primeiro token.

Erro no meio do stream chega como um evento `data:` com o objeto `error`, seguido de `data: [DONE]`.

## Uma conversa por usuário final

Se o seu app atende várias pessoas, mande um ID estável por conversa. Mesma conversa, cache aproveitado, custo menor. Sem ele nada quebra; só fica mais caro.

- Header `X-QG-Conversation-ID`, com o mesmo valor em todos os turnos da conversa.
- Até 128 caracteres imprimíveis.
- Valor inválido é ignorado, sem erro.
- Sem ID, usamos os headers de sessão que o seu cliente já envia ou o início do prompt.

**Python**

```python
client.chat.completions.create(
    model="gpt-6.2-astra",
    messages=history,
    extra_headers={
        # estável por conversa do seu usuário
        "X-QG-Conversation-ID": f"u{user.id}-c{conversation.id}",
    },
)
```

## Reserva antes, cobrança no fim

- Antes de encaminhar, o saldo separa uma reserva pelo tamanho do pedido e pelo `max_tokens`. Se o saldo livre não cobre, a resposta é 402 `insufficient_balance`.
- No fim, a cobrança é pelos tokens que o modelo usou, no preço do modelo. O resto da reserva volta para o saldo.
- Se o pedido falhar antes da resposta, a reserva volta inteira.
- Saldo bônus paga os modelos que aceitam bônus; os outros usam só saldo recarregado ([Modelos](https://quebragalho.dev/docs/api/modelos.md)).

Versão para ler no navegador: https://quebragalho.dev/docs/api/chat-completions
