Гайды

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

8 октября 2026 · 15 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 8 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.

YandexGPT API — это доступ к генеративным моделям Yandex AI Studio через HTTP. Ключ создаётся в интерфейсе AI Studio в несколько шагов, вместе с ним автоматически появляется сервисный аккаунт. Первый запрос к модели yandexgpt-lite отправляется методом POST на https://ai.api.cloud.yandex.net/v1/responses с заголовком Authorization: Api-Key. Ниже — порядок действий по официальной документации AI Studio. Мы скачали страницы сохранённого топ-10 Яндекса по запросу «yandexgpt api»: текст отдали 8 из 10.

Собственный прогон по сохранённому топ-10 Яндекса по запросу «yandexgpt api»: текст отдали 8 из 10 страниц, медиана объёма читаемого текста топа — 2792 слова, метку 2026 года несут 7 из 8 прочитанных страниц.

Что именно использует пример

Документация AI Studio описывает два слоя доступа к текстовым моделям. Первый — Responses API, совместимый с форматом OpenAI, второй — нативный API генерации текста. Пример базового запроса в руководстве «Отправить базовый запрос с помощью Responses API» построен на Responses API: базовый URL https://ai.api.cloud.yandex.net/v1, метод POST /responses, модель задаётся строкой вида gpt://<идентификатор_каталога>/<имя_модели>.

В руководстве «Отправить базовый запрос с помощью Responses API» документация приводит модель yandexgpt-lite и полный URI gpt://{YANDEX_FOLDER_ID}/{YANDEX_MODEL}. Там же указано, что для примера нужен сервисный аккаунт с ролью ai.languageModels.user и API-ключ с областью действия yc.ai.foundationModels.execute, и что ключ, создаваемый в AI Studio, имеет такие разрешения.

Важно не смешивать два формата. Тело запроса Responses API содержит поля model, input, temperature, max_output_tokens. Нативный API генерации текста использует другую структуру тела. Смешение форматов может привести к ошибке; изучите фактический ответ сервера.

Создание ключа и сервисного аккаунта

Ключ создаётся в интерфейсе AI Studio. По документации «Как создать API-ключ» порядок такой:

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

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

Для создания ключа пользователю нужна роль resource-manager.admin на каталог, в котором создаётся ключ. Это указано в примечании к инструкции.

Вместе с ключом сервис автоматически создаёт сервисный аккаунт с минимально необходимыми ролями. Среди них ai.editor — доступ к Yandex Translate, Yandex Vision OCR, Yandex SpeechKit и Yandex AI Studio. Область действия ключа включает yc.ai.languageModels.execute — доступ к генерации текста с помощью моделей Model Gallery.

Три разных идентификатора

В примерах фигурируют три сущности, которые легко перепутать.

Секрет ключа идёт в заголовок Authorization: Api-Key. Идентификатор каталога подставляется в URI модели и в заголовок x-folder-id. Идентификатор ключа в запросе не участвует — он нужен, чтобы различать ключи в списке.

Каталог — пространство, в котором содержатся ресурсы Yandex Cloud. Документация «Начало работы» поясняет: чтобы получить идентификатор, наведите указатель на название каталога в верхней части экрана AI Studio и нажмите — значение скопируется в буфер обмена.

Платежный аккаунт и доступность

Для работы с AI Studio нужен активный платежный аккаунт, привязанный к облаку. Документация «Начало работы» указывает: при создании первого платежного аккаунта с привязанной банковской картой начисляется стартовый грант. Статус аккаунта должен быть ACTIVE или TRIAL_ACTIVE.

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

Доступность сервиса из России в проверенных страницах отдельно не описана. Вход выполняется через личный аккаунт на Яндексе (Яндекс ID).

Настройка окружения

Документация «Начало работы» приводит варианты для Python, Node.js, cURL, Go и AI SDK. Для Python указана версия 3.10 или выше. Опционально предлагается библиотека venv для изолированных окружений.

Для варианта на стандартной библиотеке Python сторонние пакеты не нужны. Достаточно модулей urllib.request и json, которые входят в стандартную поставку. Это удобно, когда не хочется ставить SDK ради одного запроса.

Переменные окружения задаются так:

export YANDEX_FOLDER_ID='<идентификатор_каталога>'
export YANDEX_API_KEY='<значение_API-ключа>'

Проверить, что переменные видны процессу, можно без отправки запроса:

python3 -c "import os; print(bool(os.environ.get('YANDEX_FOLDER_ID')), bool(os.environ.get('YANDEX_API_KEY')))"

Команда печатает два значения True или False — присутствие переменных. Значения ключей она не выводит.

Первый запрос к yandexgpt-lite

Ниже — редакционная реализация на стандартной библиотеке Python по форме Responses API. Платный запрос не выполнялся. Сохраните код в файл hello_yandex.py, затем запустите python3 hello_yandex.py после настройки окружения.

import json
import os
import urllib.request

folder_id = os.environ["YANDEX_FOLDER_ID"]
api_key = os.environ["YANDEX_API_KEY"]
model = f"gpt://{folder_id}/yandexgpt-lite"

body = {
    "model": model,
    "input": "Придумай 3 необычные идеи для стартапа в сфере путешествий.",
    "temperature": 0.8,
    "max_output_tokens": 1500,
}

request = urllib.request. Request(
    "https://ai.api.cloud.yandex.net/v1/responses",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Api-Key {api_key}",
        "Content-Type": "application/json",
        "x-folder-id": folder_id,
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    payload = json.loads(response.read().decode("utf-8"))

print(payload["output"][0]["content"][0]["text"])

Тот же запрос через cURL:

curl \
--request POST https://ai.api.cloud.yandex.net/v1/responses \
--header "Authorization: Api-Key ${YANDEX_API_KEY}" \
--header "Content-Type: application/json" \
--header "x-folder-id: ${YANDEX_FOLDER_ID}" \
--data '{
"model": "gpt://'"${YANDEX_FOLDER_ID}"'/yandexgpt-lite",
"temperature": 0.8,
"max_output_tokens": 1500,
"input": "Придумай 3 необычные идеи для стартапа в сфере путешествий."
}'

В обоих вариантах yandexgpt-lite — имя модели, а gpt:// — схема URI. Подставьте свой идентификатор каталога вместо переменной. Сверьте каталог в URI с каталогом, к которому у сервисного аккаунта есть необходимые права.

Чтение ответа и контроль расхода

Ответ Responses API — JSON. Текст модели лежит по пути output[0].content[0].text. В примере ответа из документации видно, что элемент content содержит объект с полями annotations, text, type, logprobs, valid. Поле type имеет значение output_text.

Параметры запроса влияют на расход:

• temperature — температура генерации в диапазоне от 0 до 1. Чем выше значение, тем более разнообразными и творческими будут ответы модели.
• max_output_tokens — максимальное количество токенов в ответе модели.

max_output_tokens ограничивает верхнюю границу ответа. Это не гарантия, что модель израсходует ровно столько: она может остановиться раньше. Контроль расхода строится на двух вещах — на разумном значении max_output_tokens и на учёте фактического объёма ответов.

Сохраняйте ответы в локальные файлы. Так проще сверять объём и повторять разбор без нового запроса:

with open("response.json", "w", encoding="utf-8") as f:
    json.dump(payload, f, ensure_ascii=False, indent=2)

Файл с ответом может содержать чувствительные данные. Храните его там, где доступ ограничен, и не выкладывайте в публичные репозитории.

Три варианта промпта

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

Промпт, чтобы получить краткое описание продукта:

Опиши продукт [название] в трёх предложениях. Аудитория: [кто]. Тон: [спокойный/деловой]. Без рекламных эпитетов.

Промпт, чтобы получить список идей:

Предложи несколько идей для [тема]. Для каждой идеи укажи суть в одном предложении и главный риск. Формат: нумерованный список.

Промпт, чтобы переписать текст:

Перепиши текст ниже в [стиль]. Сохрани факты и числа. Не добавляй новых утверждений.

Текст:
[вставьте текст]

Квадратные скобки — места для подстановки. Меняйте их под свою задачу, остальную структуру можно оставить.

Редакционная офлайн-проверка

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

Такая проверка показывает, что запрос собран по документации. Она не показывает, что запрос выполнится: сеть, права ключа и состояние сервиса остаются за пределами офлайн-проверки. Фиксируйте фактический результат попытки.

