Как подключить YandexGPT API

YandexGPT нужен, когда модель должна отвечать из российского облака, с оплатой в рублях и закрывающими документами. Типичный случай: бот разбирает заявки, скрипт переписывает описания товаров, таблица сама раскладывает отзывы по темам. Код для такого подключения пишет Claude Code, а от тебя нужны ключ, идентификатор каталога и понимание, что куда класть.

Ниже весь путь от регистрации до первого ответа модели в терминале. Всё сверено с документацией Yandex AI Studio 26 сентября 2026 года, тексты ошибок сняты с живого сервиса в тот же день.

Что такое YandexGPT API в 2026 году?

Коротко: это доступ к моделям Яндекса из своего кода через Yandex AI Studio. Главный адрес теперь OpenAI-совместимый, поэтому подходит обычная библиотека openai.

Раньше всё называлось Yandex Foundation Models и жило внутри консоли Yandex Cloud. Сейчас модели собраны в Yandex AI Studio, документация переехала на aistudio.yandex.ru, и старые ссылки из статей 2023-2024 годов часто ведут на страницу 404. Если нашёл пример на Хабре и он не сходится с тем, что видишь в интерфейсе, дело скорее всего в переезде.

Для кода есть два входа. Новый - https://ai.api.cloud.yandex.net/v1, он повторяет формат OpenAI, и все примеры в быстром старте Яндекса написаны на нём. Старый - https://llm.api.cloud.yandex.net/foundationModels/v1/completion со своим форматом запроса, он по-прежнему описан в справочнике. Новый проект начинай с первого: агенту проще, потому что формат OpenAI он знает лучше любого другого.

Модель в запросе указывается строкой вместе с идентификатором каталога: gpt://<идентификатор_каталога>/yandexgpt-5-lite. Именно это место ломает больше всего первых запусков.

Сам код за тебя напишет агент, но ему нужна нормальная постановка задачи и правила проекта. Постановку задач и сборку рабочего окружения я объясняю в курсе ClaudeBase: видеоуроки для Claude Code и Codex плюс база материалов, которую агент подключает сам.

С какой точки ты стартуешь

• Агент не установлен. Поставь Claude Code по инструкции по установке и возвращайся сюда.
• Аккаунт в Yandex Cloud есть, ключа нет. Начинай с раздела про ключ.
• Ключ есть, запрос падает с ошибкой. Иди сразу в раздел «Частые ошибки», там тексты ответов сервера.
• Всё работает на старом адресе. Посмотри раздел про выбор модели: устаревшие имена моделей со временем отключают.

Что нужно до первого запроса к YandexGPT?

Список короткий, но без любого пункта запрос не пройдёт:

• аккаунт Яндекс ID, через него входишь в AI Studio;
• банковская карта для платёжного аккаунта Yandex Cloud;
• Python 3.10 или новее - такую версию требует быстрый старт Яндекса;
• папка проекта, в которой ты запускаешь Claude Code.

Платёжный аккаунт обязателен, даже если собираешься тратить копейки. В документации прямо сказано, что для работы с AI Studio он должен быть активным. Хорошая новость: при создании первого платёжного аккаунта с картой начисляется стартовый грант, и первые эксперименты идут за его счёт.

Как получить ключ YandexGPT API?

Путь через интерфейс AI Studio, консоль Yandex Cloud для этого не нужна.

1. Открой aistudio.yandex.cloud/platform и войди через Яндекс ID.
2. Создай организацию: название организации, название облака, кнопка «Открыть AI Studio». Каталог default появится сам.
3. Нажми «Привязать платежный аккаунт» в правом верхнем углу, добавь карту и проверь статус: нужен ACTIVE или TRIAL_ACTIVE.
4. Нажми «Создать API-ключ» там же, справа вверху. Выбери срок действия и нажми «Создать».
5. Сохрани идентификатор и секретное значение в менеджер паролей. После закрытия окна секрет больше не покажут, придётся делать новый ключ.

Вместе с ключом AI Studio создаёт сервисный аккаунт - отдельную учётную запись для программ, не для людей. Роли ему выдаются автоматически, среди них ai.editor, которой хватает для генерации текста. Руками назначать права не придётся.

Второе, что нужно, - идентификатор каталога. По справке Yandex Cloud он виден в консоли управления на дашборде каталога: сверху, под его именем, там же кнопка копирования. Идентификатор нужен тот, в котором создан сервисный аккаунт, то есть default, если ты ничего не менял.

