GigaChat API документация и тарифы: preflight перед запуском

Раздел

Модели и API

Сложность

средняя

Обновлено

2026-05-22

Короткий ответ

GigaChat API документацию и тарифы нужно читать не как справочник “куда отправить запрос”, а как production preflight: какой scope куплен, какой base URL используется, какие модели реально доступны, как получается токен, какие лимиты действуют, что будет при 401/402/429 и как команда увидит расход токенов до счета.

На 22 мая 2026 года в официальной справке GigaChat API есть REST API, gRPC API, SDK, Postman/Insomnia-коллекции, описание ошибок, модели, тарифы и мониторинг потребления. Тарифные страницы для физлиц и юрлиц обновлены 18 мая 2026 года и указывают, что цены действуют с 1 февраля 2026 года. Этого достаточно для первого server-side запуска, но не достаточно для бизнеса, если не зафиксировать владельца ключа, бюджет, журнал без секретов, fallback и день проверки тарифов перед публикацией.

Эта страница дополняет общий материал GigaChat API: ключи, модели, ограничения и план интеграции и чеклист стоимости LLM API. Здесь фокус уже: как пройти документацию и тарифы перед production, чтобы не перепутать personal scope с корпоративным, пакет токенов с pay-as-you-go и broad API-демо с управляемым сервисом.

Когда нужна эта страница

Запросы gigachat api документация и gigachat api тарифы обычно появляются в момент, когда команда уже решила “попробовать GigaChat”, но еще не готова к production. Типичная ситуация:

• разработчик нашел SDK и сделал локальный hello world;
• продукт хочет понять, сколько это будет стоить;
• безопасность спрашивает, куда уйдут данные;
• бухгалтерия спрашивает, кто оплатит токены;
• поддержка хочет fallback, если API недоступен;
• владелец процесса просит не ломать SLA ради эксперимента.

Если нужна общая оценка провайдеров, сначала откройте YandexGPT, GigaChat, OpenAI и Qwen. Если нужна именно навигация по официальной документации, тарифам и первому запуску, идите по checklist ниже.

Карта документации

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

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

Доступ и scope

GigaChat REST API использует ключ авторизации для получения access token через OAuth. В запросе на токен нужно указать scope, который соответствует версии доступа:

• GIGACHAT_API_PERS - доступ для физических лиц;
• GIGACHAT_API_B2B - ИП и юридические лица при работе по предоплате;
• GIGACHAT_API_CORP - ИП и юридические лица при оплате по фактическому использованию.

Access token действует ограниченное время, поэтому production-сервис должен уметь обновлять его, а не хранить один полученный токен в конфиге. Для REST-запросов после OAuth используется Authorization: Bearer <token>.

Отдельно выберите base URL. В документации есть основной адрес для физлиц и юрлиц с оплатой по счету-оферте или договору с ООО “СалютДевайсы”, а также адрес https://api.giga.chat/ для юрлиц, которые оплачивают API по договору с ООО “Салют для Бизнеса”. Это не косметика: неверный base URL может выглядеть как ошибка авторизации, недоступность модели или неправильный тарифный контур.

Минимальная карточка доступа:

service: support-draft-assistant
environment: staging
owner: support-platform
scope: GIGACHAT_API_B2B
base_url: https://gigachat.devices.sberbank.ru/api/v1
model: GigaChat-2-Pro
auth_key_storage: hosting secret / vault
token_refresh: server-side
budget_owner: finance + product owner
review_date: 2026-05-21

Ключ авторизации не должен попадать во frontend, репозиторий, markdown-инструкции, скриншоты, prompt, issue, чат или клиентские логи. В SDK может быть удобно передать credentials напрямую, но источник credentials должен быть server-side secret, а не личный файл разработчика.

Первый серверный запрос

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

