Развернуть

JS/TS SDK для GigaChat API

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

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

Библиотека поддерживает:

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

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

Установка

npm install gigachat

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

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

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

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

В открывшемся окне скопируйте и сохраните значение поля 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-2-Pro',
  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: 'адрес API',
  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: 'адрес API',
  httpsAgent: httpsAgent,
});

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

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

const client = new GigaChat({
  accessToken: 'ваш access token',
});

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

Потоковая передача токенов

Получение токенов по мере их генерации:

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-Pro',
    httpsAgent: httpsAgent,
  });
  for await (const chunk of client.stream('Напиши отчет на тему ипотечного кризиса')) {
    process.stdout.write(chunk.choices[0]?.delta.content || '');
  }
}

main();

Потоковая передача с подпиской на события

Для обработки потока токенов с помощью подписки на события используйте метод stream_readable():

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });
  const readable = await client.stream_readable('Напиши сочинение про слона');
  readable.on('chunk', (chunk) => {
    process.stdout.write(chunk.choices[0]?.delta.content || '');
  });
}

main();

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

Для генерации изображений передайте function_call: 'auto' вместе с соответствующим запросом:

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });
  const resp = await client.chat({
    messages: [
      {
        role: 'user',
        content: 'Сгенерируй изображение котика',
      },
    ],
    function_call: 'auto',
  });
  const detectedImage = detectImage(resp.choices[0]?.message.content ?? '');
  if (detectedImage && detectedImage.uuid) {
    const image = await client.getImage(detectedImage.uuid);
    fs.writeFile('image.jpg', image.content, 'binary', function (err) {
      if (err) throw err;
      console.log(`Сохранение изображения: ${path.resolve(__dirname, './image.jpg')}`);
    });
  }
}

main();

Распознавание изображений

Чтобы модель описала изображение:

Загрузите изображение в хранилище.
Передайте идентификатор изображения в массиве attschments вместе с соответствующим запросом.

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-Pro',
    httpsAgent: httpsAgent,
  });
  const filePath = path.resolve(__dirname, '../media/cat.jpg');
  const buffer = fs.readFileSync(filePath);
  const file = new File([buffer], 'image.jpg', { type: 'image/jpeg' });
  const uploadedFile = await client.uploadFile(file);

  const response = await client.chat({
    messages: [
      {
        role: 'user',
        content: 'Какой окрас у котенка на фото?',
        attachments: [uploadedFile.id],
      },
    ],
    temperature: 0.1,
  });
  console.log(response.choices[0]?.message.content);
}

main();

Эмбеддинги

Для получения векторного представления текста используйте метод embeddings():

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    httpsAgent: httpsAgent,
  });
  const response = await client.embeddings(['Слова слова слова']);
  console.log(response.data);
}

main();

Пакетный режим (чат)

Пакетный режим подходит для асинхронной обработки большого объема запросов:

import GigaChat from 'gigachat';
import { Agent } from 'node:https';
import { BATCH_FILE_STATUS, BatchRequest, ChatCompletion } from 'gigachat/interfaces';

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

const taskList: Record<string, string> = {
  '1': '1 + 3',
  '2': '8 - 16',
  '3': '12 * 2',
};

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });

  const chats: BatchRequest[] = Object.keys(taskList).map((key) => ({
    id: key,
    request: {
      messages: [
        {
          role: 'user',
          content: `Вычисли сколько будет ${taskList[key]}? Ответь числом`,
        },
      ],
    },
  }));

  const batch = await client.chatsBatch(chats);
  console.log(`Создан пакет, id: ${batch.id}, запросов: ${batch.request_counts.total}`);

  // Ожидание завершения
  let fileId = '';
  let isPolling = true;
  while (isPolling) {
    const batchStatus = await client.getBatchStatus(batch.id);
    if (batchStatus.status === BATCH_FILE_STATUS.completed && batchStatus.output_file_id) {
      isPolling = false;
      fileId = batchStatus.output_file_id;
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }

  // Обработка результата
  const batchFile = await client.getBatch<ChatCompletion>(fileId);
  batchFile.content.forEach((chat) => {
    console.log(`${taskList[chat.id]} = ${chat.result.choices[0]?.message.content}`);
  });
}

