GigaChat API: как подключить, какие модели доступны и как платить рублями

01Какие модели и возможности доступны

В GigaChat API сейчас четыре генеративные модели и несколько моделей для векторного представления текста. Выбор делается параметром model в запросе: если его не указать, SDK по умолчанию отправит запрос в GigaChat Lite.

• Диалог и генерация текста через Chat Completions, плюс потоковая выдача токенов
• Генерация структурированных данных, работа с функциями (function calling)
• Создание изображений и генерация 3D-моделей
• Работа с файлами и пакетная обработка задач
• Векторное представление текста (эмбеддинги) для поиска и RAG
• Подсчёт токенов до отправки запроса — метод POST /tokens/count
• Совместимость с OpenAI SDK и утилита-прокси для перенаправления запросов

02Регистрация, ключ и первый запрос

developers.sber.ru → Личный кабинет → GigaChat API

Проекты → Новый проект → GigaChat API

Authorization key = <ключ_авторизации>

Сертификаты НУЦ Минцифры → в системное хранилище

POST https://api.giga.chat/v1/chat/completions

curl -L -X POST 'https://api.giga.chat/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <токен_доступа>' \
  --data-raw '{
    "model": "GigaChat-2-Max",
    "messages": [
      {"role": "user", "content": "Привет! Как дела?"}
    ]
  }'

03Токен доступа живёт 30 минут

Ключ авторизации сам по себе запросы не подписывает. Сначала его меняют на токен доступа в отдельном OAuth-сервисе, и этот токен действует 30 минут — значит, в приложении нужен код обновления, а не один статичный заголовок.

import requests

url = "https://ngw.devices.sberbank.ru:9443/api/v2/oauth"
payload = "scope=GIGACHAT_API_PERS"   # для физлиц; юрлица используют свой scope
headers = {
    "Content-Type": "application/x-www-form-urlencoded",
    "RqUID": "6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e",  # любой UUID
    "Authorization": "Bearer <ключ_авторизации>",
}
r = requests.post(url, data=payload, headers=headers)
token = r.json()["access_token"]   # действует 30 минут

04Совместимость с OpenAI SDK и инструменты

Формат сообщений GigaChat API частично совместим с OpenAI API, поэтому часть кода переносится почти без правок: меняются базовый адрес и способ получения ключа. Для авторизации в этом сценарии используется уже токен доступа, а не ключ авторизации.

from openai import OpenAI

client = OpenAI(
    api_key="<токен_доступа>",
    base_url="https://api.giga.chat/v1",
)

completion = client.chat.completions.create(
    model="GigaChat",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello World!"},
    ],
)
print(completion.choices[0].message)

05Квоты, потоки и ограничения

Обмен данными ограничен токенами: в среднем один токен — это 3–4 символа, а точное число для конкретного промпта можно посчитать заранее методом POST /tokens/count, чтобы не ловить ошибку на боевом запросе. Второе ограничение — параллельные потоки: их число зависит от типа клиента.

• Один токен ≈ 3–4 символа, длина промпта с контекстом и ответа зависит от модели
• Поток для физлиц — один, даже если вы купили пакет токенов
• Юрлицам и ИП по умолчанию 10 потоков, лимит расширяется по письменному запросу
• Запрос с запрещённой темой возвращает признак в ответе: поле choices.finish_reason = «blacklist»
• Корпоративные клиенты могут настраивать собственные ограничения по письму в поддержку
• Статистику расхода токенов удобно смотреть в личном кабинете — она же помогает ловить утечки бюджета

06Оплата рублями и тарифы

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

07Экосистема: чем работать с GigaChat API

Официальный путь — библиотеки GigaChain и Python-клиент GigaChat. Вокруг есть и community-инструменты: прокси для OpenAI-совместимых клиентов, узлы для n8n, коннектор для 1С. По звёздам на GitHub видно, где сосредоточена активность.

08Что учесть до продакшена

• Сертификаты НУЦ Минцифры: поставьте их на бою, а не отключайте проверку TLS
• Обновление токена: 30 минут — короткий срок, кэшируйте токен и обновляйте заранее, а не по факту ошибки
• Потоки: один поток для физлиц и десять для юрлиц — это уже очередь; для параллельных задач запрашивайте расширение
• Предварительная оценка объёма: /tokens/count до отправки корпуса документов
• Мониторинг расхода: статистика потребления токенов в личном кабинете — минимальный контроль бюджета
• Ограничения тем: запрещённые запросы возвращают признак в ответе — обработайте этот случай в коде, а не падайте на нём
• Резервный маршрут: даже с российским API разумно держать второй провайдер на случай недоступности