# .env.example без реальных секретов
GIGACHAT_AUTH_KEY=
GIGACHAT_SCOPE=GIGACHAT_API_B2B
GIGACHAT_BASE_URL=https://gigachat.devices.sberbank.ru/api/v1
GIGACHAT_MODEL=GigaChat-2-Pro

Проверка должна идти с backend или CLI-сервиса. Не начинайте с браузера: даже если библиотеку можно заставить работать на клиенте, пользователь увидит network calls и часть runtime-контекста. Для production нужен серверный слой, который сам добавляет токен, маскирует логи и возвращает приложению только безопасный статус.

После hello world проверьте:

1. RqUID создается на каждый OAuth-запрос.
2. Access token обновляется без ручного вмешательства.
3. TLS/сертификаты настроены согласно официальной инструкции.
4. Таймаут, retry и backoff имеют лимит.
5. Лог содержит request id, модель, latency, usage и статус.
6. Лог не содержит auth key, bearer token, полный prompt с секретами и персональные данные без правила хранения.

Модели и endpoint

Не пишите в задаче “подключить GigaChat”. Пишите конкретную модель, endpoint и дату проверки. На publish day проверьте GET /models, страницу выбора модели и тарифы: доступность моделей и стоимость могут меняться.

Практичная схема выбора:

Для новых интеграций выбирайте модель не по описанию в документации, а по 50-200 реальным примерам: вопросы поддержки, документы, классификация, короткие и длинные prompts, ошибки, отказ без источника. Сравнивайте стоимость успешного результата: ответ, который оператор переписывает, дороже красивого ответа из демо.

Тарифный preflight

Тарифы GigaChat API нужно проверять в день публикации или релиза. На 22 мая 2026 года официальная страница для физлиц описывает freemium-режим на 1 000 000 токенов в течение 12 месяцев и платные пакеты, а страница для юрлиц - два больших режима: заранее купленные пакеты токенов и оплату по фактическому использованию. В pay-as-you-go есть синхронный и асинхронный режимы; асинхронный дешевле, но дольше выполняется. Это влияет на архитектуру: поддержке обычно нужен быстрый синхронный ответ, а массовая обработка документов может уйти в очередь.

Для юрлиц в pay-as-you-go важно не пропустить минимальный базовый тариф: если сервис использовался, но операций меньше 600 рублей за месяц, официальный расчет все равно списывает 600 рублей. Для пилота это не страшно, но в документации продукта надо явно написать, кто следит за monthly spend, кто подтверждает переход с пакета на pay-as-you-go и какой сценарий отключается первым при перерасходе.

Официальные тарифные страницы также отмечают, что модели первого поколения (GigaChat, GigaChat-Pro, GigaChat-Max) недоступны, а запросы к ним перенаправляются на аналоги второго поколения (GigaChat-2, GigaChat-2-Pro, GigaChat-2-Max). Не делайте это скрытой совместимостью: для новой интеграции лучше явно указать модель второго поколения, а старые id оставить только в плане миграции.

Не делайте pricing decision только по цене 1000 токенов. Для бизнес-сценария нужны:

• средний и p95 размер prompt;
• средний output;
• доля retries;
• RAG-фрагменты и embeddings;
• доля ручной проверки;
• стоимость fallback;
• лимит на пользователя, команду и сервис;
• ручной стоп при аномальном расходе.

Метод получения остатка токенов полезен для пакетов, но не заменяет billing-контроль для pay-as-you-go: официальная документация отдельно описывает, что /balance не подходит для оплаты по фактическому использованию и вернет ошибку доступа. Поэтому для корпоративного запуска нужен свой учет: key alias, service name, model, usage, дата, владелец и причина запроса.

Лимиты и ошибки

Лимиты нужно проектировать до продакшена. В официальной документации описаны ограничения по токенам и потокам: физлицам доступен один поток, а юрлицам и ИП по умолчанию 10 потоков; увеличение обсуждается через поддержку GigaChat API. Это значит, что код должен иметь очередь, backoff и отказ, а не бесконечный retry.

