Описание сервисов

Обновлено 1 декабря 2025

На этой странице вы найдете описание сервисов gRPC API GigaChat и примеры ответов.

Получить список моделей

Возвращает массив объектов с данными доступных моделей. Выполняется с пустым телом запроса.

Ответ:

{
  "data": [
    {
      "id": "GigaChat",
      "object": "model",
      "owned_by": "salutedevices",
      "type": "chat"
    }
  ],
  "object": "list"
}

data object[]

Array [

string

Название модели. Описание доступных моделей смотрите в разделе Модели GigaChat.

Модели в раннем доступе отмечены постфиксом -preview. Например, GigaChat-Pro-preview.

object

string

Тип сущности в ответе, например, модель.

owned_by

string

Владелец модели.

type

string

Возможные значения: [chat, aicheck, embedder]

Тип модели. Возможные значения:

chat — модель для генерации;
aicheck — модель для проверки, создан ли текст с помощью ИИ;
embedder — модель для создания эмбеддингов.

]

object

string

Тип сущности в ответе, например, список.

Получить модель

Возвращает объект с описанием указанной модели.

Параметры запроса:

model

string

Название модели. Описание доступных моделей смотрите в разделе Модели GigaChat.

Модели в раннем доступе отмечены постфиксом -preview. Например, GigaChat-Pro-preview.

Ответ:

{
  "id": "GigaChat",
  "object": "model",
  "owned_by": "salutedevices",
  "type": "chat"
}

string

Название модели. Описание доступных моделей смотрите в разделе Модели GigaChat.

Модели в раннем доступе отмечены постфиксом -preview. Например, GigaChat-Pro-preview.

object

string

Тип сущности в ответе, например, модель.

owned_by

string

Владелец модели.

type

string

Возможные значения: [chat, aicheck, embedder]

Тип модели. Возможные значения:

chat — модель для генерации;
aicheck — модель для проверки, создан ли текст с помощью ИИ;
embedder — модель для создания эмбеддингов.

Получить ответ модели

Возвращает ответ модели с учетом переданных сообщений.

Параметры запроса:

model

string

required

Название модели, котора должна обработать запрос. Описание доступных моделей смотрите в разделе Модели GigaChat.

При обращении к моделям в раннем доступе к названию модели нужно добавлять постфикс -preview.

messages object[]required

Массив сообщений, которыми пользователь обменивался с моделью.

В запросе можно передать только один системный промпт (сообщение с ролью system). Системный промпт должен быть первым сообщением в массиве.

Наличие в массиве нескольких системных промптов или передача системного промпта не в первом сообщении приведет к ошибке с кодом 422 и сообщением Invalid params: system message must be the first message.

Array [

role

string

Возможные значения: [user, system, assistant, function]

Роль автора сообщения:

system — системный промпт, который задает роль модели, например, должна модель отвечать как академик или как школьник;
assistant — ответ модели;
user — сообщение пользователя;
function — сообщение с результатом работы пользовательской функции. В сообщении с этой ролью передавайте результаты работы функции в поле content в форме валидного JSON-объекта, обернутого в строку.

Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе Работа с историей чата.

content

string

Содержимое сообщения. Зависит от роли.

Если поле передается в сообщении с ролью function, то в нем указывается обернутый в строку валидный JSON-объект с аргументами функции, указанной в поле function_call.name.

В остальных случаях содержит либо системный промпт (сообщение с ролью system), либо текст сообщения пользователя или модели.

Передавайте текст в кодировке UTF8. Это позволит снизить расход токенов при обработке сообщения.

functions_state_id

string<UUIDv4>

Идентификатор, который объединяет массив функций, переданных в запросе. Возвращается в ответе модели (сообщение с "role": "assistant") при вызове встроенных или собственных функций. Позволяет сохранить состояние обращения к функции и повысить качество работы модели. Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью assistant.

Сейчас поле работает только при обращении к моделям в раннем доступе.

attachments

string[]

Массив идентификаторов файлов, которые нужно использовать при генерации. Идентификатор присваивается файлу при загрузке в хранилище. Посмотреть список файлов в хранилище можно с помощью метода GET /files.

При работе с текстовыми документами в одном запросе на генерацию нужно передавать только один идентификатор. Если вы передадите несколько идентификаторов файлов, для генерации будет использован только первый файл из списка. При использовании больших текстовых файлов в запросах на генерацию, их содержимое может превышать размер контекста модели. В таком случае вернется ошибка с кодом 422.

В одном сообщении (объект в массиве messages) можно передать только одно изображение. В одной сессии можно передать до 10 изображений.

При этом общий размер запроса при работе с изображениями и аудио должен быть меньше 80 Мб.

Например, ваш запрос может включать текст промпта и идентификаторы изображения размером 12 Мб, и двух аудиофайлов размером 33 Мб и 21 Мб. Что в сумме даст запрос размером больше 66 Мб, в зависимости от размера промпта.

Размер текстовых документов не влияет на размер запроса, но их содержимое может превышать контекстное окно модели.

Подробнее — в разделе Обработка файлов

]

