> For the complete documentation index, see [llms.txt](https://docs.mashagpt.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mashagpt.ru/api/chat.md).

# Чат

Получая историю сообщений, дополняет диалог от лица ассистента

## Объект `chat.completion`

Представляет ответ дополнения чата, возвращаемый моделью на основе предоставленных входных данных.

***

**id**  string\
Уникальный идентификатор объекта.

***

**choices**  array\
Список вариантов дополнения чата. Может быть больше одного, если `n` больше 1.

<details>

<summary>Параметры</summary>

***

**finish\_reason**  string\
Причина, по которой модель перестала генерировать токены. Это будет `stop`, если модель достигнет естественной точки остановки или предоставленной последовательности остановки, `length`, если достигнуто максимальное количество токенов, указанное в запросе, `content_filter`, если контент был пропущен из-за флага наших фильтров контента, или `function_call`, если модель вызвала функцию.

***

**index**  integer\
Индекс варианта в списке вариантов. (Не обязательно совпадает с индексом в массиве `choices`)

***

**message**  object

* **content**  string | null\
  Содержание сообщения
* **function\_call**  object\
  Имя и аргументы функции которая должная быть вызвана по мнению модели
  * **name**  string\
    Имя функции которую следует вызвать
  * **arguments**  string\
    Аргументы для вызова функции, сгенерированные моделью в формате JSON. Обратите внимание, что модель не всегда генерирует действительный JSON и может выдавать параметры, не определенные схемой вашей функции. Проверьте аргументы в своем коде перед вызовом функции.
* **role**  string\
  Роль автора сообщения. Может быть: `system`, `assistant`, `user`, `function`

</details>

***

**created**  integer\
Unix timestamp (секунды) момента времени когда дополнение было создано

***

**model**  string\
Модель которая использовалась для генерации дополнения чата.

***

**object**  string\
Тип объекта, который всегда `chat.completion`.

***

**usage**  object\
Статистика использованных токенов и энергии при генерации

<details>

<summary>Параметры</summary>

***

**completion\_tokens**  integer\
Количество токенов в ответе модели

***

**prompt\_tokens**  integer\
Количество токенов на входе (включая `functions`)

***

**total\_tokens**  integer\
Общее количество токенов использованных в запросе (prompt + completion)

***

**completion\_energy**  integer\
Количество энергии затраченной на генерацию ответа

***

**prompt\_energy**  integer\
Количество энергии затраченной на обработку ввода

***

**total\_energy**  integer\
Общее количество энергии затраченной на запрос

</details>

***

{% code title="chat.completion" lineNumbers="true" %}

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0613",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\n\nHello there, how may I assist you today?",
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_energy": 9,
    "completion_energy": 12,
    "total_energy": 21
  }
}
```

{% endcode %}

***

## Объект `chat.completion.chunk`

Представляет ответ дополнения чата, возвращаемый моделью на основе предоставленных входных данных при использовании `stream: true`.

***

**id**  string\
Уникальный идентификатор дополнения. Каждый чанк имеет одинаковый id.

***

**choices**  array\
Список вариантов дополнения чата. Может быть больше одного, если `n` больше 1.

<details>

<summary>Параметры</summary>

***

**finish\_reason**  string\
Причина, по которой модель перестала генерировать токены. Это будет `stop`, если модель достигнет естественной точки остановки или предоставленной последовательности остановки, `length`, если достигнуто максимальное количество токенов, указанное в запросе, `content_filter`, если контент был пропущен из-за флага наших фильтров контента, или `function_call`, если модель вызвала функцию.

***

**index**  integer\
Индекс варианта в списке вариантов. (Не обязательно совпадает с индексом в массиве `choices`)

***

**delta**  object

* **content**  string | null\
  Содержание чанка (часть итогового сообщения)
* **function\_call**  object\
  Имя и аргументы функции которая должная быть вызвана по мнению модели\
  Следует иметь ввиду что в одном чанке может содержаться только часть имени или аргументов фукнции. Для того чтобы получить полностью имя функции и её аргументы - необходимо сложить все полученные куски.
  * **name**  string\
    Имя функции которую следует вызвать
  * **arguments**  string\
    Аргументы для вызова функции, сгенерированные моделью в формате JSON. Обратите внимание, что модель не всегда генерирует действительный JSON и может выдавать параметры, не определенные схемой вашей функции. Проверьте аргументы в своем коде перед вызовом функции.
* **role**  string\
  Роль автора сообщения. Может быть: `system`, `assistant`, `user`, `function`

</details>

***

**created**  integer\
Unix timestamp (секунды) момента времени когда дополнение было создано. Каждый чанк имеет одинаковое время.

***

**model**  string\
Модель которая использовалась для генерации дополнения чата.

***

**object**  string\
Тип объекта, который всегда `chat.completion.chunk`.

***

{% code title="chat.completion.chunk" lineNumbers="true" %}

```json
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

