ym88659208ym87991671
Работа с файлами | Документация для разработчиков
Развернуть

Работа с файлами

Обновлено 18 февраля 2026

Модели GigaChat умеют распознавать текстовые документы, изображения и аудио, и использовать полученные данные для генерации ответов.

Работа с хранилищем файлов

В хранилище находятся добавленные файлы и сгенерированные изображения и 3D-модели.

Для работы с хранилищем GigaChat API предоставляет методы:

Загрузить файл в хранилище

Для загрузки файла в хранилище используйте метод POST /files.

Хранилище поддерживает текстовые документы, изображения и аудио разных форматов.

ФорматMIME-тип
txttext/plain
docapplication/msword
docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
pdfapplication/pdf
epubapplication/epub
pptapplication/ppt
pptxapplication/pptx

На размеры файлов действуют ограничения:

  • максимальный размер одного аудиофайла в запросе — 35 Мб;
  • максимальный размер одного изображения в запросе — 15 Мб;
  • максимальный размер одного текстового файла в запросе — 40 Мб.

Общий размер загружаемых аудиофайлов и изображений должен быть меньше 80 Мб.

При загрузке файлов обязательно передавайте purpose="general". Это позволит использовать файл в запросах на генерацию ответов.

from gigachat import GigaChat

with GigaChat() as client:
    # Загрузка файла
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Файл загружен: {uploaded.id}")

В ответ вы получите объект с описанием файла:

{
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "file123",
  "id": "6f0b1291-c7f3-43c6-bb2e-9f3efb2dc98e",
  "object": "file",
  "purpose": "general",
  "access_policy": "private",
  "modalities": [
    "image"
  ]
}

Описание параметров — в справке API.

Получить список доступных файлов

Для получения списка всех доступных вам файлов используйте метод GET /files:

from gigachat import GigaChat

with GigaChat() as client:
    # Загрузка файла
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Файл загружен: {uploaded.id}")

    # Просмотр списка файлов
    files = client.get_files()
    for file in files.data:
        print(f"{file.id}: {file.filename}")

Получить данные файла

Для получения информации об отдельном файле используйте метод GET /files/{file}:

import requests

url = "https://gigachat.devices.sberbank.ru/api/v1/files/:file"

payload={}
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer access_token'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Удалить файл из хранилища

Для удаления файла из хранилища используйте метод POST /files/{file}/delete. В параметрах пути укажите идентификатор файла, который был получен при его загрузке в хранилище. После удаления файл нельзя будет использовать для генерации.

from gigachat import GigaChat

with GigaChat() as client:
    # Загрузка файла
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Файл загружен: {uploaded.id}")

    # Удаление файла
    client.delete_file(uploaded.id)

Использование файлов для генерации ответов

Доступные в хранилище файлы можно использовать в запросах на генерацию.

Для этого передайте идентификаторы файлов в массиве attachments запроса POST /chat/completions вместе с подходящим промптом.

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

Общий размер запроса при работе с изображениями и аудио должен быть меньше 80 Мб.

Например, ваш запрос может включать текст промпта и идентификаторы изображения размером 12 Мб, и двух аудиофайлов размером 33 Мб и 21 Мб. Что в сумме даст запрос размером больше 66 Мб, в зависимости от размера промпта.

Доступ к файлам

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

В противном случае вернется ошибка:

{
    "status":403,
    "message":"Access to file '<идентификатор файла>' is denied"
}

По умолчанию, используется идентификатор Client ID. Идентификатор отображается в проекте GigaChat API, в разделе Настройки API, в поле Client ID.

Чтобы переопределить идентификатор, передайте его явно в заголовке X-Client-ID при загрузке файла. Для дальнейшей работы с файлом нужно всегда передавать такой же идентификатор.

Текстовые документы

Для генерации с помощью загруженных текстовых документов используется встроенная функция get_file_content.

Чтобы модель учитывала документы при генерации, передайте в запросе:

  • идентификаторы файлов в массиве attachments;
  • параметр "function_call": "auto", чтобы включить автоматический режим работы с функциями. Без включения автоматического режима модель будет использовать только первый документ из списка.

Если запрос содержит собственные функции, функцию get_file_content нужно указать в массиве functions. Подробнее — в разделе Совместное использование встроенных и пользовательских функций.

Размер текстовых документов не учитывается в запросах на генерацию, но их содержимое может быть больше контекста модели. В таком случае вернется ошибка с кодом 422.

Пример запроса на генерацию с двумя документами:

from gigachat import GigaChat

giga = GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False,
)

result = giga.chat(
    {
        "function_call": "auto",
        "messages": [
            {
                "role": "user",
                "content": "Краткий пересказ файлов",
                "attachments": ["b0989008-3ec5-4b80-aaeb-32deba7a541c", "d24d347f-44d6-444f-bca0-6e9df0fe9e6a"],
            }
        ],
        "temperature": 0.1
    }
)

print(result.choices[0].message.content)

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

Аудиофайлы

В запросе на генерацию можно передать несколько аудиофайлов. Суммарный размер файлов в запросе должен быть меньше 80 Мб.

from gigachat import GigaChat

giga = GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False,
)

result = giga.chat(
    {
        "function_call": "auto",
        "messages": [
            {
                "role": "user",
                "content": "Сделай краткую выдержку подкастов",
                "attachments": ["b0989008-3ec5-4b80-aaeb-32deba7a541c", "d24d347f-44d6-444f-bca0-6e9df0fe9e6a"],
            }
        ]
    }
)

print(result.choices[0].message.content)

Изображения

В одном сообщении (объект в массиве messages) можно передать только одно изображение. В одном запросе можно передать до 10 изображений, независимо от количества сообщений.

Примеры запросов на генерацию с использованием загруженных изображений.

from gigachat import GigaChat

giga = GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False,
    model="GigaChat-Pro"
)

result = giga.chat(
    {
        "messages": [
            {
                "role": "user",
                "content": "Что изображено на рисунке?",
                "attachments": ["80e0bcd5-2b78-4fa7-8783-903995f56b4b"],
            }
        ],
        "temperature": 0.1
    }
)

print(result.choices[0].message.content)

Тарификация изображений

При отправке изображений в GigaChat они преобразуются в токены. Количество токенов после преобразования зависит от размера и разрешения изображения. Максимальное количество токенов, которые могут быть потрачены на обработку изображения — 1792.

Токены оплачиваются в соответствии с тарифами GigaChat API.

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Это полезный материал?
Развернуть
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.