function_call object

Явно задает режим работы с функциями.

Возможные значения:

строка none;
строка auto;
объект {"name": "название_функции"}.

oneOf

string

Отключение работы с функциями.

Если передать none, модель не будет вызывать встроенные функции или генерировать аргументы для пользовательских функций, а просто сгенерирует ответ в соответствии с полученными сообщениями.

string

Автоматический режим работы с функциями.

В этом режиме модель, основываясь на тексте сообщений, решает нужно ли использовать одну из встроенных функций или сгенерировать аргументы для пользовательских функций, описанных в массиве functions. При этом, если массив содержит описание хотя бы одной пользовательской функции, модель сможет вызвать встроенную функцию, только если ее название передано в массиве functions:

{
  ,,,
  "function_call": "auto",
  "functions": [
	  {
        "name": "text2image"			
	  },
    {
        "name": "weather_forecast",
        "description": "Возвращает температуру на заданный период",
        "parameters": {}
    }
  ]
  ...
}

name

string

Работа с функциями в принудительном режиме.

В поле можно передать как название собственной функции, описание которой содержится в массиве functions, так и название одной из встроенных функций:

{
  ...
  "function_call": {
    "name": "weather_forecast"
  },
  "functions": [
    {
      "name": "weather_forecast",
      ...
    }
  ]
  ...
}

functions object[]nullable

Массив с описанием пользовательских функций.

Array [

name

string

required

Название пользовательской функции, для которой будут сгенерированы аргументы.

Название функции должно содержать только латинские буквы. Название функции не должно начинаться с цифры.

description

string

Текстовое описание функции.

parameters objectrequired

Валидный JSON-объект с набором пар ключ-значение, которые описывают аргументы функции.

object

few_shot_examples object[]

Объекты с парами запрос_пользователя-параметры_функции, которые будут служить модели примерами ожидаемого результата.

Array [

request

string

required

Запрос пользователя.

params objectrequired

Пример заполнения параметров пользовательской функции.

object

]

return_parameters object

JSON-объект с описанием параметров, которые может вернуть ваша функция.

object

]

temperature

number<float>

nullable

Возможные значения: >= 0 and > 0

Температура выборки регулирует степень случайности ответов модели. Высокое значение делает ответы разнообразными и неожиданными, низкое — предсказуемыми и стабильными. Когда температура меньше 0.001, включается режим строгого контроля, дающий одинаковые ответы. А при температуре больше 2 реакция становится чрезмерно беспорядочной.

Базовое значение температуры зависит от модели, которая генерирует ответ, и меняется вместе с улучшениями модели.

top_p

number<float>

nullable

Возможные значения: >= 0 и >= 0 and <= 1

Параметр используется как альтернатива температуре (поле temperature). Задает вероятностную массу токенов, которые должна учитывать модель. Так, если передать значение 0.1, модель будет учитывать только токены, чья вероятностная масса входит в верхние 10%.

Значение по умолчанию зависит от выбранной модели (поле model) и может изменяться с обновлениями модели.

Значение изменяется в диапазоне от 0 до 1 включительно.

stream

boolean

По умолчанию: false

Указывает, что сообщения надо передавать по частям в потоке.

Сообщения передаются по протоколу SSE .

Поток завершается событием data: [DONE].

Подробнее читайте в разделе Потоковая генерация токенов.

max_tokens

integer<int32>

nullable

Возможные значения: > 0

Максимальное количество токенов, которые будут использованы для создания ответов.

repetition_penalty

number<float>

nullable

Количество повторений слов:

Значение 1.0 — нейтральное значение.
При значении больше 1 модель будет стараться не повторять слова.

Значение по умолчанию зависит от выбранной модели (поле model) и может изменяться с обновлениями модели.

