GigaChat API: гайд для разработчика на Node

В прошлом году у нас на проекте встал вопрос — заменить часть функций OpenAI на российский LLM-API, чтобы не зависеть от валютных платежей и санкционных рисков. Мы попробовали YandexGPT и GigaChat, в итоге часть фич переехала на GigaChat. В этой статье — практический гайд, как подключиться, что подстерегает и какие нюансы есть в SDK.

С чего начать

Сначала нужно зарегистрироваться в Sber AI и получить ключ авторизации. Делается через личный кабинет в Studio: создаёшь проект, выбираешь тариф (есть Freemium для теста), генерируешь ключ. Ключ — это base64-строка, которая используется для получения access-токена.

Важно: GigaChat работает по двухступенчатой авторизации. Ты обмениваешь авторизационный ключ на короткоживущий access_token (30 минут), и уже им подписываешь запросы к модели.

Получаем токен

const RQ_UID = crypto.randomUUID();

async function getAccessToken(authKey: string): Promise<string> {
  const res = await fetch('https://ngw.devices.sberbank.ru:9443/api/v2/oauth', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${authKey}`,
      'RqUID': RQ_UID,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: 'scope=GIGACHAT_API_PERS',
  });
  if (!res.ok) throw new Error(`oauth failed: ${res.status}`);
  const json = await res.json();
  return json.access_token;
}

Scope бывает разным: GIGACHAT_API_PERS — для физлиц и тестовых проектов, GIGACHAT_API_B2B — для корпоративных. У нас на проде B2B, на дев — PERS.

SSL-сертификат

Это место, где у нас встал процесс на полдня. Sber использует свой корневой сертификат «Минцифры». На macOS и большинстве Linux-сборок его нет в системном хранилище, и Node ругается ошибкой UNABLE_TO_GET_ISSUER_CERT_LOCALLY.

Решение: скачиваем .crt с сайта Минцифры, кладём в проект и в Node прокидываем переменную NODE_EXTRA_CA_CERTS:

export NODE_EXTRA_CA_CERTS=./certs/russian_trusted_root_ca.crt
node app.mjs

В докер-образе мы добавили сертификат на этапе билда:

COPY certs/russian_trusted_root_ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

Запрос к модели

async function chat(token: string, messages: Array<{role: string; content: string}>) {
  const res = await fetch('https://gigachat.devices.sberbank.ru/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'GigaChat-Pro',
      messages,
      temperature: 0.3,
      max_tokens: 1024,
      stream: false,
    }),
  });
  return res.json();
}

Формат запроса OpenAI-совместимый — ровно тот же messages-массив с role/content. Это упрощает миграцию: если у тебя был код на OpenAI SDK, ты можешь переключиться сменой URL и заголовков, не переписывая бизнес-логику.

Что есть и чего нет

Есть: streaming через SSE, function calling, embeddings, генерация картинок (отдельной моделью).

Нет (на момент мая 2026): нативной поддержки vision на pro-моделях, нормального tool use с параллельными вызовами, кэширования промптов. Если у тебя сценарий с большими system-промптами и сотнями RPS, экономика будет другой, чем у Anthropic.

Лимиты и темп

Базовый тариф B2B даёт что-то около 60 RPS на токен и квоту по токенам в месяц. Если упираешься — пиши в поддержку, поднимают довольно быстро. Главное в коде — нормально обрабатывать 429-е ответы и делать ретраи с экспоненциальной задержкой.

async function chatWithRetry(token: string, messages: any, attempt = 0): Promise<any> {
  const res = await fetch(GIGACHAT_URL, { /* ... */ });
  if (res.status === 429 && attempt < 4) {
    const wait = 500 * Math.pow(2, attempt);
    await new Promise(r => setTimeout(r, wait));
    return chatWithRetry(token, messages, attempt + 1);
  }
  return res.json();
}

Кэширование токена

Access-токен живёт 30 минут. Не получай его на каждый запрос — это лишние круги к oauth и потенциальный 429 на самом oauth-сервере. Я кладу токен в Redis с TTL 25 минут, и обновляю фоновым воркером за 2 минуты до истечения.

Чего реально стоит ждать

Качество русского у GigaChat Pro в 2026 году ровное. Для контентных задач, типа суммаризации, классификации, генерации шаблонных ответов — спокойно работает. Для тяжёлых tool use, цепочек рассуждений и кода я бы пока не брал, для этого мы держим отдельную обвязку с OpenAI/Claude через прокси.

Если у тебя задача — добавить простой LLM-фичу в продукт, который должен работать в России без выхода во внешний интернет, GigaChat — рабочий выбор. Подключение в первый раз непростое из-за сертификата, но дальше всё стандартно. И главное — у тебя счёт в рублях, без мороки с международными платежами и резидентством.