> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokmodel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/chat/completions

> OpenAI-compatible chat completions endpoint. Send a list of messages and receive a model-generated reply, with optional streaming support.

The `/v1/chat/completions` endpoint accepts a conversation as an array of messages and returns a model-generated response. It is fully compatible with the OpenAI Chat Completions API, so any client or library that targets OpenAI can be pointed at TokModel by changing only the base URL and API key. You can stream responses token-by-token using server-sent events (SSE) by setting `stream` to `true`.

## Request parameters

<ParamField body="model" type="string" required>
  The ID of the model to use for this request. Use the [list models](/api-reference/models) endpoint to retrieve available model IDs.
</ParamField>

<ParamField body="messages" type="array" required>
  An array of message objects that make up the conversation. Each object must include a `role` (`"system"`, `"user"`, or `"assistant"`) and a `content` string.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  When `true`, the response is streamed as server-sent events. Each event contains a partial `ChatCompletionChunk` object. The stream terminates with `data: [DONE]`.
</ParamField>

<ParamField body="temperature" type="number" default="1">
  Sampling temperature between `0` and `2`. Lower values produce more deterministic output; higher values produce more varied output. Avoid setting both `temperature` and `top_p` at the same time.
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens to generate in the response. The model will stop once this limit is reached, even if the response is incomplete.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling parameter. The model considers only the tokens comprising the top `top_p` probability mass. A value of `0.1` means only the top 10% of probability mass is considered.
</ParamField>

<ParamField body="n" type="integer" default="1">
  How many independent completion choices to generate for each request. Each choice is billed separately.
</ParamField>

<ParamField body="stop" type="string | string[]">
  One or more sequences at which the model will stop generating further tokens. The stop sequence itself is not included in the response.
</ParamField>

## Response fields

<ResponseField name="id" type="string">
  A unique identifier for this completion, prefixed with `chatcmpl-`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (seconds) of when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model that was used to generate the response.
</ResponseField>

<ResponseField name="choices" type="array">
  An array of completion choices. Contains `n` items when `n` is set.

  <Expandable title="properties">
    <ResponseField name="index" type="integer">
      Zero-based index of this choice in the `choices` array.
    </ResponseField>

    <ResponseField name="message" type="object">
      The generated message object.

      <Expandable title="properties">
        <ResponseField name="role" type="string">
          Always `"assistant"` for generated messages.
        </ResponseField>

        <ResponseField name="content" type="string">
          The text content of the generated message.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      Why the model stopped generating. One of `"stop"` (natural end or stop sequence reached), `"length"` (max tokens reached), or `"content_filter"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage for the request.

  <Expandable title="properties">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens in the input messages.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Number of tokens in the generated response.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens consumed (`prompt_tokens` + `completion_tokens`).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Request

```bash theme={null}
curl https://tokmodel.com/v1/chat/completions \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4o",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is the capital of France?" }
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'
```

### Response

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1716470400,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 9,
    "total_tokens": 35
  }
}
```