Как спрятать ключ от git и от агента?

Ключ даёт право тратить деньги с твоего платёжного аккаунта. Поэтому три правила, до того как Claude Code напишет первую строку кода.

Первое - ключ хранится в .env в корне проекта, в самом коде его нет:

YANDEX_API_KEY=сюда_секретное_значение
YANDEX_FOLDER_ID=сюда_идентификатор_каталога

Второе - .env добавлен в .gitignore, иначе при первой публикации репозитория ключ уедет на GitHub.

Третье - агенту запрещено этот файл читать. Код может брать переменные из окружения, а самому Claude Code видеть значение незачем. В документации Anthropic есть готовый пример, который кладётся в ~/.claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

После сохранения проверь командой /status внутри Claude Code, что файл настроек подхватился. Как вообще устроены разрешения и файлы настроек, есть в разборе настройки Claude Code.

Чтобы агент не спрашивал каждый раз, где ключи и какую модель брать, запиши это в правила проекта: «ключи в .env, модель yandexgpt-5-lite, адрес ai.api.cloud.yandex.net/v1». Как вести такой файл, я подробно разбирал в материале про CLAUDE.md.

Как отправить первый запрос через Claude Code?

Открой терминал в папке проекта, запусти claude и дай задачу примерно такими словами:

Напиши скрипт first_request.py. Он берёт YANDEX_API_KEY и YANDEX_FOLDER_ID
из файла .env через python-dotenv, обращается к YandexGPT через библиотеку
openai по адресу https://ai.api.cloud.yandex.net/v1, модель
gpt://<каталог>/yandexgpt-5-lite, Responses API. Спрашивает у модели
«Придумай три заголовка для объявления о продаже велосипеда» и печатает ответ.
Сам файл .env не открывай. Поставь нужные библиотеки и запусти скрипт.

Агент поставит openai и python-dotenv через pip и соберёт примерно такой код. Он повторяет пример из документации Яндекса, только ключ берётся не из текста скрипта:

import os
import openai
from dotenv import load_dotenv

load_dotenv()

folder = os.environ["YANDEX_FOLDER_ID"]

client = openai.OpenAI(
    api_key=os.environ["YANDEX_API_KEY"],
    base_url="https://ai.api.cloud.yandex.net/v1",
    project=folder,
)

response = client.responses.create(
    model=f"gpt://{folder}/yandexgpt-5-lite",
    input="Придумай три заголовка для объявления о продаже велосипеда",
    temperature=0.3,
    max_output_tokens=500,
)

print(response.output[0].content[0].text)

Параметр project передаёт идентификатор каталога, temperature от 0 до 1 отвечает за разнообразие ответа, max_output_tokens ограничивает его длину. Для рабочих задач вроде разбора заявок температуру держат низкой, чтобы ответы были предсказуемыми.

Если в терминале появился текст с тремя заголовками - подключение работает. Дальше скрипт можно превращать во что угодно: функцию для бота, обработчик таблицы, ночную задачу. Например, подключить его к боту для MAX на Python или отдавать ему на разбор объявления, которые собрал свой парсер Авито. Любую доработку тоже формулируй агенту словами и проверяй запуском.

Перед тем как пускать скрипт на реальные данные, попроси агента о трёх вещах. Таймаут на запрос, чтобы программа не висела вечно, если сервис задумался. Понятное сообщение при ошибке вместо простыни из библиотеки. И запись в файл, сколько запросов ушло за прогон, - так проще сверить расход с биллингом. Это десять минут работы агента, а экономит вечер разбирательств, когда ночная задача утром оказывается пустой.

Проверить ключ без Python можно одной командой из документации. Переменные сначала задаются в терминале через export:

curl --request POST https://ai.api.cloud.yandex.net/v1/responses \
  --header "Authorization: Api-Key ${YANDEX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"model": "gpt://'"${YANDEX_FOLDER_ID}"'/yandexgpt-5-lite", "input": "Привет"}'

Я сам плачу за подписки на нейросети картой для подписок «Плати по миру»: выпускается за пару минут, пополняется рублями через СБП. Оформить карту

Какую модель YandexGPT выбрать?

В AI Studio доступны не только модели Яндекса, но для задачи «YandexGPT в моём коде» выбор обычно из четырёх. Цены - синхронный режим, за 1000 токенов с НДС, по странице тарификации на 26 сентября 2026 года:

Начинай с Lite: на коротких задачах разницу часто не видно. При этом стоит она вчетверо меньше Pro 5.1. Если нужен длинный документ целиком, смотри на Alice AI LLM с окном 128 тысяч токенов - её, кстати, быстрый старт Яндекса и использует в своём примере.

Платишь за токены с обеих сторон: и за то, что отправил, и за то, что модель написала. Длинная инструкция, которую скрипт прикладывает к каждому запросу, тоже считается. Посчитать токены заранее можно методом токенизации в API, и по странице тарификации он не тарифицируется.

Старые строки yandexgpt/latest и yandexgpt/rc пока работают и ведут на Pro 5 и Pro 5.1, но Яндекс советует писать модель явно. Когда версию выводят из эксплуатации, запросы на её адрес начинают возвращать ошибку, автоматического переключения нет.

Выбор модели - часть большой темы: что отдавать дешёвой модели, что дорогой, и когда вообще брать другого провайдера. В курсе ClaudeBase на это отвечают два урока - про подбор модели под задачу и про то, как устроены контекст и лимиты: почему длинный запрос стоит дороже и отвечает хуже.

Старый адрес или OpenAI-совместимый?

Если у тебя уже есть код на foundationModels/v1/completion, переписывать его ради переписывания не нужно. Отличия в формате: в старом API модель передаётся полем modelUri, сообщения - массивом messages, а настройки лежат в completionOptions. Новый адрес принимает тот же формат, что и OpenAI, поэтому любой пример, написанный под GPT, переносится заменой адреса, ключа и строки модели.

Для новых проектов я беру совместимый адрес. Формат OpenAI встречается в примерах повсюду, и агенту проще писать под него. Если всё же остаёшься на старом API, дай Claude Code ссылку на справочник TextGeneration.Completion, чтобы он сверял поля с документацией, а не вспоминал их.

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

Первые два текста ниже - настоящие ответы сервера, полученные при написании статьи.

UNAUTHENTICATED: Unknown api key

Код ответа 401. Сервис не узнал ключ: в переменную попало не то значение, ключ удалён или истёк срок, выбранный при создании. Частая причина - вставлен идентификатор ключа вместо секретного значения. Их два, и в запрос идёт секрет.

Authorization header is missing

Код 400. Заголовка авторизации нет вообще. В Python так бывает, когда переменная YANDEX_API_KEY не загрузилась из .env: файл оказался в другой папке или скрипт запущен из другой директории. Попроси агента вывести в терминал, найдена ли переменная, но без печати её значения.

400 Bad Request после того, как всё работало

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

ModuleNotFoundError: No module named 'openai'

Библиотека стоит не в том Python, которым запускается скрипт. Обычно виновато виртуальное окружение: его создали, но не активировали. Скажи агенту: «поставь зависимости в то окружение, из которого запускается скрипт, и покажи команду запуска».

Запросы начинают отваливаться при параллельной работе

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

Чек-лист подключения YandexGPT

• Платёжный аккаунт в статусе ACTIVE или TRIAL_ACTIVE.
• Секрет API-ключа есть в менеджере паролей.
• .env лежит в корне проекта и прописан в .gitignore.
• В настройках Claude Code есть правила Read(./.env) и Read(./.env.*) в разделе deny.
• Модель указана явно: gpt://<каталог>/yandexgpt-5-lite или другая из таблицы.
• Первый запрос вернул текст в терминале.

Что дальше после первого ответа

Когда первый ответ получен, остаётся встроить модель в сам продукт: бота, таблицу, обработку заявок. Каждую такую доработку ставь агенту отдельной задачей с понятной проверкой результата. Если сомневаешься, какого агента под это брать, посмотри сравнение Codex и Claude Code. Словом промпт называют и то, что ты пишешь агенту, и то, что твой скрипт отправляет YandexGPT - это две разные задачи, и вторую тоже стоит формулировать аккуратно.

Как ставить агенту такие задачи, настраивать правила проекта и не терять контекст на длинной работе, показано в видеоуроках ClaudeBase. К ним прилагается база материалов: Claude Code и Codex подключают её по MCP и дальше пользуются ею без подсказок.