# YandexGPT API (Yandex AI Studio): Сгенерировать текст по запросу

Сценарий из mcp-everything. Актуально на 2026-10-24.

Ответ модели на вопрос пользователя, описание товара, черновик письма — один запрос к YandexGPT.

1. Создай в Yandex Cloud сервисный аккаунт с ролью ai.languageModels.user и API-ключ для него. Передавай ключ в заголовке Authorization: Api-Key <ключ>. Понадобится и ID каталога (folder).
2. Отправь запрос: POST /foundationModels/v1/completion с modelUri вида gpt://<ID каталога>/yandexgpt-5-lite, completionOptions (temperature, maxTokens) и messages — сообщениями с role (system, user, assistant) и text.
3. Ответ — в result.alternatives[0].message.text, статус ALTERNATIVE_STATUS_FINAL означает, что генерация завершилась. Расход токенов — в result.usage; счётчики приходят строками.
4. Одновременно в синхронном режиме выполняется не больше 5 генераций; для массовой обработки используй асинхронный режим.
5. Старые URI вида .../yandexgpt/latest после окончания поддержки возвращают 400 — указывай актуальную модель явно.

```bash
curl -X POST https://ai.api.cloud.yandex.net/foundationModels/v1/completion \
  -H "Authorization: Api-Key $YANDEX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "modelUri": "gpt://'"$YANDEX_FOLDER_ID"'/yandexgpt-5-lite",
        "completionOptions": {"stream": false, "temperature": 0.3, "maxTokens": "500"},
        "messages": [
          {"role": "system", "text": "Ты пишешь короткие продающие описания товаров для интернет-магазина."},
          {"role": "user", "text": "Кружка керамическая, 330 мл, белая, можно в посудомойку."}
        ]
      }'
```

## Базовые URL

- Боевой (Foundation Models API): `https://ai.api.cloud.yandex.net`
- Операции (результат асинхронных запросов): `https://operation.api.cloud.yandex.net`

## Авторизация

Тип: Bearer-токен

- IAM-токен (аккаунт на Яндексе, федеративный, локальный или сервисный аккаунт): `Authorization: Bearer <IAM-токен>`
- API-ключ (только сервисный аккаунт): `Authorization: Api-Key <API-ключ>`

Для генерации текста нужна роль `ai.languageModels.user` или выше; для Responses API — `ai.assistants.editor` и `ai.languageModels.user`.

## Методы сценария

### POST /foundationModels/v1/completion — Генерация текста

В ответе: `alternatives[]` (`message` с `role` и `text`/`toolCallList`, `status`), `usage` (`inputTextTokens`, `completionTokens`, `totalTokens`, `completionTokensDetails.reasoningTokens`), `modelVersion`. Значения `status`: `ALTERNATIVE_STATUS_PARTIAL`, `ALTERNATIVE_STATUS_TRUNCATED_FINAL`, `ALTERNATIVE_STATUS_FINAL`, `ALTERNATIVE_STATUS_CONTENT_FILTER`, `ALTERNATIVE_STATUS_TOOL_CALLS`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `modelUri` | body | string | да | URI модели, например gpt://<идентификатор_каталога>/yandexgpt-5-lite |
| `completionOptions.stream` | body | boolean | нет | Потоковая передача частично сгенерированного текста |
| `completionOptions.temperature` | body | number | нет | От 0 до 1, по умолчанию 0.3 |
| `completionOptions.maxTokens` | body | string | нет | Лимит токенов в ответе, больше нуля |
| `completionOptions.reasoningOptions.mode` | body | string | нет | DISABLED или ENABLED_HIDDEN |
| `messages` | body | array | да | Контекст диалога |
| `messages[].role` | body | string | нет | system, assistant или user |
| `messages[].text` | body | string | нет | Текст сообщения; взаимоисключающее с toolCallList и toolResultList |
| `tools` | body | array | нет | Инструменты для вызова: function.name, function.description, function.parameters (JSON Schema), function.strict |
| `jsonObject` | body | boolean | нет | Ответ — валидный JSON; взаимоисключающее с jsonSchema |
| `jsonSchema.schema` | body | object | нет | JSON Schema, которой должен соответствовать ответ |
| `parallelToolCalls` | body | boolean | нет | Несколько вызовов инструментов за ответ, по умолчанию true |
| `toolChoice.mode` | body | string | нет | NONE, AUTO (по умолчанию) или REQUIRED |
| `toolChoice.functionName` | body | string | нет | Принудительный вызов конкретной функции |

## Нюансы

- Старые URI `.../yandexgpt/latest` и `.../yandexgpt/rc` работают до окончания поддержки; после этого запросы по устаревшему URI возвращают `400 Bad Request` — автоматического переключения на новую версию нет.
- Часть открытых моделей доступна ограниченное время (gpt-oss-120b и gpt-oss-20b — до 30 октября 2026 года); список проверяйте перед интеграцией.
- `maxTokens`, `dim` и счётчики токенов в ответах передаются строками (int64).
- Дообученные модели: `gpt://<идентификатор_каталога>/yandexgpt-lite/latest@<суффикс>`.

## Другие сценарии

- [Извлечь данные из текста в JSON](https://mcp-everything.ru/integrations/yandexgpt/scenarios/izvlech-dannye-iz-teksta-v-json.md)
- [Обработать много запросов в асинхронном режиме](https://mcp-everything.ru/integrations/yandexgpt/scenarios/obrabotat-mnogo-zaprosov-v-asinhronnom.md)
- [Семантический поиск по своим текстам](https://mcp-everything.ru/integrations/yandexgpt/scenarios/semanticheskiy-poisk-po-svoim-tekstam.md)
- [Подключиться через OpenAI-совместимый Responses API](https://mcp-everything.ru/integrations/yandexgpt/scenarios/podklyuchitsya-cherez-openai-sovmestimyy.md)

---

Если этого недостаточно — официальная документация: https://aistudio.yandex.ru/ru/docs/ai-studio/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandexgpt.md