GigaChat API на Python: пример запроса

Запрос к GigaChat API на Python обычно состоит из токена доступа, HTTP-запроса, JSON-тела с сообщениями и обработки ответа. Токен нельзя хранить прямо в коде: положите его в переменную окружения и читайте через os.environ

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

Что понадобится

Установите библиотеку requests

pip install requests

Сохраните токен в переменную окружения

export GIGACHAT_TOKEN='ваш_токен'

$env:GIGACHAT_TOKEN = 'ваш_токен'

После этого Python сможет прочитать токен без записи секрета в файл со скриптом

Минимальный POST-запрос

import os
import requests

url = 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions'
token = os.environ['GIGACHAT_TOKEN']

payload = {
    'model': 'GigaChat',
    'messages': [
        {
            'role': 'user',
            'content': 'Объясни список в Python простыми словами'
        }
    ],
}

response = requests.post(
    url,
    headers={'Authorization': f'Bearer {token}'},
    json=payload,
    timeout=30,
)

response.raise_for_status()
data = response.json()

print(data)

В этом примере есть четыре важные части: адрес метода, заголовок Authorization, JSON с моделью и сообщением, проверка HTTP-статуса через raise_for_status()

timeout=30 нужен обязательно. Без таймаута скрипт может зависнуть, если сеть или API не отвечают

По этой теме полезно отдельно посмотреть Составьте еженедельное расписание занятий, чтобы расширить контекст и сравнить подходы

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы

Вынести запрос в функцию

Так код проще переиспользовать

import os
import requests

GIGACHAT_URL = 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions'

def ask_gigachat(prompt: str) -> dict:
    token = os.environ['GIGACHAT_TOKEN']

    payload = {
        'model': 'GigaChat',
        'messages': [
            {'role': 'user', 'content': prompt}
        ],
    }

    response = requests.post(
        GIGACHAT_URL,
        headers={'Authorization': f'Bearer {token}'},
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

answer = ask_gigachat('Составь план урока по циклам Python')
print(answer)

Функция получает текст запроса, собирает JSON, отправляет запрос и возвращает разобранный JSON-ответ

Достать текст ответа

У API-ответов обычно есть служебные поля. В чатовых API текст ответа часто лежит внутри первого элемента choices

def extract_text(data: dict) -> str:
    return data['choices'][0]['message']['content']

data = ask_gigachat('Напиши короткое приветствие')
text = extract_text(data)

print(text)

Если структура ответа изменилась или пришла ошибка, такой код может вызвать KeyError или IndexError. Для учебного примера это нормально, но в рабочем скрипте лучше сделать безопасную проверку

def extract_text_safe(data: dict) -> str:
    choices = data.get('choices') or []

    if not choices:
        return ''

    message = choices[0].get('message') or {}
    return message.get('content', '')

Обработка ошибок

Минимальная рабочая обработка ошибок может выглядеть так

import os
import requests

GIGACHAT_URL = 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions'

def ask_gigachat(prompt: str) -> str:
    token = os.environ['GIGACHAT_TOKEN']

    payload = {
        'model': 'GigaChat',
        'messages': [{'role': 'user', 'content': prompt}],
    }

    try:
        response = requests.post(
            GIGACHAT_URL,
            headers={'Authorization': f'Bearer {token}'},
            json=payload,
            timeout=30,
        )
        response.raise_for_status()
    except requests.exceptions.Timeout:
        return 'API не ответил за отведенное время'
    except requests.exceptions.HTTPError as error:
        return f'HTTP-ошибка: {error.response.status_code}'
    except requests.exceptions.RequestException as error:
        return f'Ошибка запроса: {error}'

    data = response.json()
    choices = data.get('choices') or []

    if not choices:
        return 'Ответ пришел без текста'

    return choices[0].get('message', {}).get('content', '')

print(ask_gigachat('Дай пример цикла for на Python'))

В реальном приложении лучше не возвращать текст ошибки как обычный ответ модели, а логировать ошибку и отдельно показывать пользователю понятное сообщение

Как передать несколько сообщений

Чатовые API обычно принимают массив сообщений. Можно передать системное сообщение и запрос пользователя

payload = {
    'model': 'GigaChat',
    'messages': [
        {'role': 'system', 'content': 'Отвечай кратко и по делу'},
        {'role': 'user', 'content': 'Что такое функция в Python?'},
    ],
}

Так можно задавать стиль ответа, контекст и последующие сообщения диалога. Не отправляйте в API секреты, персональные данные и внутренние документы без понимания правил безопасности вашего проекта

Частые ошибки

Хранить токен прямо в коде или коммитить его в репозиторий

Не ставить timeout

Не вызывать raise_for_status() и не замечать HTTP-ошибки

Считать, что структура JSON всегда будет одинаковой

Печатать весь ответ в production-логах вместе с чувствительными данными

Игнорировать лимиты, стоимость запросов и правила использования API

Практические задачи

Сохраните токен в переменную окружения и прочитайте его через os.environ

Напишите функцию ask_gigachat(prompt), которая возвращает только текст ответа

Добавьте обработку ошибки 401

Добавьте timeout и проверьте, что скрипт не зависает бесконечно

Передайте два сообщения: системное и пользовательское

Сделайте простой CLI-скрипт, который спрашивает текст у пользователя и отправляет его в API

Базовый запрос к GigaChat API на Python строится вокруг requests.post(), заголовка Authorization, JSON с сообщениями и обработки ответа. Токен храните вне кода, запросы отправляйте с таймаутом, HTTP-ошибки проверяйте через raise_for_status()

Для рабочего проекта вынесите запрос в функцию, аккуратно извлекайте текст из JSON и отдельно обрабатывайте сетевые ошибки, ошибки авторизации и пустые ответы