YandexGPT API на Python: отправляем первый запрос и собираем чат

YandexGPT можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. YandexGPT можно вызвать обычным HTTPS-запросом и увидеть весь контракт API: заголовки, modelUri, сообщения и usage. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

Новичок путает API-ключ, идентификатор каталога и адрес модели, а затем пытается искать ошибку только в тексте запроса. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте консольный чат с YandexGPT, историей последних реплик и выводом расхода токенов. Проверка: запрос возвращает ответ, usage отображается, а ошибка 401 или 403 объясняется без печати секрета.

Как устроен учебный проект YandexGPT

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

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

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией сервиса 21 октября 2026 года. Установите httpx, задайте YC_API_KEY и YC_FOLDER_ID. Начните с одного запроса без цикла. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

import os
import httpx

URL = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"
FOLDER = os.environ["YC_FOLDER_ID"]
HEADERS = {"Authorization": f"Api-Key {os.environ['YC_API_KEY']}"}
messages = [{"role": "system", "text": "Отвечай кратко и по-русски."}]

def ask(text: str) -> str:
    messages.append({"role": "user", "text": text})
    payload = {
        "modelUri": f"gpt://{FOLDER}/yandexgpt/latest",
        "completionOptions": {"stream": False, "temperature": 0.4, "maxTokens": 300},
        "messages": messages[-7:],
    }
    response = httpx.post(URL, headers=HEADERS, json=payload, timeout=60)
    response.raise_for_status()
    data = response.json()["result"]
    answer = data["alternatives"][0]["message"]["text"]
    print("tokens:", data.get("usage", {}))
    messages.append({"role": "assistant", "text": answer})
    return answer

print(ask("Объясни список Python в двух предложениях"))

Главная функция принимает явные аргументы и возвращает данные, которые можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

modelUri связывает запрос с каталогом и моделью, Authorization подтверждает доступ, а messages передаёт роли диалога. completionOptions управляет длиной и вариативностью ответа. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Секреты хранятся в переменных окружения и не попадают в исходники, журналы и скриншоты.

latest удобно для учебного примера, но рабочий продукт должен осознанно фиксировать модель и проверять изменения качества. Не используйте temperature как кнопку точности: это параметр вариативности. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверяем проект и добавляем свою функцию

Добавьте команды /reset и /usage, а сетевой вызов заверните в функцию с понятной обработкой 401, 403 и 429. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

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

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

Что запомнить и куда двигаться дальше

Для веб-приложения держите ключ только на сервере. Браузер должен обращаться к вашему backend, а не напрямую к облачному API. Для закрепления откройте в чате Gemini API, в статье про GigaChat и в локальном чат-боте Ollama.

Как изучить тему в Кодике

Сначала разберите формат данных и одну функцию, затем подключайте сеть, интерфейс или внешний сервис. Сначала восстановите главную функцию и проверьте её на трёх значениях.

Закрепите проект, переписав ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс Python.

Что получится в итоге

Финальный экран показывает результат, состояние запроса и понятное сообщение об ошибке без раскрытия секретов.