ym88659208ym87991671
SDK для GigaChat API | Документация для разработчиков

SDK для GigaChat API

Обновлено 3 октября 2025

Java-библиотека GigaChat для работы с REST API GigaChat.

Библиотека управляет авторизацией запросов и предоставляет все необходимые методы для работы с API. Кроме этого она поддерживает:

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

Примеры работы с библиотекой — в репозитории .

Требования

Для работы библиотеки установите Java версии 17 или выше.

Установка

Чтобы установить библиотеку, подключите ее в зависимости.

Gradle

implementation("chat.giga:gigachat-java:0.1.10")

Maven

<dependency>
<groupId>chat.giga</groupId>
<artifactId>gigachat-java</artifactId>
<version>0.1.10</version>
</dependency>

Быстрый старт

Для работы с библиотекой вам понадобится ключ авторизации API.

Чтобы получить ключ авторизации:

  1. Создайте проект GigaChat API в личном кабинете Studio.
  2. В интерфейсе проекта, в левой панели выберите раздел Настройки API.
  3. Нажмите кнопку Получить ключ.

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

Подробно о том, как создать проект GigaChat API — в официальной документации, в разделах Быстрый старт для физических лиц и Быстрый старт для ИП и юридических лиц.

Передайте полученный ключ авторизации в параметре authKey при инициализации объекта AuthClient.

Пример показывает как отправить простой запрос на генерацию с помощью библиотеки GigaChatClient:

//Укажите ключ авторизации, полученный в личном кабинете, в интерфейсе проекта GigaChat API
public class CompletionExample {

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

System.out.println(client.completions(CompletionRequest.builder()
.model(ModelName.GIGA_CHAT_MAX)
.message(ChatMessage.builder()
.content("Какие факторы влияют на стоимость страховки на дом?")
.role(Role.USER)
.build())
.build()));
}
}

Этот и другие примеры работы с библиотекой GigaChat — в репозитории .

Параметры объекта GigaChatClient

Для работы с GigaChat используется класс GigaChatClient, который предоставляет доступ ко всем необходимым методам работы с API.

Подробнее о методах и параметрах класса — в документации класса.

Способы аутентификации

Для аутентификации используется метод AuthClient.builder().

Методы AuthClientBuilder позволяют выполнить аутентификацию с помощью:

  • ключа авторизации;
  • токена доступа;
  • клиентского идентификатора (Client ID) и ключа (Client Secret);
  • TLS-сертификата;
  • имени пользователя и пароля.

Аутентификация с помощью ключа авторизации

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

Возможные значения:

  • GIGACHAT_API_PERS — версия API для физических лиц;
  • GIGACHAT_API_B2B — версия API для ИП и юрлиц при работе по предоплате.
  • GIGACHAT_API_CORP — версия API для ИП и юрлиц при работе по постоплате.

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

GigaChatClient client = GigaChatClient.builder()
.authClient(AuthClient.builder()
.withOAuth(OAuthBuilder.builder()
// Версия API
.scope(Scope.GIGACHAT_API_B2B)
.authKey("ключ_авторизации")
.build())
.build())
.build();

Подробно о том, как создать проект GigaChat API — в официальной документации, в разделах Быстрый старт для физических лиц и Быстрый старт для ИП и юридических лиц.

Аутентификация с помощью токена доступа

Токен доступа (access token) получается в обмен на ключ авторизации в запросе POST /api/v2/oauth.

Токен действует в течение 30 минут и содержит данные о версии API, к которой предоставляется доступ, поэтому ее не нужно указывать дополнительно.

GigaChatClient client = GigaChatClient.builder()
.authClient(AuthClient.builder()
.withProvidedTokenAuth("токен_доступа").build())
.build();

Аутентификация с помощью клиентского идентификатора и ключа

Как и при использовании ключа авторизации, при аутентификации с помощью Client ID и Client Secret нужно указывать версию API, к которой будут выполняться запросы.

GigaChatClient client = GigaChatClient.builder()
.authClient(AuthClient.builder()
.withOAuth(OAuthBuilder.builder()
.scope(Scope.GIGACHAT_API_B2B)
.clientId("test-client-id")
.clientSecret("test-scope")
.build())
.build())
.logRequests(true)
.logResponses(true)
.build();

Аутентификация с помощью имени пользователя и пароля

GigaChatClient client = GigaChatClient.builder()
.authClient(AuthClient.builder()
.withUserPassword(
UserPasswordAuthBuilder.builder()
.user("user")
.password("password")
.authApiUrl("https://api.ru/v1")
.scope(Scope.GIGACHAT_API_PERS)
.build()).build()
)
.build();

Аутентификация с помощью TLS-сертификата

GigaChatClient client = GigaChatClient.builder()
.authClient(AuthClient.builder()
.withCertificatesAuth(new JdkHttpClientBuilder()
.httpClientBuilder(HttpClient.newBuilder())
.ssl(SSL.builder()
.truststorePassword("password")
.trustStoreType("PKCS12")
.truststorePath("/Users/test/ssl/client_truststore.p12")
.keystorePassword("password")
.keystoreType("PKCS12")
.keystorePath("/Users/test/ssl/client_keystore.p12")
.build())
.build())
.build())
.build();

Установка корневого сертификата НУЦ Минцифры

Чтобы библиотека GigaChat могла передавать запросы в GigaChat API, вам нужно установить корневой сертификат НУЦ Минцифры.

Для этого перейдите в папку JAVA_HOME/bin и выполните в консоли, запущенной от имени администратора, команду:

keytool -importcert -storepass changeit -noprompt -alias rus_root_ca -cacerts -trustcacerts -file /<путь_к_файлу_сертификата>/russian_trusted_root_ca_pem.crt

При необходимости вы можете отключить проверку сертификатов. Для этого, создайте экземпляр GigaChatClient, с параметром verifySslCerts(false):

GigaChatClient client = GigaChatClient.builder()
// Отключение проверки сертификатов
.verifySslCerts(false)
.authClient(AuthClient.builder()
.withOAuth(OAuthBuilder.builder()
.scope(Scope.GIGACHAT_API_PERS)
.authKey("ключ_авторизации")
.build())
.build())
.build();

Отключение проверки сертификатов снижает безопасность обмена данными.

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

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

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