Как вызвать YandexGPT через REST API: IAM-токен, modelUri и разбор usage

curl -X POST \
 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion' \
 -H "Authorization: Bearer $IAM_TOKEN" \
 -H "x-folder-id: $FOLDER_ID" \
 -H 'Content-Type: application/json' \
 -d '{
  "modelUri":"gpt://'$FOLDER_ID'/yandexgpt",
  "completionOptions":{"stream":false,"temperature":0.3,"maxTokens":"500"},
  "messages":[
   {"role":"system","text":"Не придумывай отсутствующие значения."},
   {"role":"user","text":"Выдели три риска из текста."}
  ]
 }'

• У аккаунта или сервисного аккаунта должна быть роль ai.languageModels.user либо более широкая подходящая роль.
• modelUri содержит ID каталога; запрос с чужим или неверным каталогом не должен обходиться сменой токена на пользовательской стороне.
• maxTokens ограничивает вывод, а temperature влияет на вариативность, но не гарантирует фактическую точность.
• В usage возвращаются входные, выходные и общие токены; эти поля пригодны для мониторинга сценариев.

Порядок действий

1. Создайте сервисный аккаунт с минимальной ролью на нужный каталог.
2. Получайте IAM-токен серверным способом и обновляйте до истечения.
3. Сверьте доступное имя модели в документации/каталоге.
4. Отправьте запрос и разберите result.alternatives, status и usage.
5. На 401 обновите токен один раз; на 429 примените очередь и задержку.

Как проверить результат

Попросите вернуть ровно три пункта и проверьте их число. Затем удалите роль у тестового аккаунта — запрос обязан завершиться отказом. Добавьте неизвестное значение во вход: модель должна обозначить отсутствие, а не заполнить его догадкой.

Ограничения

Названия моделей, квоты и цены обновляются. IAM-токен и API-ключ имеют разные свойства; выбирайте способ авторизации по официальной инструкции и инфраструктуре. Не выдавайте системное правило за защиту от всех галлюцинаций.

Чего не делать

• Не используйте Owner вместо минимальной роли.
• Не храните IAM-токен в репозитории.
• Не игнорируйте status альтернативы.

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