Развернуть

Использование SDK

Обновлено 8 июня 2026

Для работы с REST API GigaChat доступны одноименные библиотеки на Python , TypeScript/JavaScript и Java .

Перед началом работы убедитесь, что у вас установлены сертификаты НУЦ Минцифры.

SDK позволяет автоматически авторизовать запросы, и предоставляет методы для работы с GigaChat API. С их помощью можно:

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

Для работы с GigaChat также доступны партнерские пакеты LangChain, которые позволяют использовать модели GigaChat с фреймворком LangChain .

Подробнее — в документации GigaChain.

Начало работы

Чтобы начать работу с API с помощью SDK:

Установите или подключите в проект подходящую библиотеку:
pip install gigachat
npm install gigachat
Подключите библиотеку в зависимости с помощью Gradle или Maven
Gradle:
implementation("chat.giga:gigachat-java:0.1.18")
Maven:
<dependency> <groupId>chat.giga</groupId> <artifactId>gigachat-java</artifactId> <version>0.1.18</version> </dependency>

Инициализируйте объект GigaChat:

from gigachat import GigaChat

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

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  scope: 'GIGACHAT_API_PERS',
  model: 'GigaChat',
});

public class CompletionExample {

    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();

        System.out.println(client.completions(CompletionRequest.builder()
                .model(ModelName.GIGA_CHAT)
                .message(ChatMessage.builder()
                        .content("текст запроса")
                        .role(Role.USER)
                        .build())
                .build()));
    }
}

При работе с библиотеками на Python и TS/JS объект GigaChat принимает параметры:

credentials — ключ авторизации для обмена сообщениями с GigaChat API. О том как получить ключ авторизации — в разделе Быстрый старт.
scope — версия API, к которой будет выполнен запрос. Необязательный параметр. Возможные значения:
- GIGACHAT_API_PERS — версия API для физических лиц;
- GIGACHAT_API_B2B — версия API для ИП и юрлиц при работе по предоплате.
- GIGACHAT_API_CORP — версия API для ИП и юрлиц при работе по постоплате.
По умолчанию запросы передаются в версию для физических лиц.
model — необязательный параметр, в котором можно явно задать модель GigaChat.

Примеры работы с SDK

Получить список доступных моделей

Выполняет запрос GET /models и возвращает список доступных моделей.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as client:
    models = client.get_models()
    for model in models.data:
        print(f"{model.id_} (owned_by={model.owned_by})")

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  model: 'GigaChat',
});

const models = await giga.getModels();
console.log(models);

public class ModelListExample {

    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.models());
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Сгенерировать текст

Метод выполняет запрос POST /chat/completions и возвращает ответ модели, сгенерированный на основе переданных сообщений.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    scope="GIGACHAT_API_PERS",
    model="GigaChat",
    verify_ssl_certs=False,
) as client:
    response = client.chat.create("Привет, как дела?")
    print(response.messages[0].content[0].text)

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  model: 'GigaChat',
});

giga
  .chat({
    messages: [{ role: 'user', content: 'Привет, как дела?' }],
  })
  .then((resp) => {
    console.log(resp.choices[0]?.message.content);
  });

public class CompletionExample {

    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.completions(CompletionRequest.builder()
                    .model(ModelName.GIGA_CHAT)
                    .message(ChatMessage.builder()
                            .content("Привет, как дела?")
                            .role(Role.USER)
                            .build())
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Потоковая генерация токенов

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

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as client:
    for chunk in client.chat.stream("Напиши короткое стихотворение о программировании"):
        for msg in chunk.messages or []:
            for part in msg.content or []:
                if part.text:
                    print(part.text, end="", flush=True)
    print()

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  model: 'GigaChat-Pro',
});

for await (const chunk of giga.stream('Напиши отчет на тему ипотечного кризиса')) {
  process.stdout.write(chunk.choices[0]?.delta.content || '');
}

