# Chat completions

`POST /v1/chat/completions` accepts `model`, `messages`, `max_tokens`, `temperature`, `stream`, and optional `stream_options: {"include_usage": true}`. The v0.1 contract covers text messages with `system`, `user`, and `assistant` roles. Tool calls, multimodal chat, embeddings, and the Responses API are outside this release contract.

```json
{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Explain HTTP in one sentence."}],"max_tokens":256,"temperature":0.7,"stream":true,"stream_options":{"include_usage":true}}
```

A non-streaming result contains `id`, `object: "chat.completion"`, `model`, `choices`, and `usage`. Streaming returns `text/event-stream`; each data event contains a completion chunk with `choices[].delta`. With `stream_options.include_usage=true`, the final upstream usage event, when supplied, precedes `data: [DONE]`. Record `X-Request-ID` from response headers. Do not parse SSE as one JSON document.

The gateway must not insert a JSON-only system prompt, silently switch the model, or replay a charged completion to repair output. Disconnecting or pressing Stop does not erase tokens already generated. Final billing uses observed usage; missing authoritative usage stays pending reconciliation, never silently becomes zero. Each route requires integration certification before being enabled.

[Billing](/docs?page=billing&lang=en) · [Production](/docs?page=production&lang=en)

All generation POST requests require an Idempotency-Key (1–128 printable ASCII characters). Use a fresh value for a new logical request and the same value only for exact replay. max_tokens is 1–4096; temperature is 0–2. Stream replay does not restart or replay a charged upstream stream.