Обработка файлов

Обновлено 27 августа 2025

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

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

Хранилище файлов позволяет получить идентификатор файла, который можно использовать при запросе к модели. Для работы с хранилищем GigaChat API предоставляет методы:

• POST /files;
• GET /files;
• GET /files/{file};
• POST /files/{file}/delete.

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

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

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

Формат	MIME-тип
txt	text/plain
doc	application/msword
docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
pdf	application/pdf
epub	application/epub
ppt	application/ppt
pptx	application/pptx

Формат	MIME-тип
jpeg	image/jpeg
png	image/png
tiff	image/tiff
bmp	image/bmp

Формат	MIME-тип
mp4	audio/mp4
mp3	audio/mp3
m4a	audio/x-m4a
wav	audio/x-wav audio/wave audio/wav audio/x-pn-wav
weba	audio/webm
ogg	audio/x-ogg
opus	audio/opus

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

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

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

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

Пример запроса для загрузки файлов:

curl --location --request POST 'https://gigachat.devices.sberbank.ru/api/v1/files' \
--header 'Authorization: Bearer access_token' \
--form 'file=@"<путь_к_файлу>/example.jpeg"' \
--form 'purpose="general"'

from gigachat import GigaChat

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

file = giga.upload_file(open("путь_к_файлу", "rb"))

public class UploadFileExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("<ключ_авторизации>")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.uploadFile(UploadFileRequest.builder()
                    .file(new byte[1000])
                    .mimeType("application/pdf")
                    .fileName("test.pdf")
                    .purpose("general")
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

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

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

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

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

Получение информации о файлах

Для получения информации о доступных в хранилище файлах GigaChat API предоставляет два метода: GET /files и GET /files/{file}.

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

curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/files' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer access_token'

import requests

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

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

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

print(response.text)

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

curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/files/:file' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer access_token'

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)

public class AvailableFilesExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("<ключ_авторизации>")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.getListAvailableFile());
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

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

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

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/files/:file/delete' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer access_token'

import requests

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

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

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

print(response.text)

public class FileDeletedExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("<ключ_авторизации>")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.deleteFile(UUID.randomUUID().toString()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

После удаления файл нельзя будет использовать для генерации.

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

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

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

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

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

Размер текстовых документов не влияет на размер запроса, но их содержимое может превышать контекстное окно модели.

Использование текстовых файлов

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

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

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer access_token' \
--data-raw '{
  "model": "GigaChat",
  "function_call": "auto",
  "messages": [
        {
            "role": "user",
            "content": "На чем основана твоя работа? Отвечай на основе приложенного документа",
            "attachments": [
              "b0989008-3ec5-4b80-aaeb-32deba7a541c"
            ]
        }
    ]
}'

from gigachat import GigaChat

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

result = giga.chat(
    {
        "function_call": "auto",
        "messages": [
            {
                "role": "user",
                "content": "На чем основана твоя работа? Отвечай на основе приложенного документа",
                "attachments": ["1460d895-2b26-4ce0-8b0d-cc7665a969df"],
            }
        ],
        "temperature": 0.1
    }
)

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

public class AttachmentExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .verifySslCerts(false)
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("<ключ_авторизации>")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.completions(CompletionRequest.builder()
                    .model(ModelName.GIGA_CHAT_MAX)
                    .message(ChatMessage.builder()
                            .content("Сделай краткий пересказ содержимого файла")
                            .role(ChatMessageRole.USER)
                            // Для передачи массива идентификаторов, используйте параметр attachments
                            .attachment("<идентификатор_файла>")
                            .build())
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Использование изображений

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

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

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer access_token' \
--data-raw '{
  "model": "GigaChat-Pro",
  "messages": [
    {
      "role": "user",
      "content": "Что изображено на рисунке?",
      "attachments": [
        "80e0bcd5-2b78-4fa7-8783-903995f56b4b"
      ]
    }
  ],
  "stream": false,
  "update_interval": 0
}'

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)

public class VisionExample {

    public static void main(String[] args) {

        GigaChatClient client = GigaChatClient.builder()
                .verifySslCerts(false)
                .authClient(AuthClient.builder()
                        .withOAuth(OAuthBuilder.builder()
                                .scope(Scope.GIGACHAT_API_PERS)
                                .authKey("<ключ_авторизации>")
                                .build())
                        .build())
                .build();
        try {
            System.out.println(client.completions(CompletionRequest.builder()
                    .model(ModelName.GIGA_CHAT_MAX)
                    .message(ChatMessage.builder()
                            .content("Что изображено на картинке?")
                            .role(ChatMessageRole.USER)
                            .attachment("<идентификатор_файла>")
                            .build())
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

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

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

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

Смотрите также

Генерация изображений

Создание изображений в формате JPG с помощью встроенной функции

POST /chat/completions

Описание запроса на генерацию