GigaChat API: безопасный старт по шагам

Всё начинается с Authorization Key из личного кабинета разработчика — это ключ для обмена, а не готовый токен доступа. Его обменивают на OAuth-эндпоинте с явным scope (точные значения для персонального, бизнес- и корпоративного доступа перечислены в официальном справочнике) и получают короткоживущий access token — на момент написания документация указывает около 30 минут; ориентируйтесь на официальный справочник. Кэшируйте токен и обновляйте незадолго до истечения, а не на каждый запрос; ключ держите на сервере — вне клиентского кода, логов и репозиториев.

Эндпоинты API работают с сертификатами российского доверенного корневого центра (НУЦ Минцифры), которого нет в большинстве стандартных хранилищ доверия. Безопасный путь — добавить корневой сертификат в хранилище вашего HTTP-клиента и оставить проверку TLS включённой. Отключать проверку сертификата, «чтобы заработало», — значит убрать ту самую защиту, ради которой TLS существует; любой сниппет с таким советом считайте багом.

Запросите каталог моделей своим токеном и выбирайте из того, что реально доступно вашему аккаунту, — ваш каталог и есть достоверный список именно для вас. Как вендор позиционирует каждую модель, смотрите в официальном обзоре моделей, а не в сторонних «уровнях»; дальше зафиксируйте точное имя модели в конфигурации, перепроверяйте каталог при обновлениях и выбирайте по задаче, а не по самому громкому имени.

Да: функции описываются параметрами в JSON Schema, модель сама решает, когда их вызвать, и возвращает структурированные аргументы; тот же механизм — надёжный путь к машиночитаемому выводу. Две привычки делают это production-уровнем: валидируйте каждый возвращённый объект по своей схеме до того, как действовать, и не рассчитывайте, что формат удержится на одних словесных инструкциях — контракт задаёт схема, промпт лишь подсказывает.

Файл загружается через эндпоинт файлов, вы получаете идентификатор и прикладываете его к сообщению в чате — так устроены вопросы по документам и понимание изображений. Генерация изображений идёт через тот же чат-интерфейс: ответ ссылается на созданный файл, который затем скачивается по идентификатору. Поддерживаемые форматы и размеры проверьте в официальных лимитах до того, как встраивать загрузку в продуктовый сценарий.

Включите стриминг, чтобы получать ответ порциями через server-sent events, — это основа отзывчивого интерфейса; читайте фрагменты до завершающего события потока [DONE], не полагаясь на фиксированную форму последнего сообщения. По ошибкам смотрите статус и сообщение ответа: истёкший access token обновите и повторите запрос один раз; в остальных случаях перепроверьте Authorization Key или token, scope и обязательные заголовки; на ограничение частоты отвечайте паузой с нарастающей задержкой, а не повтором в лоб; каждый структурированный ответ проверяйте до использования. Логируйте идентификаторы запросов, но не содержимое с пользовательскими данными.