main();

Пакетный режим (эмбеддинги)

Для создания векторного представления текста в пакетном режиме укажите подходящую модель и используйте метод embeddingsBatch():

import GigaChat from 'gigachat';
import { Agent } from 'node:https';
import { BATCH_FILE_STATUS, BatchRequest, Embeddings } from 'gigachat/interfaces';

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    httpsAgent: httpsAgent,
  });

  const request: BatchRequest[] = [
    { id: '111', request: { input: ['Слова слова слова'], model: 'Embeddings' } },
    { id: '222', request: { input: ['Еще слова'], model: 'Embeddings' } },
  ];

  const batch = await client.embeddingsBatch(request);
  console.log(`Создан пакет, id: ${batch.id}, запросов: ${batch.request_counts.total}`);

  let fileId = '';
  let isPolling = true;
  while (isPolling) {
    const batchStatus = await client.getBatchStatus(batch.id);
    if (batchStatus.status === BATCH_FILE_STATUS.completed && batchStatus.output_file_id) {
      isPolling = false;
      fileId = batchStatus.output_file_id;
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }

  const batchFile = await client.getBatch<Embeddings>(fileId);
  batchFile.content.map(console.log);
}

main();

Подсчет токенов

Для подсчета оценки количества токенов в запросе используйте метод tokensCount():

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });
  const resp = await client.tokensCount(['Привет, как дела?', 'Как дела, как дела']);
  console.log(resp);
}

main();

Список моделей

Для получения списка моделей используйте метод getModels():

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });
  console.log(await client.getModels());
}

main();

Баланс токенов

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

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });
  console.log(await client.balance());
}

main();

Проверка текста на ИИ

Проверка доступна только юридическим лицам, которые работают по схеме оплаты pay-as-you-go.

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

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

async function main() {
  const client = new GigaChat({
    timeout: 600,
    model: 'GigaChat-2-Pro',
    httpsAgent: httpsAgent,
  });
  const result = await client.aiCheck('Пример текста для проверки');
  console.log(result);
}

main();

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

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

Параметр	Переменная окружения	Описание
`credentials`	`GIGACHAT_CREDENTIALS`	Ключ авторизации, полученный в личном кабинете Studio.
`scope`	`GIGACHAT_SCOPE`	Версия GigaChat API, к которой будут выполняться запросы. По умолчанию запросы передаются в версию для физических лиц. Возможные значения: `GIGACHAT_API_PERS` — версия API для физических лиц; `GIGACHAT_API_B2B` — версия API для ИП и юрлиц при работе по предоплате; `GIGACHAT_API_CORP` — версия API для ИП и юрлиц при работе по постоплате.
`user`		Имя пользователя для аутентификации по логину и паролю
`password`		Пароль для аутентификации по логину и паролю
`accessToken`		Токен доступа, полученный в обмен на ключ авторизации
`model`	`GIGACHAT_MODEL`	Необязательный параметр, в котором можно явно задать модель GigaChat. Посмотреть список доступных моделей можно с помощью метода `getModels()`, который выполняет запрос `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`		Флаг, включающий библиотеку в браузере. По умолчанию библиотека в браузере не работает, так как это может раскрыть ваш токен API.

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

GIGACHAT_CREDENTIALS — ключ авторизации;
GIGACHAT_SCOPE — версия API: GIGACHAT_API_PERS, GIGACHAT_API_B2B, GIGACHAT_API_CORP
GIGACHAT_BASE_URL — адрес API;
GIGACHAT_MODEL — идентификатор модели;
GIGACHAT_TIMEOUT — тайм-аут в секундах.

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

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

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

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

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

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

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

Установка﻿

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

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

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

Потоковая передача токенов﻿

Потоковая передача с подпиской на события﻿

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

Распознавание изображений﻿

Эмбеддинги﻿

Пакетный режим (чат)﻿

Пакетный режим (эмбеддинги)﻿

Подсчет токенов﻿

Список моделей﻿

Баланс токенов﻿

Проверка текста на ИИ﻿

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

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