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

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

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

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

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

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

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

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

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

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

1. Установите или подключите в проект подходящую библиотеку:

   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>

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

   from gigachat import GigaChat
   
   giga = GigaChat(
      credentials="ключ_авторизации",
      base_url="https://api.giga.chat/v1",
      scope="GIGACHAT_API_PERS",
   )

   import GigaChat from 'gigachat';
   
   const giga = new GigaChat({
     credentials: 'ключ_авторизации',
     scope: 'GIGACHAT_API_PERS',
     baseUrl: 'https://api.giga.chat/api/v1',
     model: 'GigaChat-2-Max',
   });

   public class CompletionExample {
   
       public static void main(String[] args) {
           GigaChatClient client = GigaChatClient.builder()
                   .apiUrl("https://api.giga.chat/v1")
                   .apiV2Url("https://api.giga.chat/v2")
                   .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(
    base_url="https://api.giga.chat/v1",
    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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
  model: 'GigaChat-2-Max',
});

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

public class ModelListExample {

    public static void main(String[] args) {
        GigaChatClient client = GigaChatClient.builder()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    credentials="ключ_авторизации",
    scope="GIGACHAT_API_PERS",
    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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
  model: 'GigaChat-2-Max',
});

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()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
  model: 'GigaChat-2-Max',
});

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()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    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()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
  model: 'GigaChat-2-Max',
});

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()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
});

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()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
});

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

public class AvailableFilesExample {

    public static void main(String[] args) {
        GigaChatClient client = GigaChatClient.builder()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    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(
    base_url="https://api.giga.chat/v1",
    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()
                .apiUrl("https://api.giga.chat/v1")
                .apiV2Url("https://api.giga.chat/v2")
                .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(
    base_url="https://api.giga.chat/v1",
    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: 'ключ_авторизации',
  baseUrl: 'https://api.giga.chat/api/v1',
  scope: 'GIGACHAT_API_B2B',
});

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

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

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

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

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

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

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

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

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

Примеры использования TS/JS SDK в репозитории