# Text generation

Chat completions in the OpenAI format, streamed or not. Anthropic and Gemini
clients can hit the same models with their own protocol.

## Chat completions

`POST /v1/chat/completions`

```bash
curl "https://sharellm.net/v1/chat/completions" \
  -H "Authorization: Bearer $SHARE_LLM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Summarise what a model gateway does."}
    ],
    "stream": false
  }'
```

### Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | yes | Model ID from the market. |
| `messages` | array | yes | Chat history with `role` (`system` / `user` / `assistant`) and `content`. |
| `stream` | boolean | no | Stream tokens as server-sent events. Each event carries a delta; the last one carries usage. |
| `temperature` | number | no | Sampling temperature, provider default when omitted. |
| `max_tokens` | integer | no | Upper bound for the completion. Out-of-range values are rejected with a 400. |
| `tools` / `tool_choice` | array | no | Function calling, on models that support it. |

### Response

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "<model-id>",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 24, "completion_tokens": 118, "total_tokens": 142}
}
```

### Streaming

With `"stream": true` the response is `text/event-stream`: read `data:` lines
until `[DONE]`. A client disconnect before the first token is not billed for the
completion.

## Other text protocols

- `POST /v1/messages` — Anthropic Messages format.
- `POST /v1/responses` — OpenAI Responses format, including web-search tools where the model supports them.
- `POST /v1beta/models/{model}:generateContent` — Google Gemini format.

## Billing

A text call bills per token: input tokens (cache reads at the cache price,
cache writes at the cache-write price where the model prices one) and output
tokens, at the figures the model's price sets. The cost popover on a Usage Logs
row shows the per-token breakdown of the call.