openapi: 3.0.3 info: title: GigaChat API version: 1.0.0 contact: name: GigaChat API url: 'https://developers.sber.ru/portal/products/gigachat-api' email: gigachat@sberbank.ru description: | В этом разделе вы узнаете как получить токен доступа и авторизовать запросы к GigaChat API. ## Получение токена доступа Чтобы получить токен, отправьте запрос # START_RAW# END_RAW: ```sh curl -L -X POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Accept: application/json' \ -H 'RqUID: <идентификатор_запроса>' \ -H 'Authorization: Basic ключ_авторизации' \ --data-urlencode 'scope=GIGACHAT_API_PERS' ``` Где: * `RqUID` — обязательный заголовок, в котором нужно передать уникальный идентификатор запроса в формате `uuid4`. Идентификатор нужно указать самостоятельно, для этого можно использовать стандартные библиотеки и классы для генерации UUID и GUID. * `Authorization` — обязательный заголовок, в котором нужно передать [ключ авторизации](/ru/gigachat/quickstart/ind-using-api#poluchenie-avtorizatsionnyh-dannyh). * `scope` — обязательное поле в теле запроса, которое указывает, к какой версии API выполняется запрос. Возможные значения: * `GIGACHAT_API_PERS` — доступ для физических лиц. * `GIGACHAT_API_B2B` — доступ для ИП и юридических лиц по [платным пакетам](/ru/gigachat/quickstart/legal-tokens-purchase#pokupka-paketov). * `GIGACHAT_API_CORP` — доступ для ИП и юридических лиц по схеме [pay-as-you-go](/ru/gigachat/quickstart/legal-tokens-purchase#oplata-pay-as-you-go). При успешном выполнении запроса GigaChat API вернет токен доступа, который действует в течение 30 минут: ```json { "access_token": "eyJhbGci3iJkaXIiLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIn0..Dx7iF7cCxL8SSTKx.Uu9bPK3tPe_crdhOJqU3fmgJo_Ffvt4UsbTG6Nn0CHghuZgA4mD9qiUiSVC--okoGFkjO77W.vjYrk3T7vGM6SoxytPkDJw", "expires_at": 1679471442 } ``` Запросы на получение токена можно отправлять до 10 раз в секунду. :::note Как получить ключ авторизации и токен доступа Access token читайте в разделах [Быстрый старт для физических лиц](/ru/gigachat/individuals-quickstart) и [Быстрый старт для ИП и юридических лиц](/ru/gigachat/legal-quickstart). ::: ## Выбор базового адреса и авторизация запросов Для отправки запросов в GigaChat API доступно два базовых адреса. | Название | Адрес | Описание | | ----------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Основной | `https://gigachat.devices.sberbank.ru/api/v1` | Для физлиц и юрлиц, которые оплачивают работу с API по счету-оферте или по договору с ООО «СалютДевайсы» | | Салют для Бизнеса | `https://api.giga.chat/v1` | Для юрлиц, которые оплачивают работу с API по договору с ООО «Салют для Бизнеса» | Для авторизации запросов передавайте токен доступа в заголовке `Authorization`. Пример запроса на получение списка моделей: # START_RAW # END_RAW ```sh curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/models' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <токен_доступа>' ``` # START_RAW # END_RAW ```sh curl -L -X GET 'https://api.giga.chat/v1/models' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer <токен_доступа>' ``` # START_RAW # END_RAW ## Обращение к моделям в раннем доступе Модели для генерации GigaChat регулярно обновляются, и у них появляются новые возможности, например, вызов функций. В таких случаях новые версии моделей некоторое время доступны в раннем доступе. Подробнее — в разделе [Модели GigaChat](/ru/gigachat/guides/preview-models). servers: - url: https://gigachat.devices.sberbank.ru/api/v1 description: Основной - url: https://api.giga.chat/v1 description: Салют для Бизнеса tags: - name: models description: Запросы для получения данных доступных моделей. - name: batches x-displayName: Пакеты запросов description: | # Пакеты запросов Пакетный режим предназначен для асинхронной обработки большого объема данных. Подходит для задач, которые не требуют немедленного ответа, например: * Разметка или классификация массивов данных. * Расчет эмбеддингов для крупных наборов данных. Пакетный режим доступен только ИП и юридическим лицам при оплате по схеме [pay-as-you-go](/ru/gigachat/api/tariffs#oplata-pay-as-you-go). - name: functions x-displayName: Функции description: | # Функции В этом разделе описаны методы, облегчающие работу с собственными функциями при работе GigaChat API. # START_RAW
Подробнее о функциях # END_RAW Функции — ключевой элемент для построения сложных решений с применением LLM, таких, как AI-агенты и ассистенты. Они представляют внешние инструменты (фрагменты кода), к которым могут обращаться модели GigaChat для решения задач пользователей. Модель не исполняет функции, но самостоятельно принимает решение о том как, когда и с какими параметрами их следует вызвать. При принятии решения о вызове функции модель исходит из доступных знаний, данных текущего разговора и описания функции. После обращения к функции модель может обработать результат ее работы. # START_RAW
# END_RAW - name: files-storage x-displayName: Хранилище файлов description: | # Хранилище файлов В этом разделе описаны методы для работы с хранилищем файлов, которые можно использовать при запросах на генерацию. Хранилище позволяет: * [загружать файлы](/ru/gigachat/api/reference/rest/post-file). Загруженные файлы доступны только вам; * [получать список доступных файлов](/ru/gigachat/api/reference/rest/get-files); * [получать описание выбранного файла](/ru/gigachat/api/reference/rest/get-file); * [скачивать файлы изображений](/ru/gigachat/api/reference/rest/get-file-id); * [удалять файлы](/ru/gigachat/api/reference/rest/file-delete). Кроме загруженных файлов, в хранилище также сохраняются файлы изображений, сгенерированных при выполнении запроса # START_RAW# END_RAW. Хранилище поддерживает текстовые документы, изображения и аудиофайлы разных форматов. # START_RAW # END_RAW ```mdx-code-block ``` | Формат | MIME-тип | |--------|------------| | txt | text/plain | | doc | application/msword | | docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document | | pdf | application/pdf | | epub | application/epub | | ppt | application/ppt | | pptx | application/pptx | | xlsx | application/vnd.ms-excel | ```mdx-code-block ``` # START_RAW # END_RAW ```mdx-code-block ``` | Формат | MIME-тип | |--------|------------| | jpeg | image/jpeg | | png | image/png | | tiff | image/tiff | | bmp | image/bmp | ```mdx-code-block ``` # START_RAW # END_RAW ```mdx-code-block ``` | Формат | MIME-тип | | ------ | -------------------------------------------------------------- | | mp4 | audio/mp4 | | mp3 | audio/mp3 | | m4a | audio/x-m4a | | wav | audio/x-wav
audio/wave
audio/wav
audio/x-pn-wav | | weba | audio/webm | | ogg | audio/x-ogg | | opus | audio/opus | ```mdx-code-block ``` # START_RAW # END_RAW На размеры файлов действуют ограничения: * максимальный размер одного аудиофайла в запросе — 35 Мб; * максимальный размер одного изображения в запросе — 15 Мб; * максимальный размер одного текстового файла в запросе — 40 Мб. Общий размер загружаемых аудиофайлов и изображений должен быть меньше 80 Мб. :::note При использовании больших текстовых файлов в запросах на генерацию, их содержимое может превышать [размер контекста модели](/ru/gigachat/models/main#modeli-dlya-generatsii). В таком случае вернется [ошибка с кодом 422](/ru/gigachat/api/errors-description?responseCode=422). ::: # START_RAW # END_RAW - name: consumption-monitoring x-displayName: Мониторинг потребления description: | # Мониторинг потребления В разделе описаны методы, которые помогут вам оценить, сколько токенов будет потрачено на ваш запрос, а также узнать остаток токенов для работы с каждой из доступных моделей. # START_RAW
Подробнее о токенах # END_RAW Токен — единица измерения стоимости запросов к модели. Токен может быть символом, несколькими символами, фрагментом слова или словом целиком. В среднем в одном токене 3—4 символа, включая пробелы, знаки препинания и специальные символы. Кроме текста сообщений в токены преобразуется контент, который используется в контексте запроса. Например, текстовые файлы и изображения, описания функций или история сообщений из массива `messages`. # START_RAW
# END_RAW paths: /oauth: post: servers: - url: https://ngw.devices.sberbank.ru:9443/api/v2 description: Адрес запроса parameters: - name: RqUID in: header description: | Уникальный идентификатор запроса. Соответствует формату [`uuid4`](https://www.uuidgenerator.net/version4). Параметр для журналирования входящих вызовов и разбора инцидентов. Идентификатор нужно указать самостоятельно, для этого можно использовать стандартные библиотеки и классы для генерации UUID и GUID. Пример: `6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e`. required: true schema: type: string format: UUIDv4 example: 6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e requestBody: content: 'application/x-www-form-urlencoded': schema: type: object properties: scope: description: | Версия API. Возможные значения: * `GIGACHAT_API_PERS` — доступ для физических лиц. * `GIGACHAT_API_B2B` — доступ для ИП и юридических лиц по [платным пакетам](/ru/gigachat/quickstart/legal-tokens-purchase#pokupka-paketov). * `GIGACHAT_API_CORP` — доступ для ИП и юридических лиц по схеме [pay-as-you-go](/ru/gigachat/quickstart/legal-tokens-purchase#oplata-pay-as-you-go). type: string enum: - GIGACHAT_API_PERS - GIGACHAT_API_B2B - GIGACHAT_API_CORP example: GIGACHAT_API_PERS required: - scope x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>", ) response = giga.get_token() print(response) responses: '200': content: application/json: schema: $ref: '#/components/schemas/Token' description: OK '400': $ref: '#/components/responses/BadRequestFormat' '401': $ref: '#/components/responses/AuthUnauthorizedError' security: - Базовая аутентификация: [client_id, client_secret] operationId: postToken summary: Получить токен доступа description: | Возвращает токен доступа для авторизации запросов к API. Токен доступа действителен в течение 30 минут. Запросы на получение токена можно отправлять до 10 раз в секунду. В заголовке `Authorization` нужно передать ключ авторизации, полученный при создании проекта GigaChat API в личном кабинете. Как получить ключ авторизации читайте в разделах [Быстрый старт для физических лиц](/ru/gigachat/quickstart/ind-using-api#poluchenie-avtorizatsionnyh-dannyh) и [Быстрый старт для ИП и юридических лиц](/ru/gigachat/quickstart/legal-using-api#poluchenie-avtorizatsionnyh-dannyh). # START_RAW
Подробнее о ключе авторизации # END_RAW Ключ авторизации (англ. *Authorization key*) нужен для получения токена доступа Access token, с помощью которого авторизуются запросы к GigaChat API. Авторизационный ключ — строка, полученная в результате кодирования в Base64 клиентского идентификатора (Client ID) и ключа (Client Secret) API. Вы можете использовать готовый ключ из личного кабинета или самостоятельно закодировать Client ID и Client Secret. # START_RAW
# END_RAW /tokens/count: post: tags: - consumption-monitoring requestBody: content: application/json: schema: $ref: '#/components/schemas/TokensCountBody' x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>", ) response = giga.tokens_count( # Массив строк для подсчета токенов input_=["12345"], # Модель, которая используется для подсчета токенов model="GigaChat-Pro" ) print(response) - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); const response = await giga.tokensCount(["Привет! Расскажи о себе в двух словах"]); console.log("Количество токенов в запросе: ", response.tokens[0].tokens); responses: '200': content: application/json: schema: $ref: '#/components/schemas/TokensCount' description: OK '401': $ref: '#/components/responses/UnauthorizedError' security: - Токен доступа: [] operationId: postTokensCount summary: Подсчитать количество токенов description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает объект с информацией о количестве токенов, подсчитанных заданной моделью в строках. Строки передаются в массиве `input`. /balance: get: tags: - consumption-monitoring parameters: - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>" ) # Метод доступен только если вы используете пакеты токенов (купленные или бесплатные) response = giga.get_balance() print(response) - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); # Метод доступен только если вы используете пакеты токенов (купленные или бесплатные) const response = await giga.balance(); console.log("Остаток токенов: ", response); responses: '200': content: application/json: schema: $ref: '#/components/schemas/Balance' description: OK '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/PermissionDeniedError' security: - Токен доступа: [] operationId: getBalance summary: Получить остаток токенов description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает доступный остаток токенов для каждой из моделей. Метод доступен только при покупке пакетов токенов. Если вы оплачиваете работу с API по схеме [pay-as-you-go](/ru/gigachat/api/tariffs#oplata-pay-as-you-go), запрос вернет ошибку 403 Permission Denied. Подробнее о пакетах токенов — в разделах платные пакеты для [физических лиц](/ru/gigachat/api/tariffs#platnye-pakety) или [для ИП и юридических лиц](/ru/gigachat/api/tariffs#platnye-pakety2). /models: get: tags: - models x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>", ) response = giga.get_models() print(response) - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); const response = await giga.getModels(); console.log(response); responses: '200': content: application/json: schema: $ref: '#/components/schemas/Models' description: OK '401': $ref: '#/components/responses/UnauthorizedError' security: - Токен доступа: [] operationId: getModels summary: Список моделей description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает массив объектов с данными доступных моделей. Описание доступных моделей в разделе [Модели GigaChat](/ru/gigachat/models/main). /files: get: tags: - files-storage x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat with GigaChat(credentials="<ключ_авторизации>") as client: files = client.get_files() for file in files.data: print(f"{file.id_}: {file.filename}") - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); const files = await giga.getFiles(); console.log(files); responses: '200': content: application/json: schema: $ref: '#/components/schemas/Files' description: OK security: - Токен доступа: [] operationId: getFiles summary: Список доступных файлов description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает массив объектов с данными доступных файлов. post: requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FileUpload' required: true tags: - files-storage x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>", ) response = giga.upload_file(open("/<путь_к_файлу>/<имя_файла>.txt", mode="rb")) print(response) responses: '200': content: application/json: schema: $ref: '#/components/schemas/File' description: OK security: - Токен доступа: [] operationId: postFile summary: Загрузить файл description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Загружает в хранилище текстовые документы, изображения или аудиофайлы. Возвращает объект с данными загруженного файла. Загруженные файлы доступны только вам. Идентификатор файла, указанный в поле `id`, можно использовать при [запросах на генерацию](/ru/gigachat/api/reference/rest/post-chat). Для этого идентификаторы нужно передать в массиве `attachments`. Подробнее — в разделе [Обработка файлов](/ru/gigachat/guides/working-with-files). Хранилище поддерживает текстовые документы, изображения и аудиофайлы разных форматов. # START_RAW # END_RAW ```mdx-code-block ``` | Формат | MIME-тип | |--------|------------| | txt | text/plain | | doc | application/msword | | docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document | | pdf | application/pdf | | epub | application/epub | | ppt | application/ppt | | pptx | application/pptx | | xlsx | application/vnd.ms-excel | ```mdx-code-block ``` # START_RAW # END_RAW ```mdx-code-block ``` | Формат | MIME-тип | |--------|------------| | jpeg | image/jpeg | | png | image/png | | tiff | image/tiff | | bmp | image/bmp | ```mdx-code-block ``` # START_RAW # END_RAW ```mdx-code-block ``` | Формат | MIME-тип | | ------ | -------------------------------------------------------------- | | mp4 | audio/mp4 | | mp3 | audio/mp3 | | m4a | audio/x-m4a | | wav | audio/x-wav
audio/wave
audio/wav
audio/x-pn-wav | | weba | audio/webm | | ogg | audio/x-ogg | | opus | audio/opus | ```mdx-code-block ``` # START_RAW # END_RAW На размеры файлов действуют ограничения: * максимальный размер одного аудиофайла в запросе — 35 Мб; * максимальный размер одного изображения в запросе — 15 Мб; * максимальный размер одного текстового файла в запросе — 40 Мб. Общий размер загружаемых аудиофайлов и изображений должен быть меньше 80 Мб. :::note При использовании больших текстовых файлов в запросах на генерацию, их содержимое может превышать [размер контекста модели](/ru/gigachat/models/main#modeli-dlya-generatsii). В таком случае вернется [ошибка с кодом 422](/ru/gigachat/api/errors-description?responseCode=422). ::: /files/{file}: get: tags: - files-storage parameters: - name: file description: Идентификатор файла. Идентификатор содержится в поле найти в поле `id` объекта, который создается при загрузке файла в хранилище. schema: type: string in: path required: true - $ref: '#/components/parameters/xClientId' x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat with GigaChat(credentials="<ключ_авторизации>") as client: single_file = client.get_file("<идентификатор_файла>") print(f"{single_file}") - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); const file = await giga.getFile('<идентификатор_файла>'); console.log(file); responses: '200': content: application/json: schema: $ref: '#/components/schemas/File' description: OK security: - Токен доступа: [] operationId: getFile summary: Информация о файле description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает объект с описанием указанного файла. /files/{file_id}/content: get: tags: - files-storage parameters: - name: file_id description: | Идентификатор файла, сохраненного в хранилище. schema: type: string in: path required: true - $ref: '#/components/parameters/xClientId' responses: '200': content: application/octet-stream: schema: $ref: '#/components/schemas/FileContent' description: OK '400': description: Invalid model ID '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NoSuchModel' security: - Токен доступа: [] operationId: getFileId summary: Скачать файл description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает файл сохраненный в хранилище. Используйте метод для скачивания изображений и 3D-моделей, созданных с помощью [встроенных функций `text2image` и `text2model3d`](/ru/gigachat/guides/functions/calling-builtin-functions). Подробнее о работе с изображениями — в разделе [Создание изображений](/ru/gigachat/guides/images-generation). /files/{file}/delete: post: tags: - files-storage parameters: - name: file description: Идентификатор файла, который нужно удалить schema: type: string in: path required: true - $ref: '#/components/parameters/xClientId' x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>" ) response = giga.delete_file("<идентификатор_файла>") print(response) - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); const response = await giga.deleteFile('<идентификатор_файла>'); console.log(response); responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FileDeleted' security: - Токен доступа: [] operationId: fileDelete summary: Удалить файл description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Переводит статус файла в значение `deleted`. /models/model: get: tags: - models parameters: - $ref: '#/components/parameters/xClientId' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' - name: model description: ID модели schema: type: string in: path required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Model' description: OK '400': description: Invalid model version '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NoSuchModel' security: - bearerAuth: [] operationId: getModel summary: Получить указанную модель description: | Возвращает объект с описанием указанной модели. :::tip О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: /chat/completions: post: parameters: - $ref: '#/components/parameters/xClientId' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' requestBody: content: application/json: schema: $ref: '#/components/schemas/Chat' examples: Текст: value: {"model": "GigaChat","messages": [{"role": "system","content": "Ты — профессиональный переводчик на английский язык. Переведи точно сообщение пользователя."},{"role": "user","content": "GigaChat — это сервис, который умеет взаимодействовать с пользователем в формате диалога, писать код, создавать тексты и картинки по запросу пользователя."}],"stream": false,"update_interval": 0} Изображение: value: { "model": "GigaChat", "messages": [ { "role": "system", "content": "Ты — Василий Кандинский" }, { "role": "user", "content": "Нарисуй розового кота" } ], "function_call": "auto"} Аргументы для функции: value: { "model": "GigaChat-2-Pro", "messages": [ { "role": "user", "content": "Погода в Манжероке на десять дней" } ], "functions": [ { "name": "weather_forecast", "description": "Возвращает температуру на заданный период", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "Местоположение, например, название города" }, "format": { "type": "string", "enum": [ "celsius", "fahrenheit" ], "description": "Единицы измерения температуры" }, "num_days": { "type": "integer", "description": "Период, для которого нужно вернуть" } }, "required": [ "location", "num_days" ] }, "few_shot_examples": [ { "request": "Какая погода в Москве в ближайшие три дня", "params": { "location": "Moscow, Russia", "format": "celsius", "num_days": "3" } } ], "return_parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "Местоположение, например, название города" }, "temperature": { "type": "integer", "description": "Температура для заданного местоположения" }, "forecast": { "type": "array", "items": { "type": "string" }, "description": "Описание погодных условий" }, "error": { "type": "string", "description": "Возвращается при возникновении ошибки. Содержит описание ошибки" } } } } ]} x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>", ) response = giga.chat("Расскажи про себя") print(response) - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: '<ключ_авторизации>', scope: '<версия_API>', }); giga.chat({ messages: [ { role: 'user', content: 'Привет! Расскажи о себе в двух словах' } ], }) .then((resp) => { console.log(resp.choices[0]?.message.content); }); responses: '200': content: application/json: schema: $ref: '#/components/schemas/ChatCompletion' examples: Текст: value: {"choices":[{"message":{"content":"GigaChat is a service capable of interacting with the user in a dialogue format, writing code, and creating texts and images upon user's request.","role":"assistant"},"index":0,"finish_reason":"stop"}],"created":1760434636,"model":"GigaChat:2.0.28.2","object":"chat.completion","usage":{"prompt_tokens":55,"completion_tokens":30,"total_tokens":85,"precached_prompt_tokens":4}} Изображение: value: {"choices":[{"message":{"content":" вот мой рисунок розового кота.","role":"assistant","functions_state_id":"0199e20f-058c-70c0-9850-6400dd41a853"},"index":0,"finish_reason":"stop"}],"created":1760434259,"model":"GigaChat:2.0.28.2","object":"chat.completion","usage":{"prompt_tokens":626,"completion_tokens":43,"total_tokens":669,"precached_prompt_tokens":3}} Аргументы для функции: value: { "choices": [ { "message": { "content": "", "role": "assistant", "function_call": { "name": "weather_forecast", "arguments": { "location": "Манжерок", "num_days": 10 } }, "functions_state_id": "0199e210-2f13-744c-8fe5-c9a19fe27db7" }, "index": 0, "finish_reason": "function_call" } ], "created": 1760434335, "model": "GigaChat-2-Pro:2.0.28.2", "object": "chat.completion", "usage": { "prompt_tokens": 278, "completion_tokens": 35, "total_tokens": 313, "precached_prompt_tokens": 0 }} text/event-stream: schema: type: string description: | Событие формата [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html). Каждое событие содерджит сообщение вида `data: `. В последнем событии приходит сообщение `data: [DONE]`. Пример фрагмента: ```json { "choices": [ { "delta": { "content": "GigaChat is a service capable of interacting with the user in a dialogue format, writing code, and creating texts and images upon the user's request.", "role": "assistant" }, "index": 0 } ], "created": 1754637655, "model": "GigaChat:2.0.28.2", "object": "chat.completion" } ``` # Схема фрагмента ответа модели: # $ref: '#/components/schemas/ChatCompletionStream' example: | data: {"choices":[{"delta":{"content":"GigaChat is a service capable of interacting with the user in a dialogue format, writing code, and creating texts and images upon the user's request.","role":"assistant"},"index":0}],"created":1754637655,"model":"GigaChat:2.0.28.2","object":"chat.completion"} data: {"choices":[{"delta":{"content":""},"index":0,"finish_reason":"stop"}],"created":1754637655,"model":"GigaChat:2.0.28.2","object":"chat.completion","usage":{"prompt_tokens":56,"completion_tokens":31,"total_tokens":87,"precached_prompt_tokens":3}} data: [DONE] description: | Успешное выполнение запроса. При запуске [потоковой генерации](/docs/ru/gigachat/guides/response-token-streaming) передается с заголовком `Content-Type: text/event-stream`. '400': $ref: '#/components/responses/BadRequestFormat' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NoSuchModel' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - Токен доступа: [] operationId: postChat summary: Сгенерировать ответ description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает ответ модели, сгенерированный на основе переданных сообщений. Для экономии токенов передавайте текст сообщений (поле `content`) в кодировке UTF8. Запрос можно передавать [моделям в раннем доступе](/ru/gigachat/guides/preview-models). **Обработка файлов** Вы можете генерировать ответы на основе текстовых документов, изображений и аудиофайлов, загруженных в ваше хранилище. Для этого, передайте список идентификаторов нужных файлов в массиве `attachments`. При этом общий размер запроса с приложенными с изображениями и аудиофайлами должен быть меньше 80 Мб. Подробнее — в разделе [Обработка файлов](/ru/gigachat/guides/working-with-files#ispolzovanie-faylov-dlya-generatsii-otvetov). **Ограничения** Большие текстовые файлы могут превысить контекст модели. В таком случае API вернет ошибку с кодом 422. Попробуйте разбить их на несколько запросов или убрать лишнее. Одно сообщение (объект в `messages`) поддерживает только одно изображение. При этом в одном запросе можно отправить до 10 изображений, независимо от числа самих сообщений. /ai/check: post: parameters: - $ref: '#/components/parameters/xClientId' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' requestBody: content: application/json: schema: $ref: '#/components/schemas/aiCheck' x-codeSamples: - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: 'ключ_авторизации', }); const response = await giga.aiCheck('<текст_для_проверки>', '<название_модели>'); console.log(response); responses: '200': content: application/json: schema: $ref: '#/components/schemas/aiCheckResponse' example: {"category": "mixed", "characters": 500, "tokens": 38, "ai_intervals": [ [0, 100], [150, 200] ]} description: OK security: - Токен доступа: [] operationId: postAiCheck summary: Проверить текст на ИИ description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Проверяет текст на русском языке на наличие сгенерированного с помощью нейросетевых моделей контента. Минимальная длина текста — 20 слов. Метод доступен только для юридических лиц, которые работают по схеме оплаты [pay-as-you-go](/ru/gigachat/api/tariffs#oplata-pay-as-you-go). /embeddings: post: requestBody: content: application/json: schema: $ref: '#/components/schemas/EmbeddingsBody' x-codeSamples: - lang: "Python" label: "gigachat" source: | """ Установите SDK: pip install gigachat """ from gigachat import GigaChat giga = GigaChat( credentials="<ключ_авторизации>" ) response = giga.embeddings(["Hello world!"]) print(response) - lang: "JavaScript" label: "gigachat" source: | /** * Установите библиотеку gigachat с помощью менеджера пакетов npm: * * npm install gigachat */ import GigaChat from 'gigachat'; const giga = new GigaChat({ credentials: 'ключ_авторизации', }); const response = await giga.embeddings(['Слова слова слова']); console.log(response.data); responses: '200': content: application/json: schema: $ref: '#/components/schemas/Embedding' description: OK '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/InternalError' security: - Токен доступа: [] operationId: postEmbeddings summary: Создать эмбеддинг description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает векторные представления соответствующих текстовых запросов. Индекс объекта с векторным представлением (поле `index`) соответствует индексу строки в массиве `input` запроса. Векторное представление выглядит как массив чисел `embedding`. Каждое значение в массиве представляет одну из характеристик или признаков текста, учтенных при вычислении эмбеддинга. Значения образуют числовое представление текста и позволяют анализировать и использовать текст в различных задачах. Как правило, чем ближе значения эмбеддингов друг к другу, тем более семантически близки тексты. Для создания эмбеддингов можно использовать [модели Embeddings, Embeddings-2 и EmbeddingsGigaR](/ru/gigachat/models/main#modeli-dlya-vektornogo-predstavleniya-tekstov). Запросы [тарифицируются](/ru/gigachat/api/tariffs) одинаково, независимо от использованной модели. :::tip Для улучшения результатов при работе с моделью EmbeddingsGigaR следуйте рекомендациям в разделе [Векторное представление текста](/ru/gigachat/guides/embeddings#embeddingsgigar-recommendations). ::: /batches: get: tags: - batches parameters: - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' - $ref: '#/components/parameters/xClientId' - name: Content-Type in: header required: true schema: type: string default: application/json - name: batch_id description: | Идентификатор ранее загруженной пакетной задачи. schema: type: string in: query required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchesList' description: OK '400': $ref: '#/components/responses/BadRequestFormat' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/BatchTaskNotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - Токен доступа: [] operationId: getBatches summary: Статус пакетной задачи description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Возвращает информацию о существующих задачах для асинхронной обработки. Если у пользователя нет задач, возвращается пустой список. Если передан path-параметр `batch_id`, отобразится информация о конкретной задаче. post: tags: - batches parameters: - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' - name: method in: query schema: type: string description: Имя метода, в который далее пойдет запрос на выполнение (`chat_completions` или `embedder`). enum: - chat_completions - embedder requestBody: content: application/octet-stream: schema: type: string format: binary description: Файл в формате `jsonl`, содержащий перечень задач. Структура файла описана в разделе [Обработка задач в пакетном режиме](/ru/gigachat/guides/batches). responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchResponse' description: OK '400': $ref: '#/components/responses/BadRequestFormat' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - Токен доступа: [] operationId: postBatches summary: Пакет запросов description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Создает задачу на обработку большого пакета запросов в асинхронном режиме. Пакетный режим доступен при оплате работы с GigaChat API по схеме [pay-as-you-go](/ru/gigachat/api/tariffs#oplata-pay-as-you-go). Запрос принимает файл формата JSONL. Каждая строка в файле должна содержать валидный JSON-объект с запросом на [генерацию](/ru/gigachat/api/reference/rest/post-chat) или [векторное представление текста](/ru/gigachat/api/reference/rest/post-embeddings). Подробнее — в разделе [Обработка задач в пакетном режиме](/ru/gigachat/guides/batches). /functions/validate: post: parameters: - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xSessionId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomFunction' tags: - functions responses: '200': description: | Результат валидации функции. content: application/json: schema: $ref: '#/components/schemas/FunctionValidationResult' '400': $ref: '#/components/responses/BadRequestFormat' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - Токен доступа: [] operationId: functionValidation summary: Валидировать функцию description: | :::note О том как выбрать базовый адрес — в разделе [Авторизация](/ru/gigachat/api/reference/rest/gigachat-api#vybor-bazovogo-adresa). ::: Проверяет переданное описание функции на соответствие формату функций GigaChat. Пример описания функции GigaChat — в массиве `functions`, в запросе # START_RAW# END_RAW. Метод принимает описание функции в формате JSON. В результате проверки возвращается массив ошибок и предупреждений, которые нужно исправить, чтобы описание функции соответствовало формату GigaChat. # START_RAW
Пример описания функции в формате JSON Schema # END_RAW ```json { "name": "send_sms", "description": "Отправка SMS контакту по ID", "parameters": { "type": "object", "properties": { "contactId": { "description": "ID контакта", "format": "int32", "type": "integer" }, "text": { "description": "Текст SMS", "minLength": 1, "type": "string" }, "version": { "description": "Описание параметра - версия API", "type": "string" } }, "required": [ "version", "contactId", "text" ] }, "return_parameters": { "type": "object", "properties": { "description": { "description": "Описание статуса", "nullable": true, "type": "string" }, "phone": { "description": "Номер: маска + 2 последние цифры номера", "nullable": true, "type": "string" }, "status": { "description": "Отправлено/не отправлено", "type": "boolean" } } }, "few_shot_examples": [ { "request": "Отправь SMS контакту с ID 111111 с текстом Hello World", "params": { "contactId": "111111", "text": "Hello world" } } ] } ``` # START_RAW
# END_RAW Подробнее — в разделе [Работа с функциями](/ru/gigachat/guides/functions/overview). components: parameters: xClientId: name: X-Client-ID in: header description: | Произвольный идентификатор пользователя. Используется для логирования и [ограничения доступа к файлам](/ru/gigachat/guides/working-with-files#dostup-k-failam). Если вы передали этот заголовок при запросе на создание изображения, то для скачивания изображения в запросе # START_RAW# END_RAW нужно передать этот же заголовок. schema: type: string xRequestId: in: header name: X-Request-ID description: | Произвольный идентификатор запроса, который используется для логирования. Если не передан явно, GigaChat API автоматически сгенерирует идентификатор в формате UUIDv4. schema: type: string example: my-request-id-1 xSessionId: in: header name: X-Session-ID description: | Произвольный идентификатор сессии, который используется для логирования. Если не передан явно, GigaChat API автоматически сгенерирует идентификатор в формате UUIDv4. schema: type: string example: my-session-id-1 schemas: FunctionValidationResult: type: object description: Объект с результатом валидации функции, описанной в формате JSON. properties: status: type: integer default: 200 description: HTTP-код ответа. message: type: string description: | Сообщение о результате валидации функции. Возможные значения: * `Function is valid` — описание функции полностью соответствует формату GigaChat API или содержит незначительные проблемы (блок `warnings`). * `Incorrect function syntax` — описание функции не соответствует формату GigaChat API (ответ содержит блок `errors`). enum: - Function is valid - Incorrect function syntax json_ai_rules_version: type: string description: | Версия правил, которые используются для валидации функции. Передается, если запрос содержит описание функции в формате JSON. example: 1.0.5 errors: description: | Массив с описанием ошибок, возникших при валидации функции. В отличие от предупреждений ошибки возникают, когда описание функции нарушает формат GigaChat API. Например, если в описании отсутствуют обязательные блоки `name` или `parameters`. Если в описании функции есть ошибки (массив `errors`), то предупреждения (массив `warnings`) не передаются. Перед отправкой функции в запросе # START_RAW# END_RAW ошибки нужно исправить. type: array items: type: object properties: description: type: string description: Описание ошибки. example: name is required schema_location: type: string description: Указывает, где в схеме нужно внести изменения, чтобы исправить ошибку. example: (root) warnings: description: | Массив с описанием предупреждений, возникших при валидации функции. В отличие от предупреждений ошибки возникают, когда описание функции нарушает формат GigaChat API. Например, если в описании отсутствует необязательный массив образцов `few_shot_examples are missing`. Предупреждения (массив `warnings`) не передаются, если в описании функции есть ошибки (массив `errors`). type: array items: type: object properties: description: type: string description: Описание предупреждения. example: few_shot_examples are missing schema_location: type: string description: Указывает, где в схеме нужно внести изменения, чтобы исправить предупреждения. example: (root) CustomFunctions: type: array nullable: true description: Массив с описанием пользовательских функций. items: $ref: '#/components/schemas/CustomFunction' CustomFunction: description: Описание пользовательской функции. type: object required: - "name" - "parameters" properties: name: type: string description: | Название пользовательской функции, для которой будут сгенерированы аргументы. # START_RAW # END_RAW Название функции должно содержать только латинские буквы. Название функции не должно начинаться с цифры. # START_RAW # END_RAW example: weather_forecast description: type: string description: Текстовое описание функции. example: Прогноз погоды parameters: type: object properties: {} description: Валидный JSON-объект с набором пар `ключ-значение`, которые описывают аргументы функции. example: {"properties": { "location": { "type": "string", "description": "Местоположение, например, название города" } }} few_shot_examples: type: array description: | Объекты с парами `запрос_пользователя`-`параметры_функции`, которые будут служить модели примерами ожидаемого результата. items: type: object required: - "request" - "params" properties: request: type: string description: Запрос пользователя. example: Погода в Москве в ближайшие три дня params: type: object description: Пример заполнения параметров пользовательской функции. properties: {} example: { "location": "Moscow, Russia", } return_parameters: type: object description: JSON-объект с описанием параметров, которые может вернуть ваша функция. properties: {} example: {"properties": { "location": { "type": "string", "description": "Местоположение, например, название города" } }} BatchesList: type: object properties: batches: type: array description: Список пакетных задач. items: type: object properties: id: type: string description: Идентификатор созданной пакетной задачи. method: type: string enum: - chat_completions - embedder description: Имя метода, в который далее пойдет запрос на выполнение. request_counts: type: object description: Количество запросов внутри пакетной задачи. items: type: object properties: total: type: integer description: Общее количество запросов. default: 0 completed: type: integer description: Количество обработанных запросов. default: 0 failed: type: integer description: Количество ошибочных запросов. default: 0 status: type: string description: Статус обработки файла. enum: - created - in_progress - completed output_file_id: type: string description: Идентификатор файла с результатами обработки запросов батча. Заполняется, если status = completed. Cкачать результат можно с помощью метода `get file/{file_id}/content`. created_at: type: integer description: Время создания файла в формате unix timestamp. format: unix timestamp updated_at: type: integer description: Время обновления файла в формате unix timestamp. format: unix timestamp BatchResponse: type: object properties: id: description: | Идентификатор созданной пакетной задачи. type: string method: description: | Имя метода, в который пойдет запрос на выполнение. type: string enum: - chat_completions - embedder request_counts: type: object description: Количество запросов внутри пакетной задачи. items: type: object properties: total: type: integer description: Общее количество запросов. example: Подсчет при валидации. default: 0 status: description: | Статус обработки пакетной задачи. type: string enum: - created - in_progress - completed created_at: description: Время создания файла в формате unix timestamp. type: integer format: unix timestamp updated_at: description: Время обновления файла в формате unix timestamp. type: integer format: unix timestamp Model: type: object properties: id: description: | Название модели. Описание доступных моделей смотрите в разделе [Модели GigaChat](/ru/gigachat/models/main). Модели в раннем доступе отмечены постфиксом `-preview`. Например, `GigaChat-Pro-preview`. type: string example: GigaChat:2.0.28.2 object: description: Тип сущности в ответе, например, модель. type: string example: model owned_by: description: Владелец модели. type: string example: salutedevices type: description: | Тип модели. Возможные значения: * `chat` — модель для генерации; * `aicheck` — модель для проверки, [создан ли текст с помощью ИИ](/ru/gigachat/api/reference/rest/post-ai-check); * `embedder` — модель для создания [эмбеддингов](/ru/gigachat/api/reference/rest/post-embeddings). enum: - chat - aicheck - embedder ModelId: type: object properties: model: $ref: '#/components/schemas/Model/properties/id' Models: type: object properties: data: type: array items: $ref: '#/components/schemas/Model' object: description: Тип сущности в ответе, например, список. type: string example: list aiCheck: type: object required: - model - input properties: input: type: string description: | Текст, который будет проверен на наличие содержимого, сгенерированного с помощью нейросетевых моделей. Проверка доступна только для текстов на русском языке. Минимальная длина текста — 20 слов. example: Первый искусственный спутник Земли был запущен Советским Союзом 4 октября 1957 года. Этот исторический запуск ознаменовал начало космической эры и стал важным событием в истории человечества. Спутник получил название «Спутник-1». model: type: string enum: - GigaCheckClassification - GigaCheckDetection description: | Название модели. Модель GigaCheckClassification лучше всего подходит для анализа и разделения текста на два класса: написанный человеком или сгенерированный нейросетью (`ai`/`human`). В модели GigaCheckDetection добавляется третий класс — `mixed` (`ai`+`human`), что позволяет определять тексты, частично созданные с помощью ИИ. example: "GigaCheckClassification" aiCheckResponse: type: object properties: category: type: string description: | Результат проверки текста. Возможные значения: * `ai` — текст сгенерирован с помощью нейросетевых моделей; * `human` — текст написан человеком; * `mixed` — текст содержит как фрагменты сгенерированные с помощью моделей, так и написанные человеком. enum: - ai - human - mixed example: ai characters: type: integer description: Количество символов в переданном тексте. example: 158 tokens: type: integer description: Количество токенов в переданном тексте. example: 38 ai_intervals: type: array items: type: array minItems: 2 maxItems: 2 items: type: integer description: | Части текста, сгенерированные моделью. Обозначаются индексами символов, с которых начинаются и заканчиваются сгенерированные фрагменты. Содержит пустой массив если текст полностью сгенерирован с помощью нейросетевых моделей (`"category": "ai"`) или написан человеком (`"category": "human"`). Balance: type: object properties: balance: type: array items: type: object properties: usage: type: string description: Название модели, например, GigaChat или embeddings. example: GigaChat value: type: integer description: Остаток токенов. example: 100500 File: description: Описание файла, доступного в хранилище type: object properties: bytes: description: Размер файла в байтах. type: integer example: 120000 created_at: description: Время создания файла в формате unix timestamp. type: integer format: unix timestamp example: 1677610602 filename: description: Название файла. type: string example: file123 id: description: | Идентификатор файла, который можно использовать при [запросах на генерацию](/ru/gigachat/api/reference/rest/post-chat). Для этого идентификаторы нужно передать в массиве `attachments`. Подробнее — в разделе [Обработка файлов](/ru/gigachat/guides/working-with-files). type: string format: UUIDv4 example: 6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e object: description: Тип объекта. type: string example: file purpose: description: Назначение файлов. Значение `general` указывает на то, что файлы могут использоваться для [генерации ответа модели](/ru/gigachat/guides/working-with-files) enum: - general type: string access_policy: type: string description: | Доступность файла. Возможные значения: * `public`; * `private`. example: private default: private enum: - public - private modalities: type: array description: | Модальность файла, например, `image`. Определяется автоматически. items: type: string example: image nullable: true FileContent: format: byte description: Содержимое файла в двоичном формате. type: string Files: description: Массив объектов с данными доступных файлов. type: object properties: data: type: array items: $ref: '#/components/schemas/File' FileUpload: required: - file type: object properties: file: format: binary description: Загружаемый объект. type: string purpose: description: Назначение загружаемого файла. enum: - general type: string FileDeleted: type: object properties: id: type: string description: Идентификатор файла. example: d3277ca1-a140-484a-a3b4-9a121bea4bdc deleted: type: boolean description: Признак удаления файла. example: true access_policy: type: string example: private description: | Доступность файла. ChatCompletionStream: type: object description: | Сообщение формата [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html). Содержит поле `data:` с фрагментом ответа модели. В последнем событии приходит сообщение `data: [DONE]`. required: - data properties: data: type: object properties: choices: type: array items: type: object properties: delta: type: object properties: content: $ref: '#/components/schemas/MessagesRes/properties/content' role: $ref: '#/components/schemas/MessagesRes/properties/role' index: $ref: '#/components/schemas/Choices/properties/index' finish_reason: $ref: '#/components/schemas/Choices/properties/finish_reason' created: $ref: '#/components/schemas/ChatCompletion/properties/created' model: $ref: '#/components/schemas/Model/properties/id' object: $ref: '#/components/schemas/ChatCompletion/properties/object' usage: $ref: '#/components/schemas/Usage' Chat: required: - model - messages type: object properties: model: type: string description: | Название модели, котора должна обработать запрос. Описание доступных моделей смотрите в разделе [Модели GigaChat](/ru/gigachat/models/main). При обращении к моделям в раннем доступе к названию модели нужно добавлять постфикс `-preview`. example: GigaChat-2-Max messages: type: array description: | Массив сообщений, которыми пользователь обменивался с моделью. В запросе можно передать только один системный промпт (сообщение с ролью `system`). Системный промпт должен быть первым сообщением в массиве. Наличие в массиве нескольких системных промптов или передача системного промпта не в первом сообщении приведет к ошибке [с кодом 422](/ru/gigachat/api/errors-description?responseCode=422) и сообщением `Invalid params: system message must be the first message`. items: $ref: '#/components/schemas/message' function_call: description: | Явно задает [режим работы с функциями](/ru/gigachat/guides/functions/function-calling-modes). Возможные значения: * строка `none`; * строка `auto`; * объект `{"name": "название_функции"}`. oneOf: - $ref: '#/components/schemas/function_call_none' - $ref: '#/components/schemas/function_call_auto' - $ref: '#/components/schemas/function_call_name' functions: $ref: '#/components/schemas/CustomFunctions' temperature: format: float type: number description: | Температура выборки регулирует степень случайности ответов модели. Высокое значение делает ответы разнообразными и неожиданными, низкое — предсказуемыми и стабильными. Когда температура меньше 0.001, включается режим строгого контроля, дающий одинаковые ответы. А при температуре больше 2 реакция становится чрезмерно беспорядочной. Базовое значение температуры зависит от модели, которая генерирует ответ, и меняется вместе с улучшениями модели. minimum: 0 exclusiveMinimum: true nullable: true top_p: format: float type: number description: | Параметр используется как альтернатива температуре (поле `temperature`). Задает вероятностную массу токенов, которые должна учитывать модель. Так, если передать значение 0.1, модель будет учитывать только токены, чья вероятностная масса входит в верхние 10%. Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели. Значение изменяется в диапазоне от 0 до 1 включительно. minimum: 0 maximum: 1 nullable: true stream: type: boolean description: | Указывает, что сообщения надо передавать по частям в потоке. Сообщения передаются по протоколу [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format). Поток завершается событием `data: [DONE]`. Подробнее читайте в разделе [Потоковая генерация токенов](/ru/gigachat/guides/response-token-streaming). default: false example: false max_tokens: description: Максимальное количество токенов, которые будут использованы для создания ответов. format: int32 type: integer nullable: true exclusiveMinimum: 0 example: 30 repetition_penalty: type: number format: float nullable: true description: | Количество повторений слов: * Значение 1.0 — нейтральное значение. * При значении больше 1 модель будет стараться не повторять слова. Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели. example: 1.0 update_interval: type: number description: | Параметр потокового режима (`"stream": "true"`). Задает минимальный интервал в секундах, который проходит между отправкой токенов. Например, если указать `1`, сообщения будут приходить каждую секунду, но размер каждого из них будет больше, так как за секунду накапливается много токенов. default: 0 example: 0 message: type: object properties: role: type: string description: | Роль автора сообщения: * `system` — системный промпт, который задает роль модели, например, должна модель отвечать как академик или как школьник; * `assistant` — ответ модели; * `user` — сообщение пользователя; * `function` — сообщение с результатом работы [пользовательской функции](/ru/gigachat/guides/functions/generating-arguments-for-custom-functions). В сообщении с этой ролью передавайте результаты работы функции в поле `content` в форме валидного JSON-объекта, обернутого в строку. Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе [Работа с историей чата](/ru/gigachat/guides/keeping-context). enum: - user - system - assistant - function content: description: | Содержимое сообщения. Зависит от роли. Если поле передается в сообщении с ролью `function`, то в нем указывается обернутый в строку валидный JSON-объект с аргументами функции, указанной в поле `function_call.name`. В остальных случаях содержит либо системный промпт (сообщение с ролью `system`), либо текст сообщения пользователя или модели. Передавайте текст в кодировке UTF8. Это позволит снизить расход токенов при обработке сообщения. type: string example: "Погода в Болхове" functions_state_id: type: string format: UUIDv4 description: | Идентификатор, который объединяет массив функций, переданных в запросе. Возвращается в ответе модели (сообщение с `"role": "assistant"`) при вызове встроенных или собственных функций. Позволяет сохранить [состояние обращения к функции](/ru/gigachat/guides/functions/calling-builtin-functions#sohranenie-konteksta) и повысить качество работы модели. Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью `assistant`. Сейчас поле работает только при обращении к [моделям в раннем доступе](/ru/gigachat/guides/preview-models). attachments: description: | Массив идентификаторов файлов, которые нужно использовать при генерации. Идентификатор присваивается файлу при [загрузке в хранилище](/ru/gigachat/api/reference/rest/post-file). Посмотреть список файлов в хранилище можно с помощью метода # START_RAW# END_RAW. При работе с текстовыми документами в одном запросе на генерацию нужно передавать только один идентификатор. Если вы передадите несколько идентификаторов файлов, для генерации будет использован только первый файл из списка. При использовании больших текстовых файлов в запросах на генерацию, их содержимое может превышать [размер контекста модели](/ru/gigachat/models/main#modeli-dlya-generatsii). В таком случае вернется [ошибка с кодом 422](/ru/gigachat/api/errors-description?responseCode=422). В одном сообщении (объект в массиве `messages`) можно передать только одно изображение. В одной сессии можно передать до 10 изображений. # START_RAW # END_RAW При этом общий размер запроса при работе с изображениями и аудио должен быть меньше 80 Мб. Например, ваш запрос может включать текст промпта и идентификаторы изображения размером 12 Мб, и двух аудиофайлов размером 33 Мб и 21 Мб. Что в сумме даст запрос размером больше 66 Мб, в зависимости от размера промпта. Размер текстовых документов не влияет на размер запроса, но их содержимое может превышать контекстное окно модели. # START_RAW # END_RAW Подробнее — в разделе [Обработка файлов](/ru/gigachat/guides/working-with-files) type: array items: type: string MessagesRes: type: object description: Сгенерированное сообщение. properties: role: type: string enum: - assistant - function_in_progress description: | Роль автора сообщения. Роль `function_in_progress` используется при работе встроенных функций в режиме [потоковой передачи токенов](/ru/gigachat/guides/functions/calling-builtin-functions#potokovaya-peredacha-tokenov). example: assistant content: type: string description: | Содержимое сообщения, например, результат генерации. При передаче в [режиме потоковой генерации](/ru/gigachat/guides/response-token-streaming) передается частями. В предпосленем сообщении передаеся пустая строка `""`. В сообщениях с ролью `function_in_progress` содержит информацию о том, сколько времени осталось до завершения работы встроенной функции. example: 'Здравствуйте! К сожалению, я не могу дать точный ответ на этот вопрос, так как это зависит от многих факторов. Однако обычно релиз новых функций и обновлений в GigaChat происходит постепенно и незаметно для пользователей. Рекомендую следить за новостями и обновлениями проекта в официальном сообществе GigaChat или на сайте разработчиков.' created: type: integer format: unix timestamp description: Передается в сообщениях с ролью`function_in_progress`. Содержит информацию о том, когда был создан фрагмент сообщения. example: 1625284800 name: type: string description: | Название вызванной [встроенной функции](/ru/gigachat/guides/functions/calling-builtin-functions). Передается в сообщениях с ролью`function_in_progress`. Возможные значения: * `text2image` - генерация изображения на основе описания; * `text2model3d` — генерация 3D-модели на основе описания. example: text2image functions_state_id: type: string format: UUIDv4 description: | Идентификатор, который объединяет массив функций, переданных в запросе. Возвращается в ответе модели (сообщение с `"role": "assistant"`) при вызове встроенных или собственных функций. Позволяет сохранить [контекст вызова функции](/ru/gigachat/guides/functions/calling-builtin-functions#sohranenie-konteksta) и повысить качество работы модели. Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью `assistant`. Сейчас поле работает только при обращении к [моделям в раннем доступе](/ru/gigachat/guides/preview-models). example: 77d3fb14-457a-46ba-937e-8d856156d003 function_call: type: object properties: name: type: string description: Название функции. arguments: type: object description: Аргументы для вызова функции в виде пар ключ-значение. Usage: type: object description: | Данные об использовании модели. При запуске [потоковой генерации](/ru/gigachat/guides/response-token-streaming), объект приходит в предпоследнем событии. properties: prompt_tokens: format: int32 description: Количество токенов во входящем сообщении (роль `user`). type: integer example: 1 completion_tokens: format: int32 description: Количество токенов, сгенерированных моделью (роль `assistant`). type: integer example: 4 precached_prompt_tokens: format: int32 description: | Количество ранее закэшированных токенов, которые были использованы при обработке запроса. Кэшированные токены вычитаются из общего числа оплачиваемых токенов (поле `total_tokens`). Модели GigaChat в течение некоторого времени сохраняют контекст запроса (историю сообщений массива `messages`, описание функций) с помощью кэширования токенов. Это позволяет повысить скорость ответа моделей и снизить стоимость работы с GigaChat API. # START_RAW # END_RAW Для повышения вероятности использования сохраненных токенов используйте [кэширование запросов](/ru/gigachat/guides/keeping-context#keshirovanie-zaprosov). # START_RAW # END_RAW [Подробнее о подсчете токенов](/ru/gigachat/guides/counting-tokens). type: integer example: 37 total_tokens: format: int32 description: Общее число токенов, подлежащих тарификации, после вычитания кэшированных токенов (поле `precached_prompt_tokens`). type: integer example: 5 ChatCompletion: type: object properties: choices: type: array description: Массив ответов модели. items: $ref: '#/components/schemas/Choices' created: format: unix timestamp type: integer description: Дата и время создания ответа в формате unix timestamp. example: 1678878333 model: type: string description: Название и версия модели, которая обработала запрос. example: GigaChat:2.0.28.2 usage: $ref: '#/components/schemas/Usage' object: type: string description: Название вызываемого метода. example: chat.completion Choices: type: object properties: message: $ref: '#/components/schemas/MessagesRes' index: format: int32 type: integer description: Индекс сообщения в массиве, начиная с ноля. example: 0 finish_reason: description: | Причина завершения гипотезы. Возможные значения: * `stop` — модель закончила формировать гипотезу и вернула полный ответ; * `length` — достигнут лимит токенов в сообщении; * `function_call` — указывает, что при запросе была вызвана встроенная функция или сгенерированы аргументы для пользовательской функции; * `blacklist` — запрос попадает под [тематические ограничения](/ru/gigachat/limitations#tematicheskie-ogranicheniya-zaprosov). * `error` — ответ модели содержит невалидные аргументы пользовательской функции. При работе в режиме [потоковой генерации](/ru/gigachat/guides/response-token-streaming) передается в предпоследнем событии со значением. type: string enum: - stop - length - function_call - blacklist - error example: "stop" Token: type: object properties: access_token: type: string description: Токен для авторизации запросов. example: | eyJhbGci3iJkaXIiLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIn0..Dx7iF7cCxL8SSTKx.Uu9bPK3tPe_crdhOJqU3fmgJo_Ffvt4UsbTG6Nn0CHghuZgA4mD9qiUiSVC--okoGFkjO77W.vjYrk3T7vGM6SoxytPkDJw expires_at: format: unix timestamp в миллисекундах description: Дата и время истечения действия токена в миллисекундах, в формате unix timestamp. type: integer example: 1739784663483 TokensCount: type: array items: type: object properties: object: type: string description: Описание того, какая информация содержится в объекте. default: tokens tokens: type: integer description: Количество токенов в соответствующей строке. example: 7 characters: type: integer description: Количество символов в соответствующей строке. example: 36 Embedding: type: object properties: object: type: string description: Формат структуры данных. default: list data: type: array items: type: object description: Объект с данными о векторном представлении текста. properties: object: type: string description: Тип объекта. default: embedding embedding: type: array description: Массив чисел, представляющий значения эмбеддинга для предоставленного текста. items: type: number format: float index: type: integer description: Индекс, соответствующий индексу текста, полученного в массиве `input` запроса. example: 0 usage: type: object properties: prompt_tokens: type: number description: Количество токенов в строке, для которой сгенерирован эмбеддинг. example: 6 model: type: string description: Название модели, которая используется для вычисления эмбеддинга. example: Embeddings TokensCountBody: type: object required: - "model" - "input" properties: model: type: string description: Название модели, которая будет использована для подсчета количества токенов. example: GigaChat input: type: array description: Строка или массив строк, в которых надо подсчитать количество токенов. items: type: string example: Я к вам пишу — чего же боле? EmbeddingsBody: type: object required: - "input" - "model" properties: model: type: string description: | Название модели, которая будет использована для создания эмбеддинга. Возможные значения: * `Embeddings` — базовая модель, доступная по умолчанию для векторного представления текстов; * `Embeddings-2` — доработанная и улучшенная версия базовой модели; * `EmbeddingsGigaR` — продвинутая модель с большим размером контекста. example: Embeddings input: description: Строка или массив строк, которые будут использованы для генерации эмбеддинга. oneOf: - type: string example: Расскажи о современных технологиях - type: array items: type: string example: ["Расскажи о современных технологиях", "Какие новинки в мире IT?"] function_call_name: type: object properties: name: type: string description: | Работа с функциями в принудительном режиме. В поле можно передать как название собственной функции, описание которой содержится в массиве `functions`, так и название одной из [встроенных функций](/ru/gigachat/guides/functions/calling-builtin-functions): ```json { ... "function_call": { "name": "weather_forecast" }, "functions": [ { "name": "weather_forecast", ... } ] ... } ``` function_call_none: type: string description: | Отключение работы с функциями. Если передать `none`, модель не будет вызывать встроенные функции или генерировать аргументы для пользовательских функций, а просто сгенерирует ответ в соответствии с полученными сообщениями. example: none function_call_auto: type: string description: | Автоматический режим работы с функциями. В этом режиме модель, основываясь на тексте сообщений, решает нужно ли использовать одну из [встроенных функций](/ru/gigachat/guides/functions/calling-builtin-functions) или сгенерировать аргументы для пользовательских функций, описанных в массиве `functions`. При этом, если массив содержит описание хотя бы одной пользовательской функции, модель сможет вызвать встроенную функцию, только если ее название передано в массиве `functions`: ```json { ,,, "function_call": "auto", "functions": [ { "name": "text2image" }, { "name": "weather_forecast", "description": "Возвращает температуру на заданный период", "parameters": {} } ] ... } ``` example: auto responses: AuthUnauthorizedError: description: Ошибка авторизации. content: application/json: schema: type: object properties: code: type: integer description: Код ошибки. example: 6 message: type: string description: Описание ошибки. example: credentials doesn't match db data BatchTaskNotFound: description: Батч не найден. content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 404 message: type: string description: Описание ошибки. default: Batch task not found PermissionDeniedError: description: Ошибка доступа. Возникает при отправке запроса если вы оплачиваете работу с API по схеме [pay-as-you-go](/docs/ru/gigachat/api/tariffs#oplata-pay-as-you-go). content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 403 message: type: string description: Описание ошибки. default: Permission denied UnauthorizedError: description: Ошибка авторизации. content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 401 message: type: string description: Описание ошибки. default: Unauthorized TokenExpired: description: Истек срок действия токена. content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 401 message: type: string description: Описание ошибки. default: Token has expired ModelNotFound: description: Model with id not found NoSuchModel: description: | Указан неверный идентификатор модели. Список доступных моделей и их идентификаторов — в разделе [Модели GigaChat](/docs/ru/gigachat/models/main). content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 404 message: type: string description: Описание ошибки. default: No such model InternalError: description: Внутренняя ошибка сервера. content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 500 message: type: string description: Описание ошибки. default: Internal Server Error BadRequestFormat: description: | 400 Bad request. Некорректный формат запроса. TooManyRequests: description: Слишком много запросов в единицу времени. content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 429 message: type: string description: Описание ошибки. default: Too many requests ValidationError: description: Ошибка валидации параметров запроса. Проверьте названия полей и значения параметров. content: application/json: schema: type: object properties: status: type: integer description: HTTP-код сообщения. default: 422 message: type: string description: Описание ошибки. example: "Invalid params: repetition_penalty must be in range (0, +inf)" securitySchemes: Базовая аутентификация: description: | Базовая (Basic) аутентификация с помощью ключа авторизации — строки, полученной в результате кодирования в base64 идентификатора (Client ID) и клиентского ключа (Client Secret) API. Ключ авторизации передается в заголовке `Authorization`, в запросе на [получение токена доступа](/ru/gigachat/api/reference/rest/post-token). Как получить ключ авторизации и токен доступа Access token читайте в разделах [Быстрый старт для физических лиц](/ru/gigachat/individuals-quickstart) и [Быстрый старт для ИП и юридических лиц](/ru/gigachat/legal-quickstart). scheme: basic type: http Токен доступа: description: Аутентификация с помощью токена доступа Access token. Используется во всех запросах к GigaChat API, кроме запроса на [получение токена доступа](/ru/gigachat/api/reference/rest/post-token). type: http scheme: bearer bearerFormat: JWT