YandexGPT API (Yandex AI Studio) API

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

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

Сценарии

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

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

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

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

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

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

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

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

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

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

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.

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

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 с минимальными правками.

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

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 запросов в час.
Квоты можно увеличить через техподдержку.

Источники

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