Get API key

Chat completions

View as Markdown

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 -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
  }'
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)
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.
  • 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.
  • 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.
  • stop: up to four stop sequences.
  • tools: function definitions the model may call. See Tool use.
  • reasoning_effort: "off", "low", "medium", "high" or "max". Switches thinking on or off on hybrid models. See 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.
  • 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 server, which gets the request as sent. See Usage → 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. 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):

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 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 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 where the deployment declares one.

cURL
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": "<model-id>",
  "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
content_filter Output was blocked by a safety filter

Where next

  • Streaming for the SSE variant of this endpoint.
  • Tool use for function calling on top of chat completions.
  • Vision for the multimodal content-array shape.
  • Models to see what your org's models support.