---
slug: "yandexgpt"
name: "YandexGPT API (Yandex AI Studio)"
vendor: "Яндекс"
industry: "ai"
docsUrl: "https://aistudio.yandex.ru/ru/docs/ai-studio/"
version: 2
updatedAt: "2026-10-24"
---

# YandexGPT API (Yandex AI Studio)

Отрасль: AI и нейросети. Актуально на 2026-10-24.

API генеративных моделей Yandex AI Studio (Yandex Cloud): генерация текста моделями YandexGPT, Alice AI LLM и открытыми моделями (DeepSeek, Qwen, gpt-oss) в синхронном и асинхронном режиме, OpenAI-совместимый Responses API и векторные представления текста (эмбеддинги). Модель выбирается URI вида `gpt://<идентификатор_каталога>/<модель>`.

## Сценарии

### Сгенерировать текст по запросу

Ответ модели на вопрос пользователя, описание товара, черновик письма — один запрос к 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 мл, белая, можно в посудомойку."}
        ]
      }'
```

### Извлечь данные из текста в JSON

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

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"])
```

### Обработать много запросов в асинхронном режиме

Ночная обработка тысяч карточек товаров или обращений — без упора в лимит одновременных генераций.

1. Отправляй запросы: POST /foundationModels/v1/completionAsync с теми же параметрами, что и синхронная генерация. В ответе — объект Operation с id.
2. Забирай результат: GET /operations/{operationId} на хосте operation.api.cloud.yandex.net. Пока done = false — повторяй позже; когда true, заполнено ровно одно из полей response или error.
3. Лимиты асинхронного режима — 10 запросов в секунду на генерацию, 50 в секунду на получение ответа и 5 000 в час. Квоты увеличиваются через поддержку.

```bash
OP=$(curl -s -X POST https://ai.api.cloud.yandex.net/foundationModels/v1/completionAsync \
  -H "Authorization: Api-Key $YANDEX_API_KEY" -H 'Content-Type: application/json' \
  -d '{"modelUri": "gpt://'"$YANDEX_FOLDER_ID"'/yandexgpt-5-lite", "messages": [{"role": "user", "text": "Кратко перескажи: ..."}]}' | jq -r .id)

curl https://operation.api.cloud.yandex.net/operations/$OP -H "Authorization: Api-Key $YANDEX_API_KEY"
```

### Семантический поиск по своим текстам

Найти похожие вопросы в базе знаний или подходящие товары по смыслу, а не по словам — основа для RAG.