public class CompletionStreamingExample {

    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 {
            client.completionStream(CompletionRequest.builder()
                    .model(ModelName.GIGA_CHAT_MAX)
                    .message(ChatMessage.builder()
                            .content("Напиши отчет на тему ипотечного кризиса")
                            .role(Role.USER)
                            .build())
                    .build(), (c) -> System.out.println(
                            c.choices().get(0).delta().content() != null ? c.choices().get(0).delta().content() : ""
                    ));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Сгенерировать эмбеддинг

Выполняет запрос POST /embeddings и возвращает векторное представление текста.

Подробнее об использовании эмбеддингов — в разделе Векторное представление текста.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as giga:
    response = giga.embeddings(["Hello world!"], model="EmbeddingsGigaR")
    print(response)

const response = await giga.embeddings(['Hello world!']);

console.log(response.data);

public class EmbeddingExample {

    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.embeddings(EmbeddingRequest.builder()
                    .model("Embeddings")
                    .input(List.of("Hello world!"))
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Скачать сгенерированное изображение

Метод выполняет запрос GET /files/{file_id}/content и возвращает файл изображения в бинарном представлении в формате JPG.

Подробнее о работе с файлами с помощью API — в разделе Обработка файлов.

image = giga.get_image(file_id='идентификатор_файла')

import { GigaChat, detectImage } from 'gigachat';
import fs from 'node:fs';
import path from 'node:path';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  model: 'GigaChat',
});

const resp = await giga.chat({
  messages: [{ role: 'user', content: 'Сгенерируй изображение котика' }],
  function_call: 'auto',
});
const detectedImage = detectImage(resp.choices[0]?.message.content ?? '');
if (detectedImage && detectedImage.uuid) {
  const image = await giga.getImage(detectedImage.uuid);
  fs.writeFile('image.jpg', image.content, 'binary', () => {});
}

public class ImageDownloadFromCompletionsExample {

    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 {
            CompletionResponse response = client.completions(CompletionRequest.builder()
                    .model(ModelName.GIGA_CHAT)
                    .message(ChatMessage.builder()
                            .content("Сгенерируй изображение котика")
                            .role(Role.USER)
                            .build())
                    .build());
            if (response.choices() != null && !response.choices().isEmpty()) {
                String fileId = response.choices().get(0).message().attachments().get(0);
                System.out.println(Arrays.toString(client.downloadFile(fileId, null)));
            }
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

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

Методы для работы с хранилищем файлов.

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

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

Подробнее о работе с файлами с помощью API — в разделе Обработка файлов.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as client:
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Файл загружен: {uploaded.id_}")

import GigaChat from 'gigachat';
import fs from 'node:fs';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
});

const file = new File([fs.readFileSync('document.pdf')], 'document.pdf');
const uploadedFile = await giga.uploadFile(file);
console.log(`Файл загружен: ${uploadedFile.id}`);

public class UploadFileExample {

    public static void main(String[] args) throws IOException {
        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(Paths.get("/path/to/document.pdf").toFile())
                    .purpose("general").build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Получить список файлов

Просмотр файлов, доступных в хранилище с помощью метода GET /files.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as client:
    files = client.get_files()
    for file in files.data:
        print(f"{file.id_}: {file.filename}")

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
});

const files = await giga.getFiles();
console.log(files.data);

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.availableFiles());
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Просмотр информации о файле

Вызов метода GET /files/{file}.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as client:
    single_file = client.get_file("<идентификатор_файла>")
    print(f"{single_file}")

Удаление файла

Вызов метода POST /files/{file}/delete.

from gigachat import GigaChat

with GigaChat() as client:
    client.delete_file("<идентификатор_файла>")

Подсчитать количество токенов в запросе

Выполняет запрос POST /tokens/count и возвращает объект с информацией о количестве токенов, подсчитанных заданной моделью в строках.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    verify_ssl_certs=False
) as client:
    result = client.tokens_count(["12345"], model="GigaChat-2-Pro")
    print(result)

const response = await giga.tokensCount(['Привет, как дела?', 'Как дела, как дела']);

console.log(response);

public class TokenCountExample {

    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.tokensCount(TokenCountRequest.builder()
                    .model(ModelName.GIGA_CHAT_MAX)
                    .input(List.of("Привет, как дела?", "Расскажи о себе"))
                    .build()));
        } catch (HttpClientException ex) {
            System.out.println(ex.statusCode() + " " + ex.bodyAsString());
        }
    }
}

Проверить баланс токенов

Метод доступен только при покупке пакетов токенов. Если вы оплачиваете работу с API по схеме pay-as-you-go, запрос вернет ошибку 403 Permission Denied.

from gigachat import GigaChat

with GigaChat(
    credentials="ключ_авторизации",
    scope="GIGACHAT_API_B2B",
    verify_ssl_certs=False,
) as client:
    balance = client.get_balance()
    for entry in balance.balance:
        print(f"{entry.usage}: {entry.value}")

import GigaChat from 'gigachat';

const giga = new GigaChat({
  credentials: 'ключ_авторизации',
  scope: 'GIGACHAT_API_B2B',
});

const balance = await giga.balance();
console.log(balance);

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

Примеры использования

Примеры использования библиотеки в репозитории

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

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

Начало работы﻿

Примеры работы с SDK﻿

Получить список доступных моделей﻿

Сгенерировать текст﻿

Потоковая генерация токенов﻿

Сгенерировать эмбеддинг﻿

Скачать сгенерированное изображение﻿

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

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

Получить список файлов﻿

Просмотр информации о файле﻿

Удаление файла﻿

Подсчитать количество токенов в запросе﻿

Проверить баланс токенов﻿