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

API GigaChat устроено в стиле OpenAI: основной эндпоинт - /chat/completions, есть /embeddings. Работа в два шага: сначала получаем временный токен, потом им же шлём запросы к модели.

Шаг 1. Получить access_token

Постоянный Authorization key из кабинета обмениваем на временный access_token через OAuth-запрос к Сберу. Указываем scope GIGACHAT_API_PERS (персональный доступ). Токен живёт около 30 минут - после этого запрашиваем заново.

curl -X POST https://ngw.devices.sberbank.ru:9443/api/v2/oauth \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -H "RqUID: $(uuidgen)" \
  -H "Authorization: Basic <AUTHORIZATION_KEY>" \
  -d "scope=GIGACHAT_API_PERS"

В ответе придёт JSON с полем access_token и временем жизни. Дальше используем этот токен как Bearer.

Шаг 2. Запрос к /chat/completions

Передаём модель и массив messages (роли system, user, assistant - как в OpenAI).

curl -X POST https://gigachat.devices.sberbank.ru/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "model": "GigaChat",
    "messages": [
      {"role": "system", "content": "Отвечай кратко и по-русски."},
      {"role": "user", "content": "Объясни, что такое эмбеддинги."}
    ]
  }'

То же на Python

Удобно завести функцию получения токена и переиспользовать его, пока он не протух (около 30 минут), а потом обновлять.

import os
import uuid
import requests

AUTH_KEY = os.environ["GIGACHAT_AUTH_KEY"]  # ключ авторизации из кабинета


def get_token() -> str:
    resp = requests.post(
        "https://ngw.devices.sberbank.ru:9443/api/v2/oauth",
        headers={
            "Authorization": f"Basic {AUTH_KEY}",
            "RqUID": str(uuid.uuid4()),
            "Content-Type": "application/x-www-form-urlencoded",
        },
        data={"scope": "GIGACHAT_API_PERS"},
        verify="russian_trusted_root_ca.cer",  # сертификат НУЦ Минцифры
    )
    resp.raise_for_status()
    return resp.json()["access_token"]


def ask(token: str, prompt: str) -> str:
    resp = requests.post(
        "https://gigachat.devices.sberbank.ru/api/v1/chat/completions",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "model": "GigaChat",
            "messages": [{"role": "user", "content": prompt}],
        },
        verify="russian_trusted_root_ca.cer",
    )
    resp.raise_for_status()
    return resp.json()["choices"][0]["message"]["content"]


token = get_token()
print(ask(token, "Напиши короткое поздравление с днём рождения."))

Эмбеддинги и картинки

• Эмбеддинги. Отдельный эндпоинт /embeddings возвращает векторное представление текста. Используется для поиска по смыслу и RAG: считаете векторы для документов и для запроса, сравниваете близость.
• Картинки. Генерация изображений идёт через модель Kandinsky: GigaChat вызывает её как функцию при подходящем запросе, в ответе приходит ссылка или идентификатор сгенерированного изображения.