Один неверно выбранный сервис меняет не ответ модели, а весь способ выдачи прав и поддержки. Ты хотел позвать генеративную модель, а завёл маршрут для HTTP-запросов. Роль назначена не той команде, ключ выписан не на ту поверхность, и через неделю никто не понимает, почему интеграция «работает у меня, но не в проде».
Проблема не в моделях. Проблема в трёх названиях, которые звучат как синонимы, а управляются разными ролями, разной авторизацией и разной поддержкой. Поиск это подтверждает: api yandex ai, yandex ai api, yandex api ai - одно намерение в трёх написаниях, и ни одно из них не подсказывает, какой компонент Yandex Cloud тебе на самом деле нужен.
Одну границу оговорю сразу, дальше она пригодится. Если задача не в облачной роли, а в том, чтобы дёргать Claude или GPT по одному ключу, это другой класс инструмента: provod.ai - совместимый API-каталог внешних моделей, а не роль в Yandex Cloud. Всё остальное в тексте - про Yandex.
Проверить схему можно одним признаком: если выбранная поверхность требует другую авторизацию или другую роль, чем ты заложил, значит схема смешала компоненты. Дальше - карта, по которой это видно до интеграции, пока неверные ключи и границы исправить дёшево.
Платите в рублях за GPT API без наценки на токены через provod.ai
Почему неверный сервис меняет права, а не ответ?
Разберём три поверхности по документации Yandex Cloud, доступной на 2026-07-18.
Yandex AI Studio (ранее «Yandex Foundation Models») - это продуктовая поверхность для сборки AI-приложений и агентов поверх генеративных моделей, а не сама модель. Под одной консолью и API он собирает доступ к моделям, дообучение, датасеты, ассистентов и векторный поиск (S1). Когда в тикете пишут запрос вида yandex ai studio api или api в yandex cloud ai studio, речь именно про эту поверхность.
YandexGPT - это семейство моделей (Lite, Pro и последующие версии), которое обслуживается через AI Studio (S2). У него нет отдельной консоли и отдельного сервиса: модель вызывается через generation-API того же AI Studio. Поэтому запрос yandex cloud api yandexgpt - это не «другой сервис», это модель внутри AI Studio.
Yandex API Gateway - отдельный serverless-сервис, который объявляет и публикует HTTP-API из спецификации OpenAPI 3.0. В его собственной документации нет встроенного понятия AI-модели: это слой маршрутизации и интеграции, умеющий звать другие сервисы, но не хостящий модель (S3). Запрос yandex cloud api gateway ведёт сюда, и это чаще всего не то, что человек имел в виду, когда искал «нейросеть».
Отсюда и цена ошибки. Перепутав поверхность, ты меняешь не текст ответа, а способ выдачи прав: AI Studio живёт в пространстве ролей ai.*, API Gateway - в пространстве api-gateway.*, и одно не даёт прав в другом. Платишь за это не багом модели, а сломанным доступом, чужими учётными данными и поддержкой, которая ищет проблему не в том сервисе.
Какие колонки содержит схема ролей
Рабочий инструмент здесь один - таблица «сервис - роль - авторизация - поддержка». Она не заменяет живую документацию, но фиксирует границы, которые на словах путаются за секунду. Колонок ровно четыре: какой сервис, какая минимальная роль, чем авторизуется вызов и куда пойдёт тикет при сбое.
Для AI Studio минимальная IAM-роль на текстовую генерацию, эмбеддинги и классификаторы - ai.languageModels.user; она даёт сервисному аккаунту право звать модель и читать квоты (S6). Выше по иерархии идут ai.viewer (только чтение), ai.editor (полное использование AI-сервисов, включая агентов, дообучение и датасеты) и ai.admin (надмножество прав редактора). Эти ai.* роли отдельны от общих IAM-ролей Yandex Cloud (S6).
У API Gateway - собственное, несвязанное пространство ролей: api-gateway.viewer, api-gateway.editor, api-gateway.admin, api-gateway.auditor, api-gateway.websocketWriter. Они управляют шлюзом и маршрутами, а не доступом к модели; роль ai.* не даёт ни одного права в API Gateway и наоборот (S7). Это и есть материальная причина, по которой «назначим одну роль на всё» не работает.
| Как звучит запрос | Что за ним стоит | Поверхность | Учётные данные |
|---|---|---|---|
yandex ai studio api | вызов генеративной модели | AI Studio, generation-API | yandex ai api key (API-ключ) или IAM-токен |
yandex cloud api yandexgpt | конкретная модель семейства | YandexGPT в AI Studio | те же роли ai.* |
yandex cloud gpt api | GPT-подобная генерация текста | YandexGPT в AI Studio | те же роли ai.* |
yandex cloud api gateway | публикация HTTP-API | API Gateway | роли api-gateway.*, спецификация OpenAPI |
Колонка «учётные данные» - самая недооценённая. Запрос yandex ai api key ведёт к ключу сервисного аккаунта, который создаётся в консоли AI Studio через «Create API key» (S4). Это учётные данные для модели, а не для шлюза, и обратной силы у них нет.
Формулировок много, развилка одна
Дальше начинается человеческий фактор. Задача приходит к архитектору не схемой, а фразой - от коллеги, из тикета, из чата команды. И фраз этих десяток: латиница, кириллица, транслит «ии/апи», любой порядок слов. Вот характерный разброс, за которым стоит одно и то же намерение «нужна модель Yandex по API».
# одно намерение "модель Yandex по API" - вот как оно приходит api yandex ai yandex ai api yandex api ai яндекс ai api яндекс ии api яндекс ии апи yandex ии api yandex cloud ai api яндекс нейросеть api подключить нейросеть в яндексе как подключить в яндексе нейросеть яндекс яндекс чат бот нейросеть yandex ai studio sdk pip install yandex ai studio sdk
Отдельная оговорка по двум последним строкам. yandex ai studio sdk и pip install yandex ai studio sdk - это ровно то, что человек напечатал, а не подтверждённая команда: документация фиксирует авторизацию через API-ключ или IAM-токен (S4), но пакета с таким именем в PyPI не обещает. Читай их как запрос, который надо распознать, а не как рабочий install. яндекс чат бот нейросеть и подключить нейросеть в яндексе - тем более намерение, а не сервис: за обоими стоит та же развилка «модель или маршрут».
Сам список архитектуру не решает. Он снимает шум формулировок, чтобы дальше сработала таблица ролей. Формулировка - это вход. Роль и ключ - решение.
Почему Gateway не заменяет модель?
Самое частое смешение - считать, что раз через API Gateway проходит трафик, значит он и есть «api для нейросети Yandex». Это не так, и документация это показывает буквально.
Расширение интеграции x-yc-apigateway-integration поддерживает типы бэкенда dummy, cloud_functions, http, object_storage, cloud_datasphere, cloud_datastreams, serverless_containers, cloud_ymq, cloud_ydb и swagger (S8). Среди них нет ни yandexgpt, ни ai_studio. Чтобы дотянуться от шлюза до модели, ты маршрутизируешь запрос через http или через cloud_functions - то есть шлюз и сервис модели остаются архитектурно раздельными компонентами.
Авторизация усиливает это разделение. По умолчанию API Gateway не использует IAM Yandex Cloud для проверки входящих HTTP-запросов от конечного клиента: он опирается на security-схемы OpenAPI или на кастомное расширение x-yc-apigateway-authorizer:function, которое зовёт Cloud Function, возвращающую {"isAuthorized": true/false} (S7). Это авторизация уровня приложения, отдельная от ролевой модели IAM, которой живёт AI Studio.
Практический вывод: если в твоей схеме API Gateway стоит там, где должна быть роль ai.languageModels.user, авторизации просто не к чему привязаться. Это и есть признак смешанных компонентов.
Здесь же закрою развилку, оговорённую в начале. Если задача не «поднять облачную роль», а «звать внешние модели по одному ключу», логика границ та же, но учётные данные другие: provod.ai отдаёт API, совместимый с SDK OpenAI и Anthropic, - меняешь ключ и base_url, код не переписываешь.
# совместимый каталог: тот же SDK OpenAI, другой ключ и base\_url from openai import OpenAI client = OpenAI(api\_key="<PROVOD\_KEY>", base\_url="https://api.provod.ai/v1")
Держи это как параллельную опцию, а не как элемент схемы Yandex Cloud: смешивать base_url внешнего каталога с ролями ai.* - та же ошибка границ, что и путать Gateway с моделью.
Как минимальный пример проверяет выбранную поверхность?
Метод простой: сверить документацию и выполнить минимальный пример на той поверхности, которую ты выбрал. Если пример не воспроизводится или требует другой ключ - поверхность выбрана неверно. Ниже два структурно разных «минимальных примера», и сама их разность - доказательство того, что это разные компоненты.
Вызов AI Studio API (API v3) авторизуется IAM-токеном в заголовке Authorization, а папка передаётся отдельно в заголовке x-folder-id; для других версий API папка идёт полем folderId в теле запроса (S4, S5). Альтернатива IAM-токену - API-ключ сервисного аккаунта.
# минимальный вызов AI Studio (generation-API, v3): ключ/токен + папка # точный endpoint модели см. в документации AI Studio curl -H "Authorization: Bearer <IAM\_TOKEN>" \
-H "x-folder-id: <FOLDER\_ID>" \
-H "Content-Type: application/json" \
-d '{"modelUri":"gpt://<FOLDER\_ID>/yandexgpt-lite","messages":[]}' \
<AI\_STUDIO\_GENERATION\_ENDPOINT>
Минимальный API Gateway - это вообще не про ключ модели. Ему нужен OpenAPI 3.0-спек хотя бы с одним путём и (для приватных бэкендов) сервисный аккаунт с правом звать этот бэкенд (S9). Ни папки, ни ключа модели здесь нет - другая поверхность, другой минимум.
# минимальный API Gateway: один путь + интеграция, без понятия "модель" openapi: 3.0.0 info: {title: minimal, version: "1.0"} paths: /ping: get: x-yc-apigateway-integration: type: cloud\_functions function\_id: <FUNCTION\_ID> service\_account\_id: <SA\_ID>
Разность примеров - и есть карта границ. AI Studio требует папку плюс ключ или IAM-токен. API Gateway требует спецификацию и право на бэкенд. Если ты пытался вставить x-folder-id в шлюз или спецификацию OpenAPI в вызов модели, схема сообщает тебе об ошибке раньше, чем прод.
Оговорка по доверию, без неё было бы нечестно. Ни один вызов AI Studio и ни одно развёртывание API Gateway для этого материала не выполнялись: всё выше - документированная процедура, а не воспроизведённый прогон. Часть страниц aistudio.yandex.ru к тому же отдаёт CAPTCHA автоматическим запросам, поэтому формулировки сверялись по индексируемым версиям тех же официальных страниц. Читать это стоит как «сверено по документации на 2026-07-18», а не как «проверено на практике».
Что эта схема не решает
Карта границ полезна ровно до тех пор, пока ты не начал выдавать её за источник истины. Список ролей отражает страницу roles-reference на 2026-07-18; Yandex Cloud периодически добавляет и переименовывает гранулярные роли, поэтому точные имена нужно перепроверять в консоли перед тем, как зашивать их в рунбук поддержки. То же с ребрендингом: legacy-пути foundation-models теперь 301-редиректят на aistudio.yandex.ru, и любую такую ссылку считаем устаревшей, а не авторитетной.
Схема не заменяет реализацию. Она говорит, какому сервису какая роль и какой ключ, но не пишет за тебя дообучение, ассистента или маршрут. Квоты и лимиты она тоже не отменяет: точных чисел по ним в цитируемой документации нет, поэтому нет их и здесь. И она не про внешние модели - совместимый API-каталог живёт отдельным слоем.
Честно и про function-authorizer: это один из паттернов авторизации, не единственный. Если у тебя в API Gateway достаточно security-схем OpenAPI, кастомная функция может быть лишней. Схема фиксирует границу компонентов, а не предписывает единственный способ внутри каждого.
FAQ
«api yandex ai», «yandex ai api» и «yandex api ai» - это разные сервисы?
Нет, это разные написания одного намерения. Сервис определяется не порядком слов, а тем, что тебе нужно: модель (AI Studio + YandexGPT) или маршрут (API Gateway).
Где взять yandex ai api key?
API-ключ сервисного аккаунта создаётся в консоли AI Studio через «Create API key» (S4). Это ключ для вызова модели, он не даёт прав в API Gateway.
YandexGPT - это отдельная консоль?
Нет. YandexGPT - семейство моделей (Lite, Pro и версии), вызываемое через generation-API AI Studio (S2). Запрос yandex cloud gpt api ведёт в ту же поверхность.
Можно поднять модель прямо на API Gateway?
Нет нативно. Среди типов бэкенда нет модели; дотянуться до AI Studio можно только через http или cloud_functions (S8, S9).
Что подсказать пользователю с запросом подключить нейросеть в яндексе?
Сначала сними неоднозначность: нужна генерация (AI Studio, роль ai.languageModels.user) или публикация HTTP-API (API Gateway, роли api-gateway.*). Дальше выдавай ключ под выбранную поверхность.
Когда границы Yandex Cloud разведены, а внешние модели всё-таки нужны, это отдельный слой - и закрывается он не ролью, а совместимым каталогом. Архитектору здесь важна не витрина моделей, а та же административная механика, что и в облаке: общие рабочие пространства с общими ключами, единый баланс организации, контроль доступа и расходов, договор со счётом и закрывающими.
provod.ai — единая AI-платформа для текста, кода и медиа
Не нужно оплачивать и поддерживать отдельный сервис для каждого формата: веб-интерфейс, API, мультимедийный редактор и командный баланс работают в одном контуре.
В одном каталоге — актуальные модели для текста и медиа: GPT от OpenAI, Claude от Anthropic, Gemini от Google, Grok от xAI, DeepSeek, Qwen, GLM, Kimi и MiniMax; для изображений — Nano Banana 2 Pro и GPT Image; для видео — последние версии Seedance, Kling, Veo и Google Omni. Также доступны модели для reasoning, поиска, документов, эмбеддингов, музыки и аудио.
И текстовые запросы, и медиагенерации тарифицируются без собственной наценки provod.ai: стоимость соответствует официальным ценам поставщиков 1:1.
Соберите свой мультимодальный сценарий: форма регистрации · цены на модели · защита данных по 152-ФЗ · API и интеграции
Источники
- Yandex Cloud, AI Studio docs, доступ 2026-07-18 - роль продуктовой поверхности и авторизация (S1, S4, S5).
- Yandex Cloud, AI Studio concepts/generation/models, доступ 2026-07-18 - YandexGPT как семейство моделей (S2).
- Yandex Cloud, API Gateway docs, доступ 2026-07-18 - шлюз как слой маршрутизации без модели (S3).
- Yandex Cloud, IAM roles-reference, доступ 2026-07-18 - роли
ai.*иapi-gateway.*(S6, S7). - Yandex Cloud, API Gateway extensions (function-authorizer, cloud-functions), доступ 2026-07-18 - авторизация и типы бэкенда (S7, S8).
- Yandex Cloud, API Gateway quickstart, доступ 2026-07-18 - минимальное развёртывание (S9).
- Проверенные факты продукта provod.ai, 2026-07-15.