Если ответа нет, проверяйте по порядку: подставлен ли реальный идентификатор каталога, тот ли ключ в переменной, не смешаны ли поля Responses API с нативным форматом. Документация по жизненному циклу моделей отмечает: запросы по устаревшему URI возвращают ошибку 400 Bad Request, автоматического переключения между версиями нет.

Учебное чтение JSON без обращения к API

Путь к тексту из официального примера можно разобрать локально на искусственном словаре. Ниже данные созданы редакцией специально для упражнения. Это не ответ YandexGPT, не журнал платного вызова и не доказательство доступа к сервису. Проверяется только наша функция чтения вложенных полей. Редакция выполнила этот локальный пример: непустая строка вернулась как текст, пустые списки и значение None дали None. Проверка не измеряет качество модели.

Сохраните пример в read_fixture.py и выполните python3 read_fixture.py. Для этого файла ключ и каталог не нужны: в коде нет отправки HTTP-запроса. Учебная строка помогает отличить содержимое первого текстового поля от служебной оболочки. После успешного упражнения вернитесь к отдельному файлу запроса; не превращайте искусственный словарь в якобы полученный ответ сервера.

def first_text(payload):
    output = payload.get("output")
    if not isinstance(output, list) or not output or not isinstance(output[0], dict):
        return None
    content = output[0].get("content")
    if not isinstance(content, list) or not content or not isinstance(content[0], dict):
        return None
    text = content[0].get("text")
    return text if isinstance(text, str) else None

fixture = {"output": [{"content": [{"text": "Учебный текст редакции"}]}]}
assert first_text(fixture) == "Учебный текст редакции"
assert first_text({"output": []}) is None
assert first_text({"output": [{"content": []}]}) is None
assert first_text({"output": [{"content": [{"text": None}]}]}) is None
print(first_text(fixture))

Функция намеренно ограничена первым элементом и первым текстовым полем. Она не перечисляет весь ответ и не заменяет официальную схему Responses API. В реальном JSON могут быть другие элементы; изучайте сохранённый ответ полностью, прежде чем выбирать правила обработки для своего приложения. None означает только отсутствие подходящей строки по правилам этой учебной функции. Из него нельзя вывести причину сбоя модели, отсутствие прав или состояние сети.

Для самостоятельной проверки поменяйте учебную строку и убедитесь, что вывод изменился вслед за ней. Затем оставьте пустой список output: функция должна вернуть None. Верните первый элемент и удалите его content: результат тоже будет None. Эти действия проверяют ветви вашей локальной программы. Если собственная правка перестала проходить проверку, сравните её с сохранённой версией функции. Обращение к платному API для поиска такой ошибки не требуется.

Карточка сборки первого запроса

Перед настоящим запуском подготовьте короткую карточку запроса. Запишите выбранный API, адрес, метод и имя модели. Рядом отметьте, откуда взят идентификатор каталога. Для секретного значения сохраняйте только место хранения, например имя переменной окружения; содержимое ключа в карточку не вставляйте. Так вы сможете сверить части запроса, не раскрывая секрет в обсуждении ошибки.

Проверьте URI модели после подстановки каталога. В статье используется конкретный документированный пример yandexgpt-lite. Если вы изменяете модель, сначала найдите её актуальный URI и доступный API в официальном каталоге. Похожее название в стороннем обзоре не устанавливает адрес вызова. Сохраните ссылку на описание выбранной модели рядом с карточкой и отмечайте изменение, если переключаете маршрут.

Затем проверьте содержимое input. Для учебного запроса достаточно короткой заметки без конфиденциальных данных. Например: «Перепиши объявление: встреча клуба перенесена к северным воротам, время осталось прежним, книги для обмена принимаются на месте. Не добавляй дату, часы и фамилии». Это редакционная инструкция; ответ YandexGPT по ней не получен. После собственной попытки сверяйте место встречи, неизменное время и возможность принести книги. Новый час или выдуманная дата означают расхождение с входом.

Отдельно отметьте разрешённые действия программы. Пример здесь только отправляет запрос и читает ответ. Если дальше вы хотите автоматически публиковать текст, менять документы или пересылать сообщение, понадобится самостоятельная процедура принятия результата. Успех чтения JSON не утверждает правильность фактов и не согласует публикацию. Для первого проекта удобнее сохранить текст локально и проверить его глазами.