....

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":" today"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"?"},"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
```

{% endcode %}

***

## Дополнение чата

<mark style="color:green;">`POST`</mark> `https://api.mashagpt.ru/v1/chat/completions`

Модель создает ответа для данного разговора в чате.

#### Request Body

| Name                                                                   | Type                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| messages<mark style="color:red;">\*</mark>                             | Array                   | Список сообщений в беседе. Необходимо предоставлять полную историю сообщений.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| messages\[].content<mark style="color:red;">\*</mark>                  | String \| null          | Содержание сообщения. `content` требуется для всех сообщений и может быть `null` для сообщений ассистента с вызовом функции.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| messages\[].function\_call                                             | Object                  | Имя и аргументы функции которая должная быть вызвана по мнению модели                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| messages\[].function\_call.name<mark style="color:red;">\*</mark>      | String                  | Имя функции которую следует вызвать                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| messages\[].function\_call.arguments<mark style="color:red;">\*</mark> | String                  | Аргументы для вызова функции, сгенерированные моделью в формате JSON. Обратите внимание, что модель не всегда генерирует действительный JSON и может выдавать параметры, не определенные схемой вашей функции. Проверьте аргументы в своем коде перед вызовом функции.                                                                                                                                                                                                                                                                                           |
| messages\[].name                                                       | String                  | Имя автора этого сообщения. `name` требуется, если `role: function`, и это должно быть имя функции, ответ которой находится в содержимом. Может содержать буквы A–Z, A–Z, 0–9 и символы подчеркивания, максимальная длина — 64 символа.                                                                                                                                                                                                                                                                                                                          |
| messages\[].role                                                       | String                  | Роль автора сообщения. Может быть: `system`, `assistant`, `user`, `function`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| model<mark style="color:red;">\*</mark>                                | String                  | Идентификатор модели, которую нужно использовать. Подробную информацию о том, какие модели работают с Chat API, см. в [таблице совместимости](https://docs.mashagpt.ru/quickstart/models/compatibility.md).                                                                                                                                                                                                                                                                                                                                                      |
| frequency\_penalty                                                     | Number \| null          | Число от -2,0 до 2,0. Положительные значения штрафуют новые токены на основе их частоты в тексте, уменьшая вероятность повторения модели дословно одной и той же строки.                                                                                                                                                                                                                                                                                                                                                                                         |
| function\_call                                                         | String \| Object        | Управляет тем, как модель вызывает функции. `"none"` означает, что модель не будет вызывать функцию, а вместо этого генерирует сообщение. `"auto"` означает, что модель может выбирать между генерацией сообщения или вызовом функции. Указание конкретной функции через `{"name": "my_function"}` заставляет модель вызывать эту функцию. `"none"` — значение по умолчанию, когда функции отсутствуют. `"auto"` — значение по умолчанию, если присутствуют функции.                                                                                             |
| functions                                                              | Array                   | Список функций которые модель может вызвать.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| functions\[].description                                               | String                  | Описание функции которое используется моделью для определения подходящей функции для вызова.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| functions\[].name<mark style="color:red;">\*</mark>                    | String                  | Имя вызываемой функции. Должны быть от A до Z, от A до Z, от 0 до 9 или содержать символы подчеркивания и тире, максимальная длина — 64.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| functions\[].parameters<mark style="color:red;">\*</mark>              | Object                  | <p>Параметры, принимаемые функциями, описываемые как объект схемы JSON. Документацию по формату см. в <a href="https://json-schema.org/understanding-json-schema/">справочнике по схеме JSON</a>.</p><p>Чтобы описать функцию, которая не принимает никаких параметров, укажите значение <code>{"type": "object", "properties": {}}</code>.</p>                                                                                                                                                                                                                  |
| logit\_bias                                                            | Map                     | <p>Измените вероятность появления указанных токенов в завершении.</p><p>Принимает объект json, который сопоставляет токены (указанные их идентификатором в токенизаторе) со связанным значением смещения от -100 до 100. Математически смещение добавляется к логитам, сгенерированным моделью перед выборкой. Точный эффект будет варьироваться в зависимости от модели, но значения от -1 до 1 должны уменьшать или увеличивать вероятность выбора; значения типа -100 или 100 должны привести к запрету или эксклюзивному выбору соответствующего токена.</p> |
| max\_tokens                                                            | Integer \| null         | <p>Максимальное количество <a href="https://docs.mashagpt.ru/quickstart/intro.md#tokeny">токенов</a>, которые можно сгенерировать при дополнении чата.</p><p>Общая длина входных токенов и сгенерированных токенов ограничена <a href="https://docs.mashagpt.ru/quickstart/models/gpt-4o-mini.md">длиной контекста модели</a>.</p>                                                                                                                                                                                                                               |
| n                                                                      | Integer \| null         | Количество вариантов дополнения чата которые сгенерирует модель                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| presence\_penalty                                                      | Number \| null          | Число от -2,0 до 2,0. Положительные значения штрафует новые токены в зависимости от частоты их появления в тексте, что увеличивает вероятность того, что модель будет говорить о новых темах.                                                                                                                                                                                                                                                                                                                                                                    |
| stop                                                                   | String \| Array \| null | До 4 последовательностей, при которых API перестанет генерировать дальнейшие токены.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| stream                                                                 | Boolean \| null         | Если установлено, будут отправляться частичные дельты сообщений, как в ChatGPT. Токены будут отправляться как [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format), по мере их доступности, а поток завершается сообщением `data: [DONE]`.                                                                                                                                                                                                                                     |
| temperature                                                            | Number \| null          | <p>Какую температуру выборки использовать: от 0 до 2. Более высокие значения, например 0,8, сделают выходные данные более случайными, а более низкие значения, например 0,2, сделают их более детерминированными.</p><p>В общем случае мы рекомендуем использовать этот параметр или <code>top\_p</code>, но не оба сразу.</p>                                                                                                                                                                                                                                   |
| top\_p                                                                 | Number \| null          | <p>Альтернатива выборке с учетом температуры, называемая nucleus sampling, где модель учитывает результаты токенов с вероятностной массой <code>top\_p</code>. Таким образом, 0,1 означает, что учитываются только токены, составляющие 10% верхней массы вероятности.</p><p>В общем случае мы рекомендуем использовать этот параметр или <code>temperature</code>, но не оба сразу.</p>                                                                                                                                                                         |
| user                                                                   | String                  | Уникальный идентификатор пользователя                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

{% tabs %}
{% tab title="200: OK " %}
Возвращает объект [`chat.completion`](#obekt-chat.completion) или серию объектов [`chat.completion.chunk`](#obekt-chat.completion.chunk) в формате server-sent events если выбрана опция `stream: true`.
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="NO STREAMING" %}
{% code title="Пример запроса" lineNumbers="true" %}

```bash
curl https://api.mashagpt.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MASHAGPT_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'
```

{% endcode %}

{% code title="Ответ" lineNumbers="true" %}

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo-0613",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\n\nHello there, how may I assist you today?",
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_energy": 9,
    "completion_energy": 12,
    "total_energy": 21
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="STREAMING" %}
{% code title="Пример запроса" lineNumbers="true" %}

```bash
curl https://api.mashagpt.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MASHAGPT_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "stream": true
  }'
```

{% endcode %}

{% code title="Пример ответа" lineNumbers="true" %}

```json
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
....
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":" today"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"?"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
[DONE]
```

{% endcode %}
{% endtab %}

{% tab title="FUNCTION CALLING" %}
{% code title="Пример запроса" lineNumbers="true" %}

```bash
curl https://api.mashagpt.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MASHAGPT_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "functions": [
      {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    ],
    "function_call": "auto"
  }'
```

{% endcode %}

{% code title="Пример ответа" lineNumbers="true" %}

```json
{
  "choices": [
    {
      "finish_reason": "function_call",
      "index": 0,
      "message": {
        "content": null,
        "function_call": {
          "arguments": "{\n  \"location\": \"Boston, MA\"\n}",
          "name": "get_current_weather"
        },
        "role": "assistant"
      }
    }
  ],
  "created": 1694028367,
  "model": "gpt-3.5-turbo-0613",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 18,
    "prompt_tokens": 82,
    "total_tokens": 100,
    "prompt_energy": 82,
    "completion_energy": 18,
    "total_energy": 100
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}
