GigaChat API: подключение и документация

Что можно сделать через GigaChat API

Сервис помогает разобрать обращения, подготовить описания товаров и искать сведения в документах. Для AI-агента определите источники и случаи передачи вопроса человеку.

Браузер передаёт вопрос вашему серверу. Сервер проверяет пользователя, добавляет инструкцию и вызывает модель; ключ остаётся вне клиентского кода.

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

Стоимость доступа и тарифы

На сентябрь 2026 года условия оплаты различаются для новых и действующих клиентов. С 1 сентября новым клиентам предлагают оплату через Cloud.ru. Приведённые ниже пакеты относятся к действующим клиентам Сбера.

Для нового подключения сверяйте документацию платформы. Далее описана авторизация прямого API Сбера. Разработку приложения оплачивают отдельно.

Бесплатные токены и пакеты для физлиц

Freemium предусматривает 365 миллионов токенов на 12 месяцев: Lite получает 250 миллионов, Pro 40, Max 25, Ultra 50 миллионов. Генерация в этом режиме идёт в одном потоке.

Платные пакеты для действующих физических лиц действуют месяц со дня оплаты. Цены в таблице включают НДС, проверены на сентябрь 2026 года.

Оплата для организаций

Действующим юридическим клиентам доступны пакеты и оплата по факту. Только при оплате по факту действует минимальное списание 600 ₽ за месяц использования. Если запросов не было, платёж не взимается.

Синхронная генерация стоит 0,065 ₽ за тысячу токенов Lite, 0,5 ₽ для Pro и 0,65 ₽ для Max. Асинхронная обработка в опубликованной таблице вдвое дешевле. Она подходит для задач, где можно подождать результат.

Срок пакета зависит от поставщика по договору: у «СалютДевайсы» месяц, у «Салют для Бизнеса» 12 месяцев. Не переносите эти условия на новый договор с Cloud.ru.

Как получить API-ключ для GigaChat

Параметр SDK credentials принимает ключ авторизации для получения access token. Client ID и Client Secret не заменяют токен доступа.

При ручной авторизации нужен POST https://ngw.devices.sberbank.ru:9443/api/v2/oauth. Заголовок Authorization использует схему Basic, а RqUID содержит идентификатор uuid4. Для тела запроса задайте Content-Type: application/x-www-form-urlencoded.

Ответ содержит access_token и expires_at. Токен действует 30 минут; повторно используйте его до истечения срока. В последующих запросах укажите схему Bearer. Не записывайте реквизиты авторизации в журнал.

SDK управляет авторизацией. При работе через requests кэшируйте токен на сервере и обновляйте заранее по expires_at. При одновременных обращениях обновление должен выполнять один обработчик.

1. Зарегистрируйтесь в личном кабинете разработчика и создайте проект. Проверьте доступные для вашего типа клиента условия подключения.
2. Получите ключ авторизации в настройках проекта. Сохраните его в защищённом окружении сервера, без публикации в коде сайта.
3. Настройте доверенные сертификаты НУЦ Минцифры по инструкции для вашей системы. Убедитесь, что приложение использует нужное хранилище сертификатов.
4. Выберите scope под свой доступ. Затем получите токен и отправьте короткое тестовое сообщение.

Первый запрос к API GigaChat на Python

На сентябрь 2026 года целевой URL: https://api.giga.chat. Адрес https://gigachat.devices.sberbank.ru остаётся доступен ранее подключённым пользователям.

Установите пакет командой python -m pip install gigachat. Задайте GIGACHAT_CREDENTIALS с ключом авторизации и GIGACHAT_CA_BUNDLE_FILE с путём к доверенным сертификатам PEM.

Пример использует доступ физлица и модель GigaChat-2. Для организации замените scope. Метод client.chat.create и чтение response.messages соответствуют текущему руководству Python SDK.

import os
from gigachat import GigaChat

with GigaChat(
    credentials=os.environ["GIGACHAT_CREDENTIALS"],
    scope="GIGACHAT_API_PERS",
    base_url="https://api.giga.chat/v1",
    ca_bundle_file=os.environ["GIGACHAT_CA_BUNDLE_FILE"],
    model="GigaChat-2",
) as client:
    response = client.chat.create("Объясните, что такое языковая модель.")
    print(response.messages[0].content[0].text)

Документация GigaChat API: запрос и ответ

Ручной запрос: POST https://api.giga.chat/v1/chat/completions. Передайте Content-Type: application/json и авторизацию Bearer. Тело JSON содержит model и messages.

В REST v1 текст находится в choices[0].message.content, расход токенов в usage. Этот формат отличается от response.messages в новом интерфейсе SDK.

Для curl сохраните JSON в request.json. Пример для Bash использует временный токен GIGACHAT_ACCESS_TOKEN и сертификаты GIGACHAT_CA_BUNDLE_FILE. Не выводите заголовки авторизации.

Документация GigaChat API описывает поля и ошибки. Сверяйте формат ответа с выбранным методом.