update_interval

number

По умолчанию: 0

Параметр потокового режима ("stream": "true"). Задает минимальный интервал в секундах, который проходит между отправкой токенов. Например, если указать 1, сообщения будут приходить каждую секунду, но размер каждого из них будет больше, так как за секунду накапливается много токенов.

Ответ:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Здравствуйте! К сожалению, я не могу дать точный ответ на этот вопрос, так как это зависит от многих факторов. Однако обычно релиз новых функций и обновлений в GigaChat происходит постепенно и незаметно для пользователей. Рекомендую следить за новостями и обновлениями проекта в официальном сообществе GigaChat или на сайте разработчиков.",
        "created": 1625284800,
        "name": "text2image",
        "functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003",
        "function_call": {
          "name": "string",
          "arguments": {}
        }
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "created": 1678878333,
  "model": "GigaChat",
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 68,
    "total_tokens": 86
  },
  "object": "chat.completion"
}

choices object[]

Массив ответов модели.

Array [

message object

Сгенерированное сообщение.

role

string

Возможные значения: [assistant, function_in_progress]

Роль автора сообщения.

Роль function_in_progress используется при работе встроенных функций в режиме потоковой передачи токенов.

content

string

Содержимое сообщения, например, результат генерации. При передаче в режиме потоковой генерации передается частями. В предпосленем сообщении передаеся пустая строка "".

В сообщениях с ролью function_in_progress содержит информацию о том, сколько времени осталось до завершения работы встроенной функции.

created

integer<unix timestamp>

Передается в сообщениях с рольюfunction_in_progress. Содержит информацию о том, когда был создан фрагмент сообщения.

name

string

Название вызванной встроенной функции. Передается в сообщениях с рольюfunction_in_progress. Возможные значения:

text2image - генерация изображения на основе описания;
text2model3d — генерация 3D-модели на основе описания.

functions_state_id

string<UUIDv4>

Идентификатор, который объединяет массив функций, переданных в запросе. Возвращается в ответе модели (сообщение с "role": "assistant") при вызове встроенных или собственных функций. Позволяет сохранить контекст вызова функции и повысить качество работы модели. Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью assistant.

Сейчас поле работает только при обращении к моделям в раннем доступе.

function_call object

name

string

Название функции.

arguments

object

Аргументы для вызова функции в виде пар ключ-значение.

index

integer<int32>

Индекс сообщения в массиве, начиная с ноля.

finish_reason

string

Возможные значения: [stop, length, function_call, blacklist, error]

Причина завершения гипотезы. Возможные значения:

stop — модель закончила формировать гипотезу и вернула полный ответ;
length — достигнут лимит токенов в сообщении;
function_call — указывает, что при запросе была вызвана встроенная функция или сгенерированы аргументы для пользовательской функции;
blacklist — запрос попадает под тематические ограничения.
error — ответ модели содержит невалидные аргументы пользовательской функции.

При работе в режиме потоковой генерации передается в предпоследнем событии со значением.

]

created

integer<unix timestamp>

Дата и время создания ответа в формате unix timestamp.

model

string

Название и версия модели, которая обработала запрос.

usage object

Данные об использовании модели. При запуске потоковой генерации, объект приходит в предпоследнем событии.

prompt_tokens

integer<int32>

Количество токенов во входящем сообщении (роль user).

completion_tokens

integer<int32>

Количество токенов, сгенерированных моделью (роль assistant).

precached_prompt_tokens

integer<int32>

Количество ранее закэшированных токенов, которые были использованы при обработке запроса. Кэшированные токены вычитаются из общего числа оплачиваемых токенов (поле total_tokens).

Модели GigaChat в течение некоторого времени сохраняют контекст запроса (историю сообщений массива messages, описание функций) с помощью кэширования токенов. Это позволяет повысить скорость ответа моделей и снизить стоимость работы с GigaChat API.

Для повышения вероятности использования сохраненных токенов используйте кэширование запросов.

Подробнее о подсчете токенов.

total_tokens

integer<int32>

Общее число токенов, подлежащих тарификации, после вычитания кэшированных токенов (поле precached_prompt_tokens).

object

string

Название вызываемого метода.

Смотрите также

Примеры использования

Примеры использования библиотеки в репозитории

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Получить список моделей﻿

Получить модель﻿

Получить ответ модели﻿

Получить список моделей

Получить модель

Получить ответ модели