---
title: "Create a chat completion"
method: POST
path: "/v2/llms/chat/completions"
tags: ["LLM Chat Completions"]
---

# Create a chat completion

`POST /v2/llms/chat/completions`

Creates a chat completion for a multi-turn chat through an OpenAI-compatible interface. Applications built for the OpenAI Chat Completions format can use the platform's language models with minimal changes to existing tools or code.

Use this endpoint for interactive chat experiences with context-aware responses, streaming output, and token usage tracking.

The request includes a series of chat messages and optional parameters that control the behavior and structure of the model response. The request body must include the `messages` parameter. This is an array of message objects (role, content) that represents the full conversation so far.

### Streaming responses

If the `stream` parameter is set to `true`, the response arrives as a series of text/event-stream parts (also known as chunks). Each chunk includes a `delta` field with the incremental message update.

### Example request

This example sends a simple chat conversation to the API, asking the model for the capital of France. The request includes a `system` message, a `user` message, and a temperature setting for response variability.
```json
{
  "model": "chat-model-001","messages": [{ "role": "system", "content": "You are a helpful assistant." },
  { "role": "user", "content": "What is the capital of France?" }
],
"temperature": 0.7,
"stream": false
}
```

### Example response
The response includes the model's `assistant` reply, along with token usage statistics. In this example, the model returns a direct answer to a user question.
```json
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1712454830,
"model": "chat-model-001",
"choices": [
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
  },
    "finish_reason": "stop"
  }
],
"usage": {
  "prompt_tokens": 21,
  "completion_tokens": 9,
  "total_tokens": 30
  } 
} 
```

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateChatCompletionRequest — The request object for creating a chat completion with an OpenAI-compatible interface. This object is compatible with OpenAI's chat completion schema and supports customizable parameters for response generation.
  - `model` string, required — The ID of the model to use. This field is required.
  - `messages` ChatCompletionRequestMessage[], required — An ordered array of messages that represent the full context of the conversation to date. Each message includes a `role` and `content`.
    - `role` string, required — The role of the author of this message. Common values include 'system', 'user', 'assistant', 'function', and 'tool'.
    - `content` unknown, required
    - `name` string — The name of the author of this message, used to connect messages in a conversation.
  - `stream` boolean — Optional. When set to `true`, the platform streams partial message deltas as they become available instead of returning the full message at once.
  - `response_format` ResponseFormat — Specifies the format the model must output. - `text`: Plain text responses (default). - `json_object`: Ensures the response is valid JSON. - `json_schema`: Ensures the response conforms to the provided JSON schema.
    - `type` 'json_schema' | 'json_object' | 'text', required — The format type. Use 'json_schema' for structured outputs, 'json_object' for basic JSON mode, or 'text' for plain text.
    - `json_schema` JsonSchemaSpec — A specification wrapper for a named JSON schema.
      - `description` string — A description of the purpose of the response format. The model uses this description to determine how to respond in the format.
      - `name` string, required — A unique name for this schema.
      - `strict` boolean, nullable — When true, enforces strict schema adherence. The model always follows the exact schema structure. In strict mode, the schema must follow these rules: - Set `additionalProperties: false` on all object types - List all properties in the `required` array - Maximum 100 properties total, with max 5 levels of nesting - Unsupported keywords: minLength, maxLength, pattern, minimum, maximum, minItems, maxItems - The root schema cannot use the `anyOf` type
      - `schema` union, required — A JSON Schema definition that describes a data structure. Covers the smallest subset of JSON Schema that all LLM providers support. Unknown keywords are kept and passed through to the provider. `properties`, `required`, and `additionalProperties` are valid only when `type` is `object`. `enum`, `format`, `items`, and `anyOf` are valid for every other `type`, and for an element with no `type`, such as one that only combines schemas with `anyOf`.
        - object — Keywords shared by every JSON Schema element.
          - `title` string — A short label for this schema element.
          - `description` string — A description of this schema element.
          - `default` unknown
          - `type` string, required — The JSON type of this schema element. Always `object`.
          - `properties` object — The object's properties. Each key maps to a nested schema.
          - `required` string[] — The property names that must be present.
          - `additionalProperties` boolean — Whether the object may have properties beyond those listed in `properties`.
        - object — Keywords shared by every JSON Schema element.
          - `title` string — A short label for this schema element.
          - `description` string — A description of this schema element.
          - `default` unknown
          - `type` string — The JSON type of this schema element. One of `array`, `string`, `number`, `integer`, `boolean`, or `null`. Omit it when the element only combines other schemas with `anyOf`.
          - `enum` unknown[] — The allowed values for this element.
            - unknown
          - `format` string — A semantic format hint, such as date-time, date, email, uri, or uuid. Provider support varies.
          - `items` JsonSchemaDefinition — recursive
          - `anyOf` JsonSchemaDefinition[] — A list of schemas. The value must match at least one of them.

## Response `200`

A chat completion

- CreateChatCompletionResponse — Response object containing the generated chat completion.
  - `object` 'chat.completion', required — The object type, which is always 'chat.completion'.
  - `choices` ChatCompletionResponseChoice[], required — A list of chat completion choices. Can be more than one if `n` is greater than `1`.
    - `index` integer, required — The index of the choice in the array of choices.
    - `message` ChatCompletionResponseMessage, required — A message in the chat completion response from the assistant.
      - `role` string, required — The role of the author of this message, typically 'assistant' for responses.

## Other responses

- `400` — Chat completion request was malformed.
- `403` — Permissions do not allow creating a chat completion.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/a95087fe3a20/schema)