Минимальная таблица обработки:

Отдельно обработайте тематические ограничения. Если ответ завершился ограничением, продукт не должен показывать “пустой сбой” или выдуманный fallback. Лучше вернуть понятное сообщение, записать категорию и отправить сценарий человеку.

Данные и логи

API-доступ не решает вопрос данных. До первого реального prompt зафиксируйте, что нельзя отправлять:

• пароли, токены, private keys, cookies;
• production .env;
• полные персональные данные без правового основания;
• платежные данные;
• договоры и КП целиком без необходимости;
• коммерческие условия клиента под NDA;
• incident logs с секретами;
• чужой код или документы, если договор запрещает внешний API.

Для журналирования хватит технической карточки:

Если нужно хранить prompts для eval, отделите eval-корпус от production-логов: обезличьте данные, храните ссылку на внутренний источник с правами и добавьте срок удаления.

День публикации

Перед релизом или обновлением статьи пройдите publish-day проверку. Она нужна потому, что официальные страницы моделей, тарифов и SDK меняются быстрее, чем внутренняя инструкция.

1. Открыть официальные страницы: API reference, authorization, model selection, tariffs, limitations, errors, SDK.
2. Проверить дату обновления и model id.
3. Проверить выбранный scope, base URL и договорный контур.
4. Проверить, не изменились ли цены, минимальные платежи, пакеты или режимы sync/async.
5. Проверить лимиты потоков и способ увеличения.
6. Выполнить staging-запрос без реальных клиентских данных.
7. Проверить 401/402/429 handling.
8. Проверить, что статья и внутренний runbook не содержат ключей, токенов и выдуманных тарифов.

Если факты не подтверждаются официальными источниками, не публикуйте “примерную цену” или “скорее всего доступно”. Пишите: требуется проверка в личном кабинете или у владельца договора.

Чеклист

• Документация проверена в день запуска.
• Выбран конкретный scope: PERS, B2B или CORP.
• Base URL соответствует договорному и платежному контуру.
• Auth key хранится server-side.
• Access token обновляется автоматически и не лежит в конфиге.
• Модель выбрана по eval-набору, а не только по описанию.
• Тарифный режим зафиксирован: пакет токенов или pay-as-you-go.
• Есть бюджет, владелец счета и стоп-сигнал по расходу.
• 400/401/402/403/413/422/429/500 обрабатываются разными сценариями.
• Логи не содержат ключи, bearer tokens и sensitive prompts.
• Есть fallback и ручная деградация для production.
• Сравнение стоимости ведется по успешному сценарию, а не по одному вызову.

FAQ

Где начинать: с документации API или тарифов?

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

Можно ли просто использовать пример из SDK?

Для hello world - да. Для production - нет. Нужны server-side secrets, token refresh, обработка ошибок, журнал, бюджет и eval-набор. SDK снимает часть работы с API, но не делает процесс безопасным.

Что выбрать: пакет токенов или pay-as-you-go?

Это зависит от договора, прогнозируемого объема, сценария и контроля расходов. Для пакетов полезен учет остатка токенов, а для pay-as-you-go нужен отдельный billing-контроль и лимиты в вашем сервисе.

Нужно ли переписывать текущую статью про GigaChat API?

Не обязательно. Общая статья остается входом в интеграцию. Эта страница закрывает другой интент: как читать официальные docs и tariffs перед production. Внутренними ссылками они должны поддерживать друг друга, а не повторять один текст.

Что делать, если тарифы изменились?

Обновить дату проверки, source list, тарифные выводы и runbook. Не оставляйте старые цены в статье без пометки даты, потому что пользователь примет их за текущие условия.

Что читать дальше?

Начните с GigaChat API для общей архитектуры, затем откройте стоимость LLM API для бюджета, Qwen API key и DeepSeek API key для сравнения дисциплины provider-key management.