Как задавать GigaChat вопросы по документу через API

GigaChat API позволяет загрузить PDF, DOCX, XLSX и другие текстовые файлы, а затем задавать модели вопросы по их содержимому. Ниже — воспроизводимая схема по официальной документации, проверенной 21 октября 2026 года; редакция не проводила собственный тест запросов.

Инструкция относится именно к GigaChat API, а не к обычному чату. Понадобятся проект с доступом к API и токен авторизации. Условия подключения зависят от типа клиента: в быстром старте указано, что новые физлица с 1 сентября могут оплачивать работу с моделями через cloud.ru, поэтому перед началом стоит проверить доступный способ подключения и тариф.

1. Подготовьте файл

API принимает текстовые документы TXT, DOC, DOCX, PDF, EPUB, PPT, PPTX и XLSX. Один текстовый файл должен быть не больше 40 МБ. Даже файл допустимого размера может не поместиться в контекст модели; тогда сервер вернёт ошибку 422, и документ придётся разбить на части.

2. Загрузите документ

Отправьте файл методом POST /files на адрес https://api.giga.chat/v1/files. Вместе с файлом обязательно укажите purpose со значением general. В ответе найдите поле id — это идентификатор, который понадобится в запросе к модели.

Соберите multipart-запрос из двух полей: самого документа и параметра purpose. Токен доступа передайте в заголовке авторизации по схеме Bearer; секретное значение нельзя включать в публикации, логи или общий репозиторий.

3. Передайте идентификатор модели

В запросе POST /chat/completions добавьте идентификатор файла в attachments. Если документов несколько, укажите function_call со значением auto: без автоматического режима модель использует только первый документ из списка.

{ "model": "GigaChat", "function_call": "auto", "messages": [{ "role": "user", "content": "Работай только по приложенному документу. Дай краткое резюме, затем перечисли ключевые факты с указанием раздела. Если сведений нет, напиши: не найдено. Отдельно отметь неоднозначные места.", "attachments": ["FILE_ID"] }] }

4. Уточняйте ответ в том же контексте

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

5. Проверьте ошибки доступа и результат

Файл может использовать только тот пользователь, который его загрузил. Если при загрузке был задан X-Client-ID, тот же идентификатор нужно передавать и дальше; иначе возможна ошибка 403.

Результат генерации не заменяет чтение оригинала. Сверьте все числа, даты, имена и цитаты с документом. Для договоров, финансовых таблиц и нормативных текстов отдельно попросите модель перечислить фрагменты, которые она не смогла однозначно интерпретировать.