GigaChat API: как получить ключ и подключить нейросеть Сбера

Коротко. GigaChat API — программный доступ к нейросети Сбера: вы отправляете запрос из своего кода, бота или таблицы и получаете ответ модели. Подключение устроено чуть сложнее, чем у OpenAI: постоянный ключ авторизации сначала меняется на временный токен, который живёт 30 минут. Ниже — как получить ключ, сделать первый запрос на curl и Python, какие ошибки встречаются чаще всего и что изменилось с оплатой в сентябре 2026 года.

Что такое GigaChat API и кому он нужен

Чат на сайте Сбера подходит для разговора, а API — для автоматизации. Через гига чат API делают Telegram-ботов, ответы клиентам в поддержке, разбор входящих писем, генерацию описаний для каталога, поиск по базе знаний через эмбеддинги. Главный довод в пользу GigaChat — российский поставщик: данные обрабатываются в России, договор и закрывающие документы оформляются по местным правилам. Для компаний с требованиями к хранению данных это часто решающий фактор.

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

Как получить ключ авторизации

1. Зарегистрируйтесь в личном кабинете на портале разработчиков Сбера — по Сбер ID или почте. Физлица и компании проходят разные сценарии: у ИП и юрлиц добавляется договор.
2. Создайте проект GigaChat API. В нём появятся Client ID и Client Secret.
3. Скопируйте ключ авторизации. Это строка, в которой Client ID и Client Secret закодированы в Base64. Кабинет показывает её готовой, кодировать вручную не нужно.
4. Запомните свой scope. Для физлиц это GIGACHAT_API_PERS, для ИП и юрлиц — GIGACHAT_API_B2B или GIGACHAT_API_CORP, в зависимости от способа оплаты.

Пошаговые экраны и актуальные квоты — в официальной документации.

Токен доступа: обмен ключа раз в 30 минут

Сам ключ авторизации к нейросети не обращается. Его отправляют на адрес авторизации и получают access token, действующий 30 минут:

curl -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: $(uuidgen)" \
  -H "Authorization: Basic $GIGACHAT_AUTH_KEY" \
  --data-urlencode "scope=GIGACHAT_API_PERS"

RqUID — уникальный идентификатор запроса в формате uuid4, нужен для журналов Сбера. В ответе придут токен и время его окончания. В продакшене токен кешируют и обновляют заранее, а не запрашивают перед каждым сообщением.

Первый запрос: curl и Python

Генерацией текста занимается метод /chat/completions. Формат сообщений знаком всем, кто работал с OpenAI: массив messages с ролями system, user и assistant.

curl https://api.giga.chat/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GIGACHAT_TOKEN" \
  -d '{"model":"GigaChat","messages":[{"role":"user","content":"Привет! Как дела?"}]}'

На Python удобнее официальная библиотека gigachat (pip install gigachat): она сама меняет ключ на токен и обновляет его, когда тот истекает.

import os
from gigachat import GigaChat

giga = GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials=os.environ["GIGACHAT_AUTH_KEY"],
    scope="GIGACHAT_API_PERS",
)
r = giga.chat("Составь три варианта названия для кофейни")
print(r.choices[0].message.content)

Список моделей, доступных вашему ключу, возвращает GET /models — сверяйтесь с ним, а не со старыми примерами из интернета: линейка обновляется. Кроме чата в API есть эмбеддинги (/embeddings), подсчёт токенов, работа с файлами и функциями. Для LangChain существует пакет langchain-gigachat.

GigaChat API и OpenAI-совместимый API: отличия

Если код уже написан под OpenAI, переезд на гига чат API — не только смена адреса. Вот что придётся учесть:

В документации Сбера есть отдельный раздел о совместимости с OpenAI, но обмен ключа на токен никуда не исчезает — его придётся встроить в свой код или доверить SDK.

Частые ошибки при подключении

• 401 через полчаса работы. Истёк токен. Обновляйте его по времени из ответа OAuth или используйте SDK.
• 401 сразу. Scope не совпадает с типом аккаунта: физлицо отправляет GIGACHAT_API_B2B или наоборот.
• Ошибка SSL-сертификата. Часть сервисов Сбера использует корневой сертификат Минцифры. Установите его в систему или в окружение Python — инструкция есть в документации. Отключать проверку сертификатов в продакшене не стоит.
• 429 Too Many Requests. Превышены квоты на частоту или закончился объём токенов. Смотрите статистику потребления в личном кабинете.
• Ключ в репозитории. Храните его в переменной окружения или .env, а при утечке пересоздайте в кабинете.

Сколько стоит GigaChat API и как оплатить

Тарифицируются токены — и входящие, и исходящие; сколько ушло на запрос, видно в поле usage каждого ответа. Цены пакетов зависят от модели и типа клиента, актуальные — на странице тарифов в документации Сбера. Важное изменение: по данным документации, с 1 сентября 2026 года покупать пакеты прямо в кабинете могут только действующие клиенты, а новые оплачивают работу с моделями на платформе cloud.ru. Заложите время на регистрацию там, если запускаете проект с нуля.

Когда лучше другой API

Моделей GigaChat в Умке нет — если нужен именно Сбер, подключайтесь напрямую. Но часто задача шире: бот должен писать код, читать длинный договор или отвечать на английском, и здесь сильнее зарубежные модели. Через API Умки они доступны по одному OpenAI-совместимому ключу с адресом https://umka.chat/v1 — как это выглядит на практике, мы показали в статьях DeepSeek API и API Qwen. Сравнение моделей для программирования собрано на странице нейросетей для кода.

Платите только за запросы, с того же баланса, что и в чате. По текущим меркам умный ответ стоит около 33 токенов, быстрый — 1 токен; реальное списание зависит от длины запроса и ответа.

• 290 ₽ — 725 токенов: около 21 умного ответа;
• 690 ₽ — 1 811 токенов: около 54 умных ответов;
• 1 490 ₽ — 4 172 токена: около 126 умных ответов;
• 3 900 ₽ — 11 700 токенов: около 354 умных ответов.

При регистрации дают 60 токенов без карты — этого хватает, чтобы проверить ключ и код. Все пакеты — на странице тарифов.

Вывод

GigaChat API подключается за полчаса: проект в кабинете, ключ авторизации, обмен на токен и первый запрос к /chat/completions. Чтобы не ловить ошибки, берите официальный SDK, правильный scope и сертификат Минцифры, а новым клиентам — учитывайте оплату через cloud.ru. Если российский поставщик не обязателен, сравните ответы GigaChat с другими моделями — о самой нейросети Сбера подробно рассказано в статье Гига чат нейросеть.

Частые вопросы