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

# Create a chat completion

Отправляет запрос на получение ответа модели для указанной чат-беседы. Поддерживает как потоковый, так и непотоковый режимы. Совместим с форматом API OpenAI Chat Completions.

## Аутентификация

<ParamField header="Authorization" type="string" required>
  Bearer-токен. Используйте ваш API-ключ в качестве Bearer-токена в заголовке Authorization.

  Формат: `Bearer <SUNRA_KEY>`
</ParamField>

## Запрос

Этот эндпоинт принимает объект.

<ParamField body="messages" type="object[]" required>
  Список сообщений для беседы.

  <Expandable title="properties">
    <ParamField body="role" type="string" required>
      Роль автора сообщения. Поддерживаемые значения: `system`, `user`, `assistant`, `tool`.
    </ParamField>

    <ParamField body="content" type="string | object[]" required>
      Содержание сообщения. Может быть строкой или массивом частей контента для мультимодального ввода.
    </ParamField>

    <ParamField body="name" type="string">
      Необязательное имя участника. Предоставляет модели информацию для различения участников с одинаковой ролью.
    </ParamField>

    <ParamField body="tool_calls" type="object[]">
      Вызовы инструментов, сгенерированные моделью, такие как вызовы функций. Присутствует только в сообщениях `assistant`.
    </ParamField>

    <ParamField body="tool_call_id" type="string">
      Вызов инструмента, на который отвечает это сообщение. Присутствует только в сообщениях `tool`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="model" type="string" required>
  Модель, используемая для завершения. Просмотрите доступные модели на [sunra.ai/models](https://sunra.ai/models).
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  Если установлено значение `true`, частичные дельты сообщений будут отправляться как Server-Sent Events (SSE).
</ParamField>

<ParamField body="max_tokens" type="integer">
  Максимальное количество токенов для генерации в завершении. Общая длина входных токенов и сгенерированных токенов ограничена длиной контекста модели.
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  Температура сэмплирования от 0 до 2. Более высокие значения, такие как 0.8, делают вывод более случайным, более низкие значения, такие как 0.2, делают его более сфокусированным и детерминированным.
</ParamField>

<ParamField body="top_p" type="number" default={1}>
  Параметр nucleus-сэмплирования (0-1). Альтернатива сэмплированию по температуре, при которой модель учитывает токены с массой вероятности top\_p.
</ParamField>

<ParamField body="frequency_penalty" type="number" default={0}>
  Число от -2.0 до 2.0. Положительные значения штрафуют новые токены на основе их существующей частоты в тексте, уменьшая вероятность дословного повторения одной и той же строки.
</ParamField>

<ParamField body="presence_penalty" type="number" default={0}>
  Число от -2.0 до 2.0. Положительные значения штрафуют новые токены на основе их присутствия в тексте, увеличивая вероятность того, что модель затронет новые темы.
</ParamField>

<ParamField body="stop" type="string | string[]">
  До 4 последовательностей, при которых API прекратит генерацию дальнейших токенов.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  Сколько вариантов завершения чата генерировать для каждого входного сообщения.
</ParamField>

<ParamField body="logprobs" type="boolean" default={false}>
  Возвращать ли логарифмические вероятности выходных токенов. Если true, возвращает логарифмические вероятности каждого выходного токена, возвращённого в содержании сообщения.
</ParamField>

<ParamField body="top_logprobs" type="integer">
  Целое число от 0 до 20, определяющее количество наиболее вероятных токенов, возвращаемых в каждой позиции токена. `logprobs` должен быть установлен в `true` при использовании этого параметра.
</ParamField>

<ParamField body="response_format" type="object">
  Объект, определяющий формат, который должна выводить модель.

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      Тип формата ответа. Поддерживаемые значения: `text`, `json_object`, `json_schema`.
    </ParamField>

    <ParamField body="json_schema" type="object">
      Объект JSON-схемы. Обязателен, когда type — `json_schema`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="seed" type="integer">
  Если указано, система приложит максимум усилий для детерминированного сэмплирования, чтобы повторные запросы с одинаковым seed и параметрами возвращали одинаковый результат.
</ParamField>

<ParamField body="tools" type="object[]">
  Список инструментов, которые модель может вызвать. В настоящее время в качестве инструмента поддерживаются только функции.

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      Тип инструмента. В настоящее время поддерживается только `function`.
    </ParamField>

    <ParamField body="function" type="object" required>
      Определение функции.

      <Expandable title="properties">
        <ParamField body="name" type="string" required>
          Имя вызываемой функции.
        </ParamField>

        <ParamField body="description" type="string">
          Описание того, что делает функция.
        </ParamField>

        <ParamField body="parameters" type="object">
          Параметры, принимаемые функцией, описанные как объект JSON Schema.
        </ParamField>

        <ParamField body="strict" type="boolean" default={false}>
          Включить ли строгое соблюдение схемы.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Управляет тем, какой (если есть) инструмент вызывается моделью. `none` означает, что модель не будет вызывать никаких инструментов. `auto` означает, что модель может выбирать между генерацией сообщения и вызовом инструментов. `required` означает, что модель должна вызвать один или несколько инструментов. Также можно указать конкретную функцию через `{"type": "function", "function": {"name": "my_function"}}`.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default={true}>
  Разрешить ли параллельные вызовы функций во время использования инструментов.
</ParamField>

<ParamField body="user" type="string">
  Уникальный идентификатор вашего конечного пользователя, который может помочь в мониторинге и обнаружении злоупотреблений.
</ParamField>

## Ответ

Успешный ответ завершения чата.

<ResponseField name="id" type="string">
  Уникальный идентификатор завершения чата.
</ResponseField>

<ResponseField name="object" type="string">
  Тип объекта. Всегда `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix-временная метка (в секундах) создания завершения чата.
</ResponseField>

<ResponseField name="model" type="string">
  Модель, использованная для завершения чата.
</ResponseField>

<ResponseField name="choices" type="object[]">
  Список вариантов завершения чата. Может быть более одного, если `n` больше 1.

  <Expandable title="properties">
    <ResponseField name="index" type="integer">
      Индекс варианта в списке вариантов.
    </ResponseField>

    <ResponseField name="message" type="object">
      Сообщение завершения чата, сгенерированное моделью.

      <Expandable title="properties">
        <ResponseField name="role" type="string">
          Роль автора этого сообщения. Всегда `assistant`.
        </ResponseField>

        <ResponseField name="content" type="string | null">
          Содержание сообщения.
        </ResponseField>

        <ResponseField name="tool_calls" type="object[]">
          Вызовы инструментов, сгенерированные моделью, такие как вызовы функций.

          <Expandable title="properties">
            <ResponseField name="id" type="string">
              Идентификатор вызова инструмента.
            </ResponseField>

            <ResponseField name="type" type="string">
              Тип инструмента. В настоящее время поддерживается только `function`.
            </ResponseField>

            <ResponseField name="function" type="object">
              Функция, вызванная моделью.

              <Expandable title="properties">
                <ResponseField name="name" type="string">
                  Имя вызываемой функции.
                </ResponseField>

                <ResponseField name="arguments" type="string">
                  Аргументы для вызова функции, сгенерированные моделью в формате JSON.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      Причина остановки генерации токенов моделью. Может быть `stop`, `length`, `tool_calls` или `content_filter`.
    </ResponseField>

    <ResponseField name="logprobs" type="object | null">
      Информация о логарифмических вероятностях для данного варианта.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Статистика использования для запроса завершения.

  <Expandable title="properties">
    <ResponseField name="prompt_tokens" type="integer">
      Количество токенов в промпте.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Количество токенов в сгенерированном завершении.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Общее количество токенов, использованных в запросе (промпт + завершение).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="system_fingerprint" type="string | null">
  Этот отпечаток представляет конфигурацию бэкенда, на которой работает модель. Может использоваться с параметром `seed` для отслеживания изменений в бэкенде.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant."
        },
        {
          "role": "user",
          "content": "What is the capital of France?"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-llm.sunra.ai/v1/chat/completions",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "openai/gpt-4o",
          "messages": [
              {"role": "system", "content": "You are a helpful assistant."},
              {"role": "user", "content": "What is the capital of France?"}
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "openai/gpt-4o",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is the capital of France?" }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "openai/gpt-4o",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "The capital of France is Paris."
        },
        "finish_reason": "stop",
        "logprobs": null
      }
    ],
    "system_fingerprint": "fp_44709d6fcb",
    "usage": {
      "prompt_tokens": 25,
      "completion_tokens": 8,
      "total_tokens": 33
    }
  }
  ```
</ResponseExample>