SDK для GigaChat API

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

GigaChat — это JS-библиотека для работы с REST API GigaChat. Она является частью GigaChain и входит в состав langchain-gigachat-js — партнерского пакета opensource-фреймворка LangChain .

Вот часть того, что она поддерживает:

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

Больше примеров работы с библиотекой gigachat — в репозитории .

Установка

npm install gigachat

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

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

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

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

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

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

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

Пример простого запроса на генерацию:

import GigaChat from 'gigachat';
import { Agent } from 'node:https';

const httpsAgent = new Agent({
  rejectUnauthorized: false, // Отключает проверку корневого сертификата
  // Читайте ниже как можно включить проверку сертификата НУЦ Минцифры
});

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

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

Способы авторизации

Существуют различные способы авторизации, помимо ключа авторизации.

const client = new GigaChat({
  credentials: 'креды',
  scope: 'GIGACHAT_API_PERS / GIGACHAT_API_B2B / GIGACHAT_API_CORP',
});

const client = new GigaChat({
  baseUrl: 'BASE URL апи',
  user: 'юзернейм',
  password: 'пароль',
});

import GigaChat from 'gigachat';
import { Agent } from 'node:https';
import fs from 'node:fs';

const httpsAgent = new Agent({
  ca: fs.readFileSync('certs/ca.pem'),
  cert: fs.readFileSync('certs/tls.pem'),
  key: fs.readFileSync('certs/tls.key'),
  passphrase: 'пароль от приватного ключа',
});

const client = new GigaChat({
  baseUrl: 'BASE URL апи',
  httpsAgent: httpsAgent,
});

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

Токен действителен в течение 30 минут.

const client = new GigaChat({
  baseUrl: 'BASE URL апи',
  accessToken: 'токен',
});

Предварительная авторизация

По умолчанию, библиотека GigaChat получает токен доступа при первом запросе к API.

Если вам нужно получить токен и авторизоваться до выполнения запроса, инициализируйте объект GigaChat и вызовите метод updateToken().

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

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

В таблице описаны параметры, которые можно передать при инициализации объекта GigaChat.

Часть из параметров можно задать с помощью соответствующих переменных окружения.

Параметр	Переменная окружения	Описание
credentials	GIGACHAT_CREDENTIALS	Ключ авторизации для обмена сообщениями с GigaChat API. Ключ авторизации содержит информацию о версии API, к которой выполняются запросы. Если вы используете версию API для ИП или юрлиц, укажите это явно в параметре scope
scope	GIGACHAT_SCOPE	Версия API, к которой будет выполнен запрос. По умолчанию запросы передаются в версию для физических лиц. Возможные значения: GIGACHAT_API_PERS — версия API для физических лиц; GIGACHAT_API_B2B — версия API для ИП и юрлиц при работе по предоплате. GIGACHAT_API_CORP — версия API для ИП и юрлиц при работе по постоплате.
model	GIGACHAT_MODEL	необязательный параметр, в котором можно явно задать модель GigaChat. Вы можете посмотреть список доступных моделей с помощью метода get_models(), который выполняет запрос GET /models. Стоимость запросов к разным моделям отличается. Подробную информацию о тарификации запросов к той или иной модели вы ищите в официальной документации
baseUrl	GIGACHAT_BASE_URL	Адрес API. По умолчанию запросы отправляются по адресу https://gigachat.devices.sberbank.ru/api/v1/, но если вы хотите использовать модели в раннем доступе, укажите адрес https://gigachat-preview.devices.sberbank.ru/api/v1
timeout	GIGACHAT_TIMEOUT	Таймаут (в секундах), который используется при подключении
httpsAgent		Настройки HTTPS, которые добавляются при подключении к серверу API (подключение по сертификату, отключение проверки корневого сертифаката и т.д). В браузере не поддерживается!
dangerouslyAllowBrowser		Флаг, включащий библиотеку в браузере. По умолчанию, данная библиотека в браузере не работает, так как так можно разоблачить ваш GigaChat токен.

Не работает в браузере

Работа в браузере

По умолчанию, при запуске в браузере библиотека возвращает Exception.

Кроме этого, при запуске в браузере не работают параметры, заданные в переменных окружения, и нельзя отключить проверку сертификатов НУЦ Минцифры.

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

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