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

Для вызова YandexGPT из приложения нужны не подписка ChatGPT и не ключ OpenAI, а проект в Yandex Cloud, ID каталога и авторизация Yandex Cloud. Для первого теста достаточно создать API-ключ, сохранить его в переменной окружения и отправить синхронный REST-запрос.

Что подготовить в Yandex Cloud

Откройте AI Studio в нужном каталоге Yandex Cloud и создайте API-ключ для субъекта, от имени которого будет выполняться запрос. Скопируйте значение ключа и ID каталога, в котором доступна модель.

API-ключ передаётся в заголовке Authorization: Api-Key <ключ>. Для Text Generation API у ключа может быть ограниченный scope yc.ai.languageModels.execute. Вместо него можно использовать IAM-токен с заголовком Authorization: Bearer, но такой токен действует не более 12 часов. Для локального первого запроса API-ключ обычно проще. Форматы авторизации описаны в документации API key и IAM token.

В Bash задайте значения так:

export YANDEX_API_KEY='ваш_api_ключ'
export YANDEX_FOLDER_ID='ваш_folder_id'

В Windows PowerShell:

$env:YANDEX_API_KEY = "ваш_api_ключ"
$env:YANDEX_FOLDER_ID = "ваш_folder_id"

Не записывайте секрет в Git, исходники или публикуемый лог CI. Если нужен посредник для отдельного AI-сервиса, можно посмотреть каталог AI-сервисов и подписок Amber Market, но он не заменяет проект, права и API-ключ Yandex Cloud. Наличие и условия конкретного предложения проверьте на карточке; магазин принимает заказы через СБП, без автоматических списаний.

Укажите URI модели явно

В теле запроса поле modelUri должно указывать и модель, и каталог. Для примера возьмём URI вида:

gpt://<folder_ID>/yandexgpt-5.1

Замените <folder_ID> на значение YANDEX_FOLDER_ID. Версия 5.1 не означает, что URI будет постоянным: список доступных моделей и актуальные идентификаторы меняются. Старый URI не переключается автоматически после вывода модели из эксплуатации, поэтому перед переносом примера в приложение сверяйте его с разделом Available generative models.

Первый вызов через curl

Синхронная генерация выполняется POST-запросом на https://ai.api.cloud.yandex.net/foundationModels/v1/completion:

curl --fail-with-body \
  --request POST \
  --url https://ai.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-5.1",
  "completionOptions": {
    "stream": false,
    "temperature": 0.3,
    "maxTokens": 200
  },
  "messages": [
    {
      "role": "user",
      "text": "Коротко объясни, зачем API нужен явный URI модели."
    }
  ]
}
JSON

modelUri выбирает модель, messages передаёт диалог, а completionOptions задаёт режим генерации. Для сообщения доступны роли system, user и assistant; текст находится в поле text. temperature принимает значения от 0 до 1 и по умолчанию равна 0.3, а maxTokens должен быть больше нуля. Формат запроса описан в справочнике TextGeneration.Completion.

В этом примере используется Bash heredoc: ${YANDEX_FOLDER_ID} оболочка подставляет до отправки JSON. В PowerShell удобнее сохранить тело в here-string или сразу запустить Python-вариант.

Тот же запрос из Python

Для минимальной проверки подойдёт requests:

import os

import requests


api_key = os.environ["YANDEX_API_KEY"]
folder_id = os.environ["YANDEX_FOLDER_ID"]

response = requests.post(
    "https://ai.api.cloud.yandex.net/foundationModels/v1/completion",
    headers={
        "Authorization": f"Api-Key {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "modelUri": f"gpt://{folder_id}/yandexgpt-5.1",
        "completionOptions": {
            "stream": False,
            "temperature": 0.3,
            "maxTokens": 200,
        },
        "messages": [
            {
                "role": "user",
                "text": "Верни одну фразу: API отвечает.",
            }
        ],
    },
    timeout=60,
)

response.raise_for_status()
payload = response.json()

text = payload["result"]["alternatives"][0]["message"]["text"]
print(text)
print(payload["result"].get("modelVersion"))

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

Как проверить авторизацию и ответ

Для первого запуска проверьте два условия:

1. HTTP-статус равен 200.
2. В ответе есть непустой текст в alternatives[0].message.text.

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

Если curl вернул ошибку, проверяйте границы по порядку:

• 401 или ошибка авторизации — ключ отсутствует, повреждён, передан без схемы Api-Key в заголовке Authorization или больше недействителен;
• ошибка доступа — у субъекта нет прав на каталог или у ключа неподходящий scope;
• ошибка модели — неверны modelUri, ID каталога или указан устаревший URI;
• ошибка валидации — проверьте, что messages является массивом, у каждого сообщения есть role и text, а maxTokens больше нуля.

Сначала выведите только наличие переменных, а не сами секреты:

print(bool(os.getenv("YANDEX_API_KEY")))
print(os.getenv("YANDEX_FOLDER_ID"))

Если первая строка печатает False, текущий процесс не видит ключ и до YandexGPT дело ещё не дошло. Если ключ виден, но API отвергает запрос, сравните заголовок, каталог и явный URI модели с актуальной документацией. Так проверяется именно доступ к Text Generation API, а не пользовательский веб-интерфейс YandexGPT.