# YandexGPT API (Yandex AI Studio): Извлечь данные из текста в JSON

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

Разобрать письмо клиента, заявку или отзыв в структуру: имя, телефон, суть обращения, тональность.

1. Отправь запрос: POST /foundationModels/v1/completion с инструкцией в system-сообщении и текстом в user-сообщении.
2. Добавь jsonSchema.schema — схему ответа: модель вернёт валидный JSON по ней. Если схема не нужна, достаточно jsonObject = true. Эти параметры взаимоисключающие.
3. Поставь temperature ближе к 0 — так ответы стабильнее.
4. Разбери result.alternatives[0].message.text как JSON и всё равно проверяй поля перед записью в базу.

```python
import json, requests

r = requests.post("https://ai.api.cloud.yandex.net/foundationModels/v1/completion",
    headers={"Authorization": f"Api-Key {API_KEY}"},
    json={
        "modelUri": f"gpt://{FOLDER_ID}/yandexgpt-5-lite",
        "completionOptions": {"temperature": 0, "maxTokens": "300"},
        "messages": [
            {"role": "system", "text": "Извлеки из обращения клиента данные."},
            {"role": "user", "text": "Здравствуйте, это Иван, +7 999 000-11-22. Заказ 1042 так и не пришёл, очень недоволен."},
        ],
        "jsonSchema": {"schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "phone": {"type": "string"}, "order": {"type": "string"},
                           "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]}},
            "required": ["name", "sentiment"],
        }},
    }).json()
data = json.loads(r["result"]["alternatives"][0]["message"]["text"])
```

## Базовые 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@<суффикс>`.

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

- [Сгенерировать текст по запросу](https://mcp-everything.ru/integrations/yandexgpt/scenarios/sgenerirovat-tekst-po-zaprosu.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