Аутентификация в API AI Studio
Для запросов к API моделей и агентов AI Studio, SpeechKit, Yandex Search API, Translate и Vision OCR используйте API-ключ или IAM-токен. Доступные способы зависят от операции и аккаунта, от имени которого выполняется запрос.
Если вы работаете только в интерфейсе AI Studio, получать ключ или токен не нужно. Убедитесь, что вашему аккаунту назначены необходимые роли.
Выберите способ аутентификации
API-ключ — это простой способ начать работу с API AI Studio. Он подойдет, если нужные операции поддерживают API-ключи или у приложения нет возможности автоматически получать IAM-токены. API-ключ всегда принадлежит сервисному аккаунту и не может использоваться для аутентификации от имени пользователя. Если вы создадите API-ключ в интерфейсе AI Studio, для вас автоматически будет создан и сервисный аккаунт с ролями для работы в AI Studio. Как создать API-ключ.
IAM-токен — короткоживущие учетные данные пользовательского или сервисного аккаунта. Это рекомендуемый способ, если вы можете обновлять токен автоматически. Также подходит для экспериментов от своего имени. Получить IAM-токен.
Сервисный аккаунт — отдельный аккаунт, от имени которого приложение обращается к API. Сервисный аккаунт может аутентифицироваться и с API-ключом, и с IAM-токеном.
Перед получением учетных данных проверьте исключения.
|
Задача |
Что использовать |
|
Работа с моделями в рамках подписки |
IAM-токен пользователя, на которого оформлена подписка. API-ключ и IAM-токен сервисного аккаунта для подписки не подходят. Нужны также специальный эндпоинт и модель из подписки — подробнее. |
|
Асинхронное распознавание речи в SpeechKit API v2 или v3 |
API-ключ или IAM-токен сервисного аккаунта. Пользовательский аккаунт для этой операции не подходит. |
|
Создание, изменение и удаление рабочих процессов Workflows |
IAM-токен. API-ключ поддерживается только для методов ресурса |
|
Управление MCP-серверами через MCP Gateway API |
IAM-токен. Для обращения к уже созданному приватному MCP-серверу можно использовать и API-ключ с областью действия |
Аутентификация с API-ключом
-
Создайте API-ключ в интерфейсе AI Studio. Можно создать ключ вместе с новым сервисным аккаунтом или для существующего аккаунта.
-
Убедитесь, что сервисному аккаунту назначены роли для нужных операций, а область действия ключа разрешает их выполнять.
-
В каждом запросе передавайте секретную часть ключа, а не его идентификатор:
Authorization: Api-Key <API-ключ>
Если вы используете OpenAI SDK, передавайте секретную часть ключа в параметре api_key клиента. Заголовок SDK сформирует самостоятельно. Примеры настройки клиента приведены в инструкциях по работе с моделями.
Срок действия задается при создании ключа. Чтобы продолжить работу после его истечения, создайте новый ключ и замените значение в приложении.
Аутентификация с IAM-токеном
IAM-токен действует не больше 12 часов. Короткий срок действия снижает риск использования утекших учетных данных. Для федеративного или локального аккаунта токен может перестать действовать раньше, если завершится сессия входа.
Для получения токена через CLI установите и настройте Yandex Cloud CLI.
-
Получите IAM-токен: для разового запроса можно использовать свой аккаунт, для приложения — сервисный аккаунт. Учитывайте исключения в таблице выше.
-
Убедитесь, что аккаунту назначены роли для нужных операций.
-
В каждом запросе передавайте токен:
Authorization: Bearer <IAM-токен>
Если вы используете OpenAI SDK, убедитесь, что он отправляет IAM-токен в заголовке Authorization: Bearer <IAM-токен>.
Для непрерывной работы приложения настройте автоматическое получение нового IAM-токена до истечения срока текущего. Например, Yandex AI Studio SDK поддерживает аутентификацию через профиль CLI и получение токена из метаданных виртуальной машины. Если вы передали токен строкой, заменять его в приложении нужно самостоятельно.
Работа по подписке
Чтобы использовать модели в рамках подписки:
- Получите IAM-токен пользователя, на которого оформлена подписка, и передавайте его в заголовке
Authorization: Bearer <IAM-токен>. - Укажите эндпоинт
https://apps.ai.api.cloud.yandex.net/v1. - Выберите модель, доступную в подписке, и каталог в облаке, в котором оформлена подписка.
Использование IAM-токена само по себе не включает подписочную тарификацию. Запросы к эндпоинту https://ai.api.cloud.yandex.net/v1 оплачиваются отдельно по потреблению.
Подписка предоставляет доступ к определенным моделям и сценариям, а не ко всем API платформы. Готовые настройки клиентов приведены в разделе Подписки для разработчиков.
Роли и каталог
Роли определяют, какие операции разрешено выполнять аккаунту. Выберите необходимые роли в разделе Управление доступом. Для API-ключа дополнительно проверяется его область действия.
При создании ключа с новым сервисным аккаунтом в интерфейсе AI Studio роли назначаются автоматически. Для существующего аккаунта проверьте их самостоятельно. Изменить роли можно в разделе Доступ → Права доступа — инструкция.
Для запросов к API может понадобиться идентификатор каталога. Скопируйте его из интерфейса AI Studio. При запросах от имени сервисного аккаунта к Translate и Vision OCR используется каталог этого аккаунта.
Как передавать идентификатор каталога в запросе
В примерах ниже замените <идентификатор_каталога> на значение, которое вы скопировали из интерфейса AI Studio. Добавьте это значение в запрос: в заголовок, поле тела запроса или URI модели в зависимости от API.
|
API |
Как передать идентификатор |
|
API моделей AI Studio |
Подставьте значение в URI модели, например |
|
SpeechKit API v1 и v2 |
При запросе от пользовательского аккаунта запишите значение в параметр |
|
SpeechKit API v3 |
Добавьте к запросу заголовок |
|
Yandex Search API v2 |
В теле REST-запроса укажите |
|
Translate API v2 |
При запросе от пользовательского аккаунта укажите в теле REST-запроса |
|
Vision OCR |
При запросе от пользовательского аккаунта добавьте заголовок |
Если запрос не выполняется
- Проверьте, что ключ или токен не просрочен, в заголовке указан нужный префикс, а вместо секретной части API-ключа не передан его идентификатор.
- Проверьте роли аккаунта и каталог. Для API-ключа дополнительно проверьте его область действия.
- Если операция требует сервисный аккаунт, используйте учетные данные этого аккаунта.
- При работе по подписке проверьте владельца токена, эндпоинт, модель и облако подписки. Если лимит подписки не уменьшается, а за запросы списываются средства, воспользуйтесь проверками настроек.
Для разбора конкретной ошибки используйте разделы API моделей, SpeechKit или Yandex Search API.
Полезные ссылки
- IAM-токен: использование и срок действия.
- API-ключи: области и срок действия.
- Сервисные аккаунты.
- Как устроено управление доступом в IAM.
- Что делать при компрометации учетных данных.
- Настройка аутентификации в Yandex AI Studio SDK.
- Использование моделей по подписке.
Каталог — пространство, в котором содержатся ресурсы Yandex Cloud. Для аутентификации в AI Studio необходим идентификатор каталога. Чтобы его получить, в интерфейсе AI Studio наведите указатель на название каталога, расположенное в верхней части экрана, и нажмите