1. Посчитай векторы документов: POST /foundationModels/v1/textEmbedding с modelUri модели для документов (emb://<ID каталога>/text-search-doc/latest) и text. В ответе embedding — список чисел.
2. Сохрани векторы в базе с поддержкой векторного поиска (например, PostgreSQL с pgvector).
3. Для запроса пользователя посчитай вектор моделью для запросов (emb://<ID каталога>/text-search-query/latest) и найди ближайшие документы по косинусному сходству.
4. Найденные фрагменты передай в POST /foundationModels/v1/completion как контекст — модель ответит по твоим данным.

```python
def embed(text: str, kind: str) -> list[float]:
    r = requests.post("https://ai.api.cloud.yandex.net/foundationModels/v1/textEmbedding",
                      headers={"Authorization": f"Api-Key {API_KEY}"},
                      json={"modelUri": f"emb://{FOLDER_ID}/text-search-{kind}/latest", "text": text}).json()
    return r["embedding"]

doc_vec = embed("Как вернуть товар надлежащего качества", "doc")
query_vec = embed("хочу сдать обратно кружку", "query")
```

### Подключиться через OpenAI-совместимый Responses API

Если код уже написан под OpenAI — переключить его на модели Yandex AI Studio с минимальными правками.

1. Нужны роли ai.assistants.editor и ai.languageModels.user у сервисного аккаунта.
2. Отправь запрос: POST /v1/responses с model = gpt://<ID каталога>/<модель>, input — текстом запроса, temperature и max_output_tokens.
3. Текст ответа — в элементах output с type = output_text, поле text.
4. Через тот же API доступны и открытые модели (DeepSeek, Qwen, gpt-oss) — но часть из них доступна ограниченное время, проверяй список перед интеграцией.

```bash
curl -X POST https://ai.api.cloud.yandex.net/v1/responses \
  -H "Authorization: Api-Key $YANDEX_API_KEY" \
  -H 'Content-Type: application/json' \
  --max-time 60 \
  -d '{
        "model": "gpt://'"$YANDEX_FOLDER_ID"'/yandexgpt-5-lite",
        "temperature": 0.5,
        "max_output_tokens": 800,
        "input": "Придумай 3 названия для кофейни у вокзала."
      }'
```

## Базовые 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 | нет | Принудительный вызов конкретной функции |

### POST /foundationModels/v1/completionAsync — Асинхронная генерация текста

Принимает те же параметры, что `completion`. Возвращает объект Operation (`id`, `done`, `response` или `error`); результат забирают по `id` операции.

### GET /operations/{operationId} — Результат асинхронной операции

Хост `operation.api.cloud.yandex.net`. Когда `done` равно `true`, заполнено ровно одно из полей `response` или `error`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `operationId` | path | string | да | ID операции из ответа completionAsync |

### POST /foundationModels/v1/textEmbedding — Эмбеддинг текста

В ответе: `embedding` (список чисел), `numTokens`, `modelVersion`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `modelUri` | body | string | да | URI модели эмбеддингов |
| `text` | body | string | да | Входной текст |
| `dim` | body | string | нет | Размерность эмбеддинга (для моделей с несколькими размерностями) |

### POST /v1/responses — Responses API (OpenAI-совместимый)

Текст ответа — в элементах с `"type": "output_text"` (поле `text`).

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `model` | body | string | да | URI модели gpt://<идентификатор_каталога>/<модель> |
| `input` | body | string | да | Запрос к модели |
| `temperature` | body | number | нет | Температура генерации |
| `max_output_tokens` | body | integer | нет | Лимит токенов в ответе |

Пример запроса:

```
curl \
--request POST https://ai.api.cloud.yandex.net/v1/responses \
--header "Authorization: Api-Key ${YANDEX_API_KEY}" \
--header "Content-Type: application/json" \
--max-time 60 \
--data '{
    "model": "gpt://'"${YANDEX_FOLDER_ID}"'/'"${YANDEX_MODEL}"'",
    "temperature": 0.8,
    "max_output_tokens": 1500,
    "input": "Придумай 3 необычные идеи для стартапа в сфере путешествий."
}'
```

## Нюансы

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

## Ошибки

| Код | Описание |
|---|---|
| `400` | Некорректные параметры или неподдерживаемый URI модели |
| `401` | Нужна аутентификация |
| `403` | Недостаточно прав |
| `429` | Превышена квота запросов |
| `500` | Внутренняя ошибка |
| `503` | Сервис временно недоступен |

## Ограничения

- Одновременных генераций в синхронном режиме — 5.
- Асинхронный режим: 10 запросов в секунду на генерацию, 50 запросов в секунду на получение ответа, 5 000 запросов в час.
- Квоты можно увеличить через техподдержку.

## Источники

- [Генерация текста — Completion](https://aistudio.yandex.ru/ru/docs/ai-studio/text-generation/api-ref/TextGeneration/completion)
- [Асинхронная генерация](https://aistudio.yandex.ru/ru/docs/ai-studio/text-generation/api-ref/TextGenerationAsync/completion)
- [Эмбеддинги](https://aistudio.yandex.ru/ru/docs/ai-studio/embeddings/api-ref/Embeddings/textEmbedding)
- [Аутентификация](https://aistudio.yandex.ru/ru/docs/ai-studio/api-ref/authentication)
- [Модели генерации](https://aistudio.yandex.ru/ru/docs/ai-studio/concepts/generation/models)
- [Запрос к модели (Responses API)](https://aistudio.yandex.ru/ru/docs/ai-studio/operations/generation/create-prompt)
- [Квоты и лимиты](https://aistudio.yandex.ru/ru/docs/ai-studio/concepts/limits)
- [Обработка ошибок в API Yandex Cloud](https://yandex.cloud/ru/docs/api-design-guide/concepts/errors)

---

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