GigaChat API: от сертификата до первого ответа без путаницы с ключами

Ключ проекта получен, библиотека установлена, но вместо ответа модели приходит ошибка сертификата или авторизации. Эти сбои возникают на разных этапах: сначала клиент проверяет защищённое соединение, затем получает временный токен и только потом отправляет запрос к модели. Разделите проверку на эти три шага — так не придётся менять промпт, когда проблема находится в настройках доступа.

Начните с адреса. С 17 июля 2026 года целевым базовым URL для всех категорий пользователей, физических и юридических лиц, является https://api.giga.chat; прежний адрес gigachat.devices.sberbank.ru продолжает работать только для тех, кто подключился до этой даты, и в дальнейшем будет выведен из эксплуатации (документация Sber Developers). Если вы начинаете интеграцию сейчас, прописывайте новый адрес сразу, чтобы потом не ловить загадочные отказы на ровном месте.

Шаг первый: сертификат НУЦ до всего остального

Для подключения предусмотрены сертификаты НУЦ Минцифры. Если клиент не доверяет цепочке сервера, соединение может завершиться ошибкой CERTIFICATE_VERIFY_FAILED. Установите сертификаты из официального источника и укажите приложению доверенное хранилище. Не превращайте отключение проверки TLS в постоянное решение: успешное соединение с такой настройкой не подтверждает безопасную конфигурацию.

Для Python официальный SDK позволяет передать путь к сертификату через ca_bundle_file. Другой описанный вариант — добавить сертификат в хранилище certifi. Я предпочёл бы явный путь в конфигурации приложения: так зависимость видна при развёртывании. Сам файл нужно доставить и в рабочий контейнер; существующий путь на ноутбуке не появится на сервере автоматически. После обновления окружения повторите проверку соединения. Сертификат берите по ссылкам официальной инструкции, а не из случайного ответа на форуме.

Шаг второй: обмен ключа на access-токен

Авторизационный ключ, который вы получили при создании проекта в личном кабинете, нельзя подставить в запрос к модели. Для обмена отправляют POST на https://ngw.devices.sberbank.ru:9443/api/v2/oauth с заголовком Authorization: Basic и ключом, а в ответ получают access-токен (описание эндпоинта oauth). У токена две жёсткие границы: он действует 30 минут, и запрашивать новый можно не чаще 10 раз в секунду, поэтому не стоит запрашивать токен заново перед каждым обращением к модели.

В этом же запросе есть два поля, на которых чаще всего спотыкаются. Заголовок RqUID обязан содержать уникальный идентификатор в формате UUID4 на каждый запрос, то есть генерироваться заново, а не храниться константой в коде. Тело запроса обязано содержать поле scope, и его значение зависит от типа учётной записи: GIGACHAT_API_PERS для физических лиц, GIGACHAT_API_B2B для ИП и юрлиц по платным пакетам, GIGACHAT_API_CORP для ИП и юрлиц по схеме оплаты по факту потребления (параметры авторизации). При отказе сохраните HTTP-статус и текст ошибки без секретов. Ответ 400 указывает на параметры запроса, а 401 требует проверки данных авторизации; конкретную причину уточняйте по сообщению сервера.

После получения токена выполните простой GET-запрос к https://api.giga.chat/v1/models с заголовком Authorization: Bearer и access-токеном. Полученный список моделей позволяет проверить доступ до генерации текста. Ключ проекта на этом шаге уже не используется. Затем выберите доступную модель и повторите минимальный пример генерации из документации SDK.

Если после первого запроса нужен помощник с рабочим сценарием и подключением к вашим данным, обсудить требования можно на странице ИИ-ассистентов PROMAREN. Сначала определите, какие действия ему разрешены и где он должен передавать вопрос сотруднику.

Шаг третий: жизнь с токеном, который живёт полчаса

Токен действует полчаса. Сохраняйте его вместе со сроком действия, который возвращает сервис, и обновляйте с небольшим запасом. Если несколько запросов одновременно обнаружили истечение срока, организуйте одно обновление, результатом которого воспользуются остальные. Иначе нагрузка на авторизацию растёт с числом запросов, хотя всем нужен один свежий токен.

HTTP 401 не означает автоматически, что токен истёк: заголовок может оказаться пустым или неверным. Допустимо один раз получить свежий токен и повторить запрос, если причина связана с его действительностью. Повторный отказ должен завершать попытку и попадать в журнал для диагностики. Бесконечное обновление по любому 401 маскирует ошибку настройки и создаёт лишние обращения к сервису.

Оплата: проверьте, куда попал ваш аккаунт

В быстром старте для физлиц указано: с 1 сентября 2026 года новые клиенты и клиенты без прошлых покупок пакетов могут оплачивать модели на Cloud.ru. Покупка пакетов в прежнем кабинете остаётся для действующих клиентов. Проверьте условия именно вашего аккаунта до интеграции: наличие ключа ещё не подтверждает доступный объём запросов. Для подключения через другую платформу используйте её собственную инструкцию по авторизации, а не смешивайте параметры двух способов доступа.

Что проверить перед первым запуском

Смотрите на этап отказа и сверяйтесь с официальным описанием ошибок. Ошибка TLS возникает до ответа API. Код 400 требует проверки параметров, 401 — авторизации, 402 может означать, что закончились токены выбранной модели. При 429 проверьте ограничение и темп обращений. Один внешний признак не всегда устанавливает единственную причину, поэтому сохраняйте и сообщение сервера.

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

Что должно пережить первый запуск

Этот порядок относится к серверной интеграции через GigaChat API и официальный SDK. Условия проверены 22 октября 2026 года. Не переносите авторизационный ключ в код страницы или мобильного клиента: запросы с секретом должны проходить через ваш сервер. Для браузера предусмотрите собственную авторизацию пользователя и ограничение частоты запросов, чтобы открытая кнопка чата не стала неограниченным доступом к вашему аккаунту.

Считайте первый запуск завершённым, когда приложение получает список доступных моделей, возвращает ответ на короткий запрос и корректно переживает обновление токена. Отдельно проверьте отказ при неверных настройках: пользователь должен получить понятное сообщение, а вы — диагностическую запись без секретов. Зафиксируйте рабочую конфигурацию и версии зависимостей, чтобы следующий запуск не начинался с повторного поиска сертификата.