# YandexGPT API (Yandex AI Studio): 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 | нет | Принудительный вызов конкретной функции |

## Базовые 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`.

## Нюансы

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

## Сценарии с этим методом

- [Сгенерировать текст по запросу](https://mcp-everything.ru/integrations/yandexgpt/scenarios/sgenerirovat-tekst-po-zaprosu.md)
- [Извлечь данные из текста в JSON](https://mcp-everything.ru/integrations/yandexgpt/scenarios/izvlech-dannye-iz-teksta-v-json.md)
- [Семантический поиск по своим текстам](https://mcp-everything.ru/integrations/yandexgpt/scenarios/semanticheskiy-poisk-po-svoim-tekstam.md)

---

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