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

Для первого запроса к YandexGPT нужны три вещи: идентификатор каталога Yandex Cloud, сервисный аккаунт с правом вызывать языковые модели и API-ключ этого аккаунта. Сам ключ не привязан к вашей учётной записи как к пользователю: он выпускается для сервисного аккаунта и передаётся в HTTP-заголовке Authorization с префиксом Api-Key.

Что подготовить до создания ключа

Откройте консоль Yandex Cloud и выберите каталог, из которого будет выполняться запрос. Скопируйте его идентификатор — он понадобится в modelUri. Для создания сервисного аккаунта у вашей учётной записи должны быть соответствующие права на этот каталог. Имя аккаунта тоже должно соответствовать ограничениям Yandex Cloud; например, используйте короткое имя yandexgpt-client без пробелов.

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

Для генерации текста через YandexGPT при создании API-ключа выберите scope yc.ai.languageModels.execute. Scope и срок действия можно ограничить — для локальной проверки это полезнее, чем выпускать ключ без ограничений. Пошаговое создание описано в документации Yandex Cloud по управлению API-ключами, а назначение ключа и заголовка — в описании API-ключей.

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

API-ключ, IAM-токен и RSA-ключ — это разные вещи

Не подставляйте в запрос случайный ключ из другого раздела консоли.

• API-ключ сервисного аккаунта отправляется как Authorization: Api-Key <значение> и подходит для первого REST-запроса ниже.
• IAM-токен — другой способ авторизации с другим форматом заголовка и сроком жизни. Наличие IAM-токена не превращает его в API-ключ.
• RSA-ключ используется для получения IAM-токена от имени сервисного аккаунта. Сам файл закрытого ключа нельзя передать в Authorization вместо API-ключа.

В этой инструкции используем именно API-ключ: он проще для локального smoke-теста и не требует отдельного шага получения токена.

Сохраните секрет и идентификаторы в окружении

В Linux или macOS можно задать значения так:

export YANDEX_API_KEY='скопированный-секрет'
export YANDEX_FOLDER_ID='идентификатор-каталога'

Не записывайте ключ прямо в Git, Dockerfile или исходный код. Для сервиса используйте секрет-хранилище, а локальный .env добавьте в .gitignore. Перед отправкой запроса полезно проверить, что переменные непустые, но не выводить сам секрет в терминал:

test -n "$YANDEX_API_KEY" && test -n "$YANDEX_FOLDER_ID" \
  && echo 'Параметры найдены' \
  || echo 'Не задан API-ключ или идентификатор каталога'

Первый запрос к YandexGPT через curl

Текстовая генерация выполняется POST-запросом к Foundation Models. В modelUri укажите каталог и актуальное имя модели с суффиксом /latest:

curl --fail-with-body \
  --request POST \
  --url 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion' \
  --header "Authorization: Api-Key ${YANDEX_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data @- <<JSON
{
  "modelUri": "gpt://${YANDEX_FOLDER_ID}/yandexgpt/latest",
  "completionOptions": {
    "stream": false,
    "temperature": 0.2,
    "maxTokens": "200"
  },
  "messages": [
    {
      "role": "user",
      "text": "Коротко объясни, зачем API нужен заголовок Authorization."
    }
  ]
}
JSON

Актуальный endpoint запроса — https://llm.api.cloud.yandex.net/foundationModels/v1/completion, а gpt://.../yandexgpt/latest находится в JSON-поле modelUri. Если перепутать эти значения, сервер получит технически неправильный запрос ещё до генерации текста. Формат полей также показан в примере REST-вызова YandexGPT.

Успешный ответ содержит результат генерации в JSON. Полезно сохранить полный ответ в файл и проверить его уже после HTTP-проверки:

curl --fail-with-body \
  --request POST \
  --url 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion' \
  --header "Authorization: Api-Key ${YANDEX_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "modelUri": "gpt://'"${YANDEX_FOLDER_ID}"'/yandexgpt/latest",
    "completionOptions": {"stream": false, "temperature": 0.2, "maxTokens": "100"},
    "messages": [{"role": "user", "text": "Ответь одним словом: готово"}]
  }' \
  > yandexgpt-response.json

head -c 500 yandexgpt-response.json

--fail-with-body сохраняет тело ошибки доступным для диагностики и возвращает ненулевой код при HTTP-ошибке. Это удобнее, чем считать любой полученный текст успешным ответом.

Если первый запрос не прошёл

Сначала проверьте три значения: API-ключ относится к нужному сервисному аккаунту, scope содержит yc.ai.languageModels.execute, а YANDEX_FOLDER_ID указывает на тот же каталог, где настроены права. Ошибка авторизации обычно означает неверный или отозванный секрет. Ошибка доступа часто указывает на роль сервисного аккаунта или на то, что для каталога не настроен биллинг.

Не обещайте себе бесплатный вызов только потому, что запрос тестовый: доступность, права и тарификация зависят от текущих условий Yandex Cloud. Названия моделей и доступные варианты могут меняться, поэтому перед переносом примера в рабочий сервис сверяйте URI и параметры в актуальной документации Foundation Models.

API YandexGPT — это программный доступ, а не пользовательская подписка ChatGPT и не готовый чат. Если после технического подключения вам нужен отдельный доступ к AI-сервисам, предложения можно посмотреть в каталоге Amber Market. Каталог не выдаёт Yandex Cloud API-ключ и не пополняет баланс API; это отдельный маршрут для заказа доступного сервиса через карточку товара и указанный там способ оплаты.

Когда curl-запрос заработал, перенесите ту же схему в приложение: читайте секрет из окружения, формируйте modelUri из проверенного идентификатора каталога, устанавливайте тайм-аут и логируйте код ответа без самого API-ключа. Если нужен отдельный пример первого запроса к другому провайдеру, он есть в инструкции по OpenAI API на Python; ключи и схемы авторизации там не взаимозаменяемы.