curl --fail-with-body --silent --show-error \
  --cacert "$GIGACHAT_CA_BUNDLE_FILE" \
  'https://api.giga.chat/v1/chat/completions' \
  -H "Authorization: Bearer $GIGACHAT_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

Тело тестового запроса

Сохраните этот объект в request.json в UTF-8. Ожидаемый результат: текст объяснения в choices, сведения о расходе в usage.

{
  "model": "GigaChat-2",
  "messages": [
    {
      "role": "user",
      "content": "Объясните, что такое языковая модель."
    }
  ],
  "stream": false
}

Промпт, история диалога и выбор модели

Системный промпт, или system prompt, задаёт правила поведения GigaChat через API. Первое сообщение получает role system, вопрос посетителя: role user.

Например: «Отвечайте на русском языке по приложенному описанию товара. Если сведений нет, попросите уточнение. Не придумывайте стоимость доставки». Такой промпт задаёт проверяемое поведение для консультанта интернет-магазина.

Историю хранит ваше приложение. Для продолжения диалога передавайте предыдущие сообщения user и assistant в messages. Удаляйте нерелевантные реплики, сохраняя сведения, нужные для ответа.

GigaChat Lite подходит для простых быстрых ответов. GigaChat Pro рассчитан на сложные инструкции, GigaChat Max на более трудные задачи. Сравните качество на своих примерах: название модели не гарантирует точность.

GET /v1/models возвращает список доступных ID. На сентябрь 2026 года тарифы также включают GigaChat-3-Ultra для Freemium.

Потоковый ответ, файлы и вызов функций

Когда нужен streaming

При stream: true результат поступает частями с типом Content-Type: text/event-stream. Обработчик должен собирать фрагменты и учитывать разрыв соединения.

Для первоначальной отладки оставьте stream: false. Так проще сравнить полный результат с ожидаемым.

Function calling для обращения к вашим системам

Вызов функций позволяет связать GigaChat и API вашей системы. Например, ассистент может подготовить параметры поиска заказа. Пользовательскую функцию исполняет сервер приложения, а модель предлагает аргументы.

Описание передаётся в functions. Поле description объясняет назначение, parameters задаёт объект типа object. В properties укажите type string для строки, а required перечисляет обязательные аргументы. При function_call проверьте параметры до выполнения действия.

Сохраните сообщение assistant с function_call и functions_state_id, если он пришёл. Добавьте результат с role function и отправьте историю модели. Проверяйте права пользователя; изменение заказа требует подтверждения.

Документы, изображения и база знаний

В REST v1 идентификаторы загруженных файлов передаются в attachments. Попросите извлечь данные из документа или распознать объекты и текст на изображении. Сверьте результат с оригиналом.

Для базы знаний рассмотрите эмбеддинги, векторные представления текста. Сначала найдите подходящие фрагменты, затем передайте их модели вместе с вопросом. Храните связь фрагмента с исходным документом, чтобы показывать проверяемую ссылку.

Создание изображений

Для генерации картинки передайте описание и function_call: auto. Встроенная функция text2image создаёт изображение. Скачайте результат по возвращённому идентификатору через GET /v1/files/{file_id}/content. Не вставляйте ответ модели в страницу как непроверенный HTML.

Ошибки подключения и проверка перед запуском

При работе через requests параметр verify отвечает за проверку сертификата сервера. Не устраняйте ошибку SSL значением verify=False. Укажите корректный файл сертификатов или настройте доверенное хранилище.

Сохраняйте ID обращения, статус и длительность без переписки и секретов. Для 429 и временных сбоев ограничьте повторные попытки. Показывайте пользователю причину остановки.

Проверьте пустой вопрос, длинный диалог и недоступность внешней системы. Контролируйте finish_reason: blacklist означает ограничение контента. Предложите переформулировать запрос без обхода правил сервиса.

На сентябрь 2026 года прямой API Сбера допускает для физлиц один одновременный запрос, включая платные пакеты. Для ИП и организаций по умолчанию доступны 10 потоков. Очередь ограничивает параллельные обращения; stream управляет выдачей частей одного ответа.

POST /v1/tokens/count считает токены текста. GET /v1/balance возвращает остаток купленных пакетов, при оплате по факту выдаёт 403. Учитывайте историю и будущий ответ. При исчерпании пакета передавайте обращение оператору.

Что проверить при переносе с OpenAI API

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

Проведите тестирование GigaChat API на прежних русскоязычных запросах. Проверьте JSON и ошибки библиотеки.

Подключение к сайту и стоимость разработки

Для разработки чат-бота на GigaChat подготовьте сценарий, примеры диалогов и перечень систем для обмена данными.

В seosite1 цена после брифа. Минимальный бюджет проекта от 50 тыс. ₽, каждый этап оплачивается вперёд.

Цена зависит от базы знаний, прав доступа, обработки ошибок и интерфейса. Состав работ и сроки согласуем после брифа.