{"name":"YandexGPT API (Yandex AI Studio)","vendor":"Яндекс","industry":"ai","summary":"API генеративных моделей Yandex AI Studio (Yandex Cloud): генерация текста моделями YandexGPT, Alice AI LLM и открытыми моделями (DeepSeek, Qwen, gpt-oss) в синхронном и асинхронном режиме, OpenAI-совместимый Responses API и векторные представления текста (эмбеддинги). Модель выбирается URI вида `gpt://<идентификатор_каталога>/<модель>`.","docsUrl":"https://aistudio.yandex.ru/ru/docs/ai-studio/","coverage":{"included":[],"excluded":[]},"scenarios":[{"id":"sgenerirovat-tekst-po-zaprosu","title":"Сгенерировать текст по запросу","summary":"Ответ модели на вопрос пользователя, описание товара, черновик письма — один запрос к YandexGPT.","steps":["Создай в 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 — указывай актуальную модель явно."],"code":"curl -X POST https://ai.api.cloud.yandex.net/foundationModels/v1/completion \\\n  -H \"Authorization: Api-Key $YANDEX_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"modelUri\": \"gpt://'\"$YANDEX_FOLDER_ID\"'/yandexgpt-5-lite\",\n        \"completionOptions\": {\"stream\": false, \"temperature\": 0.3, \"maxTokens\": \"500\"},\n        \"messages\": [\n          {\"role\": \"system\", \"text\": \"Ты пишешь короткие продающие описания товаров для интернет-магазина.\"},\n          {\"role\": \"user\", \"text\": \"Кружка керамическая, 330 мл, белая, можно в посудомойку.\"}\n        ]\n      }'","language":"bash","methods":["POST /foundationModels/v1/completion"]},{"id":"izvlech-dannye-iz-teksta-v-json","title":"Извлечь данные из текста в JSON","summary":"Разобрать письмо клиента, заявку или отзыв в структуру: имя, телефон, суть обращения, тональность.","steps":["Отправь запрос: POST /foundationModels/v1/completion с инструкцией в system-сообщении и текстом в user-сообщении.","Добавь jsonSchema.schema — схему ответа: модель вернёт валидный JSON по ней. Если схема не нужна, достаточно jsonObject = true. Эти параметры взаимоисключающие.","Поставь temperature ближе к 0 — так ответы стабильнее.","Разбери result.alternatives[0].message.text как JSON и всё равно проверяй поля перед записью в базу."],"code":"import json, requests\n\nr = requests.post(\"https://ai.api.cloud.yandex.net/foundationModels/v1/completion\",\n    headers={\"Authorization\": f\"Api-Key {API_KEY}\"},\n    json={\n        \"modelUri\": f\"gpt://{FOLDER_ID}/yandexgpt-5-lite\",\n        \"completionOptions\": {\"temperature\": 0, \"maxTokens\": \"300\"},\n        \"messages\": [\n            {\"role\": \"system\", \"text\": \"Извлеки из обращения клиента данные.\"},\n            {\"role\": \"user\", \"text\": \"Здравствуйте, это Иван, +7 999 000-11-22. Заказ 1042 так и не пришёл, очень недоволен.\"},\n        ],\n        \"jsonSchema\": {\"schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"name\": {\"type\": \"string\"}, \"phone\": {\"type\": \"string\"}, \"order\": {\"type\": \"string\"},\n                           \"sentiment\": {\"type\": \"string\", \"enum\": [\"positive\", \"neutral\", \"negative\"]}},\n            \"required\": [\"name\", \"sentiment\"],\n        }},\n    }).json()\ndata = json.loads(r[\"result\"][\"alternatives\"][0][\"message\"][\"text\"])","language":"python","methods":["POST /foundationModels/v1/completion"]},{"id":"obrabotat-mnogo-zaprosov-v-asinhronnom","title":"Обработать много запросов в асинхронном режиме","summary":"Ночная обработка тысяч карточек товаров или обращений — без упора в лимит одновременных генераций.","steps":["Отправляй запросы: POST /foundationModels/v1/completionAsync с теми же параметрами, что и синхронная генерация. В ответе — объект Operation с id.","Забирай результат: GET /operations/{operationId} на хосте operation.api.cloud.yandex.net. Пока done = false — повторяй позже; когда true, заполнено ровно одно из полей response или error.","Лимиты асинхронного режима — 10 запросов в секунду на генерацию, 50 в секунду на получение ответа и 5 000 в час. Квоты увеличиваются через поддержку."],"code":"OP=$(curl -s -X POST https://ai.api.cloud.yandex.net/foundationModels/v1/completionAsync \\\n  -H \"Authorization: Api-Key $YANDEX_API_KEY\" -H 'Content-Type: application/json' \\\n  -d '{\"modelUri\": \"gpt://'\"$YANDEX_FOLDER_ID\"'/yandexgpt-5-lite\", \"messages\": [{\"role\": \"user\", \"text\": \"Кратко перескажи: ...\"}]}' | jq -r .id)\n\ncurl https://operation.api.cloud.yandex.net/operations/$OP -H \"Authorization: Api-Key $YANDEX_API_KEY\"","language":"bash","methods":["POST /foundationModels/v1/completionAsync","GET /operations/{operationId}"]},{"id":"semanticheskiy-poisk-po-svoim-tekstam","title":"Семантический поиск по своим текстам","summary":"Найти похожие вопросы в базе знаний или подходящие товары по смыслу, а не по словам — основа для RAG.","steps":["Посчитай векторы документов: 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 как контекст — модель ответит по твоим данным."],"code":"def embed(text: str, kind: str) -> list[float]:\n    r = requests.post(\"https://ai.api.cloud.yandex.net/foundationModels/v1/textEmbedding\",\n                      headers={\"Authorization\": f\"Api-Key {API_KEY}\"},\n                      json={\"modelUri\": f\"emb://{FOLDER_ID}/text-search-{kind}/latest\", \"text\": text}).json()\n    return r[\"embedding\"]\n\ndoc_vec = embed(\"Как вернуть товар надлежащего качества\", \"doc\")\nquery_vec = embed(\"хочу сдать обратно кружку\", \"query\")","language":"python","methods":["POST /foundationModels/v1/completion","POST /foundationModels/v1/textEmbedding"]},{"id":"podklyuchitsya-cherez-openai-sovmestimyy","title":"Подключиться через OpenAI-совместимый Responses API","summary":"Если код уже написан под OpenAI — переключить его на модели Yandex AI Studio с минимальными правками.","steps":["Нужны роли 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) — но часть из них доступна ограниченное время, проверяй список перед интеграцией."],"code":"curl -X POST https://ai.api.cloud.yandex.net/v1/responses \\\n  -H \"Authorization: Api-Key $YANDEX_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  --max-time 60 \\\n  -d '{\n        \"model\": \"gpt://'\"$YANDEX_FOLDER_ID\"'/yandexgpt-5-lite\",\n        \"temperature\": 0.5,\n        \"max_output_tokens\": 800,\n        \"input\": \"Придумай 3 названия для кофейни у вокзала.\"\n      }'","language":"bash","methods":["POST /v1/responses"]}],"baseUrls":[{"label":"Боевой (Foundation Models API)","url":"https://ai.api.cloud.yandex.net"},{"label":"Операции (результат асинхронных запросов)","url":"https://operation.api.cloud.yandex.net"}],"auth":{"type":"bearer","description":"- IAM-токен (аккаунт на Яндексе, федеративный, локальный или сервисный аккаунт): `Authorization: Bearer <IAM-токен>`\n- API-ключ (только сервисный аккаунт): `Authorization: Api-Key <API-ключ>`\n\nДля генерации текста нужна роль `ai.languageModels.user` или выше; для Responses API — `ai.assistants.editor` и `ai.languageModels.user`.","example":""},"methods":[{"id":"POST /foundationModels/v1/completion","title":"Генерация текста","httpMethod":"POST","path":"/foundationModels/v1/completion","description":"В ответе: `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`.","params":[{"name":"modelUri","in":"body","type":"string","required":true,"description":"URI модели, например gpt://<идентификатор_каталога>/yandexgpt-5-lite"},{"name":"completionOptions.stream","in":"body","type":"boolean","required":false,"description":"Потоковая передача частично сгенерированного текста"},{"name":"completionOptions.temperature","in":"body","type":"number","required":false,"description":"От 0 до 1, по умолчанию 0.3"},{"name":"completionOptions.maxTokens","in":"body","type":"string","required":false,"description":"Лимит токенов в ответе, больше нуля"},{"name":"completionOptions.reasoningOptions.mode","in":"body","type":"string","required":false,"description":"DISABLED или ENABLED_HIDDEN"},{"name":"messages","in":"body","type":"array","required":true,"description":"Контекст диалога"},{"name":"messages[].role","in":"body","type":"string","required":false,"description":"system, assistant или user"},{"name":"messages[].text","in":"body","type":"string","required":false,"description":"Текст сообщения; взаимоисключающее с toolCallList и toolResultList"},{"name":"tools","in":"body","type":"array","required":false,"description":"Инструменты для вызова: function.name, function.description, function.parameters (JSON Schema), function.strict"},{"name":"jsonObject","in":"body","type":"boolean","required":false,"description":"Ответ — валидный JSON; взаимоисключающее с jsonSchema"},{"name":"jsonSchema.schema","in":"body","type":"object","required":false,"description":"JSON Schema, которой должен соответствовать ответ"},{"name":"parallelToolCalls","in":"body","type":"boolean","required":false,"description":"Несколько вызовов инструментов за ответ, по умолчанию true"},{"name":"toolChoice.mode","in":"body","type":"string","required":false,"description":"NONE, AUTO (по умолчанию) или REQUIRED"},{"name":"toolChoice.functionName","in":"body","type":"string","required":false,"description":"Принудительный вызов конкретной функции"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /foundationModels/v1/completionAsync","title":"Асинхронная генерация текста","httpMethod":"POST","path":"/foundationModels/v1/completionAsync","description":"Принимает те же параметры, что `completion`. Возвращает объект Operation (`id`, `done`, `response` или `error`); результат забирают по `id` операции.","params":[],"requestExample":"","responseExample":"","docsUrl":""},{"id":"GET /operations/{operationId}","title":"Результат асинхронной операции","httpMethod":"GET","path":"/operations/{operationId}","description":"Хост `operation.api.cloud.yandex.net`. Когда `done` равно `true`, заполнено ровно одно из полей `response` или `error`.","params":[{"name":"operationId","in":"path","type":"string","required":true,"description":"ID операции из ответа completionAsync"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /foundationModels/v1/textEmbedding","title":"Эмбеддинг текста","httpMethod":"POST","path":"/foundationModels/v1/textEmbedding","description":"В ответе: `embedding` (список чисел), `numTokens`, `modelVersion`.","params":[{"name":"modelUri","in":"body","type":"string","required":true,"description":"URI модели эмбеддингов"},{"name":"text","in":"body","type":"string","required":true,"description":"Входной текст"},{"name":"dim","in":"body","type":"string","required":false,"description":"Размерность эмбеддинга (для моделей с несколькими размерностями)"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"POST /v1/responses","title":"Responses API (OpenAI-совместимый)","httpMethod":"POST","path":"/v1/responses","description":"Текст ответа — в элементах с `\"type\": \"output_text\"` (поле `text`).","params":[{"name":"model","in":"body","type":"string","required":true,"description":"URI модели gpt://<идентификатор_каталога>/<модель>"},{"name":"input","in":"body","type":"string","required":true,"description":"Запрос к модели"},{"name":"temperature","in":"body","type":"number","required":false,"description":"Температура генерации"},{"name":"max_output_tokens","in":"body","type":"integer","required":false,"description":"Лимит токенов в ответе"}],"requestExample":"curl \\\n--request POST https://ai.api.cloud.yandex.net/v1/responses \\\n--header \"Authorization: Api-Key ${YANDEX_API_KEY}\" \\\n--header \"Content-Type: application/json\" \\\n--max-time 60 \\\n--data '{\n    \"model\": \"gpt://'\"${YANDEX_FOLDER_ID}\"'/'\"${YANDEX_MODEL}\"'\",\n    \"temperature\": 0.8,\n    \"max_output_tokens\": 1500,\n    \"input\": \"Придумай 3 необычные идеи для стартапа в сфере путешествий.\"\n}'","responseExample":"","docsUrl":""}],"codeExamples":[],"errors":[{"code":"400","description":"Некорректные параметры или неподдерживаемый URI модели"},{"code":"401","description":"Нужна аутентификация"},{"code":"403","description":"Недостаточно прав"},{"code":"429","description":"Превышена квота запросов"},{"code":"500","description":"Внутренняя ошибка"},{"code":"503","description":"Сервис временно недоступен"}],"limits":"- Одновременных генераций в синхронном режиме — 5.\n- Асинхронный режим: 10 запросов в секунду на генерацию, 50 запросов в секунду на получение ответа, 5 000 запросов в час.\n- Квоты можно увеличить через техподдержку.","gotchas":["Старые URI `.../yandexgpt/latest` и `.../yandexgpt/rc` работают до окончания поддержки; после этого запросы по устаревшему URI возвращают `400 Bad Request` — автоматического переключения на новую версию нет.","Часть открытых моделей доступна ограниченное время (gpt-oss-120b и gpt-oss-20b — до 30 октября 2026 года); список проверяйте перед интеграцией.","`maxTokens`, `dim` и счётчики токенов в ответах передаются строками (int64).","Дообученные модели: `gpt://<идентификатор_каталога>/yandexgpt-lite/latest@<суффикс>`."],"slug":"yandexgpt","version":2,"updatedAt":"2026-10-24T17:05:42.405Z","sources":[{"title":"Генерация текста — Completion","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/text-generation/api-ref/TextGeneration/completion","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Асинхронная генерация","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/text-generation/api-ref/TextGenerationAsync/completion","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Эмбеддинги","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/embeddings/api-ref/Embeddings/textEmbedding","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Аутентификация","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/api-ref/authentication","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Модели генерации","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/concepts/generation/models","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Запрос к модели (Responses API)","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/operations/generation/create-prompt","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Квоты и лимиты","url":"https://aistudio.yandex.ru/ru/docs/ai-studio/concepts/limits","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Обработка ошибок в API Yandex Cloud","url":"https://yandex.cloud/ru/docs/api-design-guide/concepts/errors","kind":"research","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"Вставленный текст","url":"","kind":"import","addedAt":"2026-10-14T14:53:49.435Z"},{"title":"scenarios-yandexgpt.md","url":"","kind":"import","addedAt":"2026-10-24T17:05:31.205Z"}],"logoUrl":null}