# Chat completions The primary inference endpoint. OpenAI-shape requests and responses. `POST /v1/chat/completions` is the main inference endpoint: send a conversation in OpenAI's format and get the model's reply. Click **Try it** on the cURL tab to run the example against the demo API. **cURL** ```bash curl -s "https://api.privatemind.com/v1/chat/completions" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "fast", "messages": [ {"role": "system", "content": "You are a concise assistant."}, {"role": "user", "content": "Explain the CAP theorem."} ], "temperature": 0.2, "max_tokens": 400 }' ``` **Python** ```python from openai import OpenAI client = OpenAI( base_url="https://api.privatemind.com/v1", api_key="PMIND...:abcdef...", ) resp = client.chat.completions.create( model="fast", messages=[ {"role": "system", "content": "You are a concise assistant."}, {"role": "user", "content": "Explain the CAP theorem."}, ], temperature=0.2, max_tokens=400, ) print(resp.choices[0].message.content) ``` **TypeScript** ```typescript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.privatemind.com/v1', apiKey: process.env.PMIND_KEY, }); const resp = await client.chat.completions.create({ model: 'fast', messages: [ { role: 'system', content: 'You are a concise assistant.' }, { role: 'user', content: 'Explain the CAP theorem.' }, ], temperature: 0.2, max_tokens: 400, }); console.log(resp.choices[0].message.content); ``` ## Parameters - **`model`** (required): id of a model returned by [`GET /v1/models`](https://docs.privatemind.com/models.html). - **`messages`** (required): the conversation so far. Each entry has a `role` (`system`, `user`, `assistant`, or `tool`) and a `content` string. For multimodal input, such as images, `content` can be an array. See [Vision](https://docs.privatemind.com/vision.html). - **`temperature`** (default `1.0`): sampling temperature, `0` to `2`. Lower is more deterministic. - **`top_p`** (default `1.0`): nucleus sampling cutoff. - **`max_tokens`**: the most tokens to generate. It can't exceed the model's `context_length` minus the prompt. - **`stream`** (default `false`): when `true`, the response arrives in chunks as server-sent events (SSE). See [Streaming](https://docs.privatemind.com/streaming.html). - **`stop`**: up to four stop sequences. - **`tools`**: function definitions the model may call. See [Tool use](https://docs.privatemind.com/tool-use.html). - **`reasoning_effort`**: `"off"`, `"low"`, `"medium"`, `"high"` or `"max"`. Switches thinking on or off on hybrid models. See [Reasoning effort](https://docs.privatemind.com/chat-completions.html#reasoning-effort) below. - **`include_reasoning`** (default `true`): set `false` to leave the model's reasoning out of the response. The model still thinks and the tokens are still billed. See [Streaming → Reasoning output](https://docs.privatemind.com/streaming.html#reasoning-output). - **`metadata`**: up to 16 string key-value tags in OpenAI's format, for attributing the call. Keys can be up to 64 characters and values up to 512. Tags are stored with the call's usage, so you can query and roll up by them later. They are **never forwarded to the model**, except on a [No translation](https://docs.privatemind.com/model-deployments.html#no-translation) server, which gets the request as sent. See [Usage → Tagging requests](https://docs.privatemind.com/usage.html#tagging-requests). Other OpenAI fields (`presence_penalty`, `frequency_penalty`, `response_format`, `seed`) are forwarded to the model's engine. Whether they take effect depends on the model: check `supported_parameters` in `GET /v1/models`. The whole request body, base64 media included, can be up to 64 MB. A larger body gets `413` with `error.code` `request_too_large`. ## Reasoning effort `reasoning_effort` (optional) switches a model's thinking on or off, and sets its depth, without raw `chat_template_kwargs`. The values are: | Value | Meaning | | --- | --- | | `"off"` | Disable thinking. Only on models without `reasoning_mandatory`. | | `"low"` | Enable thinking at the lightest depth this deployment honours. | | `"medium"` | Enable thinking at a middle depth. | | `"high"` | Enable thinking at a deeper setting. | | `"max"` | Enable thinking at the deepest setting the deployment honours. | Each model lists the levels it tells apart in [`capabilities.reasoning_effort_levels`](https://docs.privatemind.com/models.html#capabilities). An enabling value not in the list goes to the nearest listed level, and a tie goes to the lower one. A model that thinks but lists no levels has one thinking setting. Every enabling value gets it, so on a thinking-only model the value changes nothing. What the API does with the value depends on the model's runtime contract, the catalog's record of whether and how the model thinks (see [Models](https://docs.privatemind.com/models.html)): | Runtime mode | Example models | `"off"` | Any enabling value | | --- | --- | --- | --- | | Hybrid | Qwen 3.8 27B, DeepSeek V4.1 Flash | Disables thinking | Enables thinking, at the depth the level maps to | | Thinking-only | Kimi K3.1 Pro, GLM 5.3 | `400` | Sets the depth; thinking cannot be turned off | | Non-thinking | KX qSQL (`qsql-qwen35-9b`) | Accepted, no effect | `400` | | No runtime contract | None in the catalog today | Accepted, no effect | Accepted, no effect | | [Model server you launched](https://docs.privatemind.com/model-deployments.html) | Your own | Sent to your vLLM as `"none"` | Sent to your vLLM as that level | A thinking-only model always thinks, and both thinking-only models above honour their published levels. A model server you launched has no runtime contract, so the value goes to your vLLM in its own `reasoning_effort` field, mapped as in the table. Your vLLM and the model's chat template decide what happens next, and a value your vLLM refuses comes back as its `400`. On a server with [No translation](https://docs.privatemind.com/model-deployments.html#no-translation) on, the field goes exactly as you sent it. > [!NOTE] > Omit `reasoning_effort` to get the model's default, published as [`capabilities.reasoning_effort_default`](https://docs.privatemind.com/models.html#capabilities) where the deployment declares one. ```bash curl -s "https://api.privatemind.com/v1/chat/completions" \ -H "Authorization: Bearer $PMIND_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "reasoning", "messages": [{"role": "user", "content": "Plan a four-step proof of Pythagoras."}], "reasoning_effort": "low" }' ``` > [!TIP] > You can also pass `chat_template_kwargs` directly, for a template parameter `reasoning_effort` doesn't cover. If you send both, `chat_template_kwargs` wins. ## Response ```json { "id": "chatcmpl-abc123", "object": "chat.completion", "model": "", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The CAP theorem ..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 42, "completion_tokens": 128, "total_tokens": 170 } } ``` Your key is billed on `usage.prompt_tokens` and `usage.completion_tokens`. ## Prompt caching Models hosted by PrivateMind cache recently processed prompts. When a request starts with the same content as an earlier one, that shared start is read from the cache and the answer begins sooner. There is nothing to switch on. The gain is largest on long prompts, such as a follow-up in a long conversation or a large document you ask several questions about. The cache matches from the first token forward and stops at the first difference, so the order of your request matters: - Keep the system prompt and tool definitions identical from one request to the next. Put anything that changes per request, such as the current time or a request id, in the last message, not the system prompt. - In a conversation, send the earlier messages back exactly as they were and append the new ones. Editing, trimming or reordering an earlier message means everything after it is processed again. - When asking several questions about the same document, put the document first and the question after it. `usage.prompt_tokens_details.cached_tokens` reports how much of the prompt was read from the cache: ```json "usage": { "prompt_tokens": 6060, "completion_tokens": 5, "total_tokens": 6065, "prompt_tokens_details": { "cached_tokens": 3200 } } ``` The cache works in fixed-size blocks, so `cached_tokens` is usually a little below the length of the shared start. A hit is likely but not guaranteed. Under heavy load, older entries are dropped to make room, and the next request with that start is processed in full. On a streamed response, the same field arrives in the final chunk's `usage`. ## Finish reasons | Value | Meaning | | --- | --- | | `stop` | Natural end of generation or a `stop` sequence matched | | `length` | Hit `max_tokens` or the context window | | `tool_calls` | The model wants to call one or more tools. See [Tool use](https://docs.privatemind.com/tool-use.html) | | `content_filter` | Output was blocked by a safety filter | ## Where next - [Streaming](https://docs.privatemind.com/streaming.html) for the SSE variant of this endpoint. - [Tool use](https://docs.privatemind.com/tool-use.html) for function calling on top of chat completions. - [Vision](https://docs.privatemind.com/vision.html) for the multimodal content-array shape. - [Models](https://docs.privatemind.com/models.html) to see what your org's models support.