Как читать результат собственной попытки

После запуска разделите запись на технический результат и содержание ответа. Техническая часть описывает, получено ли тело ответа и удалось ли разобрать JSON. Содержательная проверка сравнивает текст модели с вашим исходником. Эти проверки отвечают на разные вопросы. Валидный JSON может содержать неподходящее объявление; хороший текст в консоли ещё не показывает, какие условия расхода действуют для аккаунта.

Если программа завершилась с ошибкой, сохраните её сообщение и этап выполнения. Перед передачей записи другому человеку удалите значения секретов и личные пути. Не вырезайте само название проблемного поля: оно нужно для разбора. Если ошибка возникла при чтении output, сначала откройте сохранённый JSON и найдите этот элемент. Пустой список, другой тип значения и отсутствующее поле требуют разных изменений локального обработчика. Сам текст исключения не доказывает первопричину на стороне сервиса.

При успешном ответе сохраните исходную инструкцию вместе с полученным текстом. Выпишите неизвестные сведения отдельно: в учебном объявлении точная дата и час не заданы. Затем проверьте, не превратил ли ответ неизвестность в обещание. Если правка нужна, сформулируйте конкретное расхождение и снова сверяйте весь результат после уточнения. Список изменений, который написала сама модель, тоже требует проверки по двум версиям текста.

Для последующего сравнения меняйте одно условие запроса. Можно попросить таблицу вместо объявления, сохранив те же входные факты. Затем проверить, что строки таблицы содержат только исходные сведения. Можно уменьшить объём ответа и убедиться, что оговорка о прежнем времени не исчезла. Такие прогоны выполняются в вашем аккаунте по его условиям; редакция не измеряла их скорость, стоимость и количество переделок.

Когда остановиться и уточнить настройки

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

После чтения документации вернитесь к своей карточке и отметьте, какое условие подтверждено, а какое ещё требует проверки. Локальный пример с искусственным JSON остаётся доказательством работы конкретной функции чтения. Документированный HTTP-пример остаётся инструкцией для запуска. Результат обращения к YandexGPT появляется только после вашей действительной попытки; эту границу сохраняйте в заметках проекта и объяснении для команды.

Частые вопросы

Как получить API-ключ YandexGPT?
Ключ создаётся в интерфейсе AI Studio кнопкой «Создать API-ключ» в правом верхнем углу. Нужно задать описание и срок действия, затем сохранить идентификатор и секретный ключ. После закрытия диалога значение ключа недоступно. Для создания ключа нужна роль resource-manager.admin на каталог.

Есть ли бесплатный доступ к YandexGPT через API?
В официальном quickstart описан стартовый грант при первом платёжном аккаунте с привязанной картой. Проверьте применимость и условия в своём аккаунте. Эта инструкция не измеряет бесплатную квоту и стоимость запроса.

Какую модель использовать для первого запроса?
Документация Responses API приводит yandexgpt-lite и URI вида gpt://<идентификатор_каталога>/yandexgpt-lite. В каталоге моделей есть и другие варианты, включая YandexGPT Pro и Alice AI LLM. Начните с той модели, что указана в примере, чтобы сверить сборку запроса.

Что такое Folder ID и где его взять?
Folder ID — идентификатор каталога, пространства с ресурсами Yandex Cloud. Он нужен для аутентификации в AI Studio. В интерфейсе AI Studio найдите название каталога в верхней части экрана и используйте кнопку копирования идентификатора рядом с ним. Оно подставляется в URI модели и в заголовок x-folder-id.

Почему запрос возвращает ошибку?
Проверьте три вещи: подставлен ли реальный идентификатор каталога вместо переменной, тот ли ключ лежит в переменной окружения, не смешаны ли поля Responses API с нативным форматом генерации текста. Отдельная причина — устаревший URI модели: документация указывает, что такие запросы возвращают 400 Bad Request.

Если вы только выбираете между моделями для повседневных задач, посмотрите сравнение DeepSeek и Алисы. Для генерации изображений пригодится материал про лимиты Шедеврума. А если задача — тексты для видео, есть разбор нейросетей для сценариев.