YandexGPT API: как получить ключ и отправить первый запрос

Чат с Алисой отвечает вам в окне браузера. Но чтобы нейросеть отвечала клиентам в Telegram, разбирала заявки или работала внутри вашего агента, то есть программы, которая сама отвечает клиентам и выполняет поручения, ей нужно получать вопросы от программы, а не от человека. Для этого у Яндекса есть YandexGPT API.

API — это канал, по которому программы обмениваются данными без человека, как окошко выдачи, куда кладут запрос и забирают ответ. Ниже по шагам, как получить доступ, как выглядит первый запрос к YandexGPT API и что делать, если он не прошёл. Все запросы и ошибки в статье получены в нашей проверке 9 октября 2026.

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

• Аккаунт Yandex Cloud с подключённой оплатой, в Яндексе это называют платёжным аккаунтом. Новым пользователям дают стартовый грант, то есть деньги на счёт для пробы, подробнее о нём в обзоре моделей YandexGPT.
• API-ключ. Это пароль, по которому Яндекс узнаёт вашу программу.
• Номер каталога. Каталог — это папка внутри Yandex Cloud, к которой привязаны нейросети и расходы. Его номер начинается с букв b1g.

Отправлять запросы можно из любой программы, текст запроса везде одинаковый. Ниже настройки показаны для конструктора n8n, в нём мы проводили проверку.

Шаг 1. Получите API-ключ

По документации Яндекса ключ создаётся прямо в интерфейсе Yandex AI Studio:

1. Откройте Yandex AI Studio и нажмите Создать API-ключ в правом верхнем углу.
2. При желании поменяйте описание ключа.
3. Выберите срок действия ключа.
4. Нажмите Создать.
5. Сохраните секретную часть ключа в надёжном месте.

Вместе с ключом Яндекс сам создаёт служебную учётную запись с минимальными правами для работы с нейросетями. Учтите: после закрытия окна Яндекс больше не покажет секретную часть ключа. Если вы её потеряли, создайте новый ключ.

Никогда не вставляйте ключ в текст сообщений, документы и схемы, которые видят другие люди. Храните его в разделе доступов программы, в n8n это раздел Credentials.

Шаг 2. Скопируйте номер каталога

Вверху экрана Yandex AI Studio написано название каталога. Наведите на него курсор и нажмите значок копирования: номер окажется в буфере обмена.

Шаг 3. Соберите запрос

Запрос к YandexGPT API — это сообщение, в котором три части:

• адрес, куда отправлять;
• заголовок с ключом, чтобы Яндекс понял, кто спрашивает;
• текст запроса: какая модель, что спросить и сколько текста максимум вернуть.

Адрес из документации Яндекса. Запросы по нему пишут в том же формате, что и для OpenAI, компании, которая делает ChatGPT, а этот формат понимают многие программы:

https://ai.api.cloud.yandex.net/v1/chat/completions

Работает и адрес https://llm.api.cloud.yandex.net/v1/chat/completions: в нашей проверке 9 октября 2026 оба адреса отвечали одинаково.

Заголовок с ключом по документации выглядит так:

Authorization: Api-Key ВАШ_КЛЮЧ

Текст запроса из нашей проверки. Вместо b1gXXXXXXXXXXXXXXXXX подставьте номер своего каталога:

json { "model": "gpt://b1gXXXXXXXXXXXXXXXXX/yandexgpt-lite/latest", "messages": [ {"role": "user", "content": "Скажи привет"} ], "max_tokens": 100 }

Сообщение с ролью user — это вопрос. Чтобы задать нейросети постоянную инструкцию, перед вопросом добавляют сообщение с ролью system, например {"role": "system", "content": "Отвечай коротко и вежливо."}. Поле max_tokens ограничивает длину ответа: 100 токенов хватит на несколько предложений. Токен — это кусочек слова в три-четыре буквы.

В этом запросе модель записана старым именем yandexgpt-lite, документация сейчас называет её yandexgpt-5-lite, и 9 октября 2026 работали оба имени. Как писать хорошую инструкцию, объяснено в статье про промпт для ИИ-агента.

Шаг 4. Посмотрите на ответ

В n8n ответ появляется в правой части окна блока HTTP Request после тестового запуска схемы. Вот главное из ответа, который мы получили:

json { "object": "chat.completion", "model": "gpt://b1gXXXXXXXXXXXXXXXXX/yandexgpt-lite/latest", "choices": [{ "message": {"role": "assistant", "content": "Привет! Чем я могу вам помочь?"}, "finish_reason": "stop" }], "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20} }

Ответ нейросети лежит в поле content. В поле usage указано, сколько токенов ушло на вопрос и на ответ: по ним считаются деньги.

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

В n8n запрос отправляет блок HTTP Request. Его настройки:

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

Как называются модели в запросе

Название модели в запросе всегда начинается с gpt://, затем номер каталога и короткое имя модели:

В нашей проверке модель отвечала и с окончанием /latest, и без него. Какую модель выбрать под задачу и сколько они стоят, разобрано в обзоре моделей Яндекса по ссылке выше, а чем они отличаются от нейросетей Сбера, показывает сравнение GigaChat и YandexGPT.

Умеет ли YandexGPT вызывать инструменты

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

Мы описали нейросети инструмент find_order, который ищет заказ по номеру, и спросили: «Где мой заказ 4512?». Alice AI LLM, Alice AI LLM Flash и YandexGPT Pro 5.1 вернули вызов инструмента с номером заказа 4512, а не ответили наугад. Значит, агента на этих моделях собрать можно. YandexGPT Lite из примеров выше мы на вызов инструментов не проверяли.

Если не работает

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

Если ответ обрывается на полуслове, увеличьте max_tokens: это потолок длины ответа в токенах.

Если Яндекс не принимает ключ, проверьте заголовок: перед ключом должно стоять слово Api-Key и пробел. Если в ответе есть слова folder ID, дело не в ключе, а в номере каталога, смотрите таблицу выше. И проверьте, что на платёжном аккаунте есть деньги или действует грант.