Управление Яндекс.Станцией программно — задача, с которой сталкиваются разработчики умных домов, создатели навыков (диалогов) и энтузиасты автоматизации. На официального публичного REST API для прямого управления колонкой (включение музыки, громкость, TTS) у Яндекса не существует. Однако есть несколько рабочих подходов: от локального API (через Home Assistant) до облачных сценариев и навыков Алисы.

В этой статье мы подробно разберем все актуальные способы «отправить запрос на станцию», их плюсы, минусы и примеры реализации.

Локальное управление через Home Assistant (Проект YandexStation)

На данный момент самый надежный и функциональный способ управлять станцией локально — это использование компонента AlexxIT/YandexStation для Home Assistant. Он реализует обратную инженерию локального протокола колонок.

Ключевые параметры конфигурации

Для работы интеграции требуются три основных параметра (в примерах скрыты маской ):

• OAUTH_TOKEN — OAuth-токен Яндекса (получается через https://oauth.yandex.ru/authorize?response_type=token&client_id=).
• DEVICE_ID — Идентификатор устройства. Найти его можно в приложении «Яндекс» → Устройства → Станция → Настройки (шестеренка) → Идентификатор устройства (выглядит как ).
• HTTP_HOST, Хост и порт локального сервера интеграции (по умолчанию localhost:8001 или ).

Отправка команды TTS (Говорящая станция)

Чтобы заставить станцию произнести текст, используется сервис media_player.play_media с особым форматом media_content_type.

# Пример вызова сервиса в Home Assistant (YAML/Automation)
service: media_player.play_media
target:
 entity_id: media_player.yandex_station_* # Ваш entity_id
data:
 media_content_type: "dialog:my_custom_dialog:tag_*"
 media_content_id: "Текст, который должна сказать Алиса"

Важный нюанс формата media_content_type:

В media_content_type вы должны указать имя своего Яндекс.Диалога через двоеточие без пробелов. Регистр неважен. И через второе двоеточие некий тег диалога, чтоб потом в автоматизации понять, на какой вопрос вам пришёл ответ.

• dialog: — фиксированный префикс.
• my_custom_dialog — имя вашего навыка (диалога) в Консоли разработчика.
• tag_* — произвольный тег для корреляции запроса и ответа.

Отправка видеоконтента (YouTube и др.)

Ранние методы (2019 г.) требовали получения csrf_token через GET frontend.vh.yandex.ru/csrf_token. Сейчас компонент YandexStation делает это автоматически. Достаточно передать ссылку в media_content_id с типом video или music.

Облачное управление через Я.Диалоги (Навыки Алисы)

Если локальный доступ невозможен (станция в другой сети, нет Home Assistant), единственный официальный путь — создание Навыка Алисы (Яндекс.Диалогов).

Архитектура взаимодействия

1. Ваш сервер (Backend) получает событие (вебхук) от Яндекса.
2. Сервер формирует direttive (директиву) ответа.
3. Яндекс выполняет директиву на станции пользователя.

Пример директивы для TTS (прямая речь)

В ответе на запрос пользователя или в пуш-уведомлении (если настроено) вы возвращаете JSON:

{
 "response": {
 "text": "Текст для экрана/лога",
 "tts": "Текст, который проговорит Алиса  с эффектами",
 "end_session": false,
 "directives": {
 "audio_player": {
 "play": {
 "entity_id": "*", # device_id станции, если адресуете конкретную
 "play_request": {
 "type": "TTS",
 "text": "Привет из скрипта!"
 }
 }
 }
 }
 },
 "version": "1.0"
}

Асинхронные запросы (Yandex Cloud / AI Studio)

Для тяжелых генеративных задач (большие тексты, сложная логика) используется асинхронный режим API Яндекс.Облака (Foundation Models / AI Studio).

Запросы к собственным моделям Яндекса можно отправлять в асинхронном режиме. В ответ на асинхронный запрос модель вернет объект Operation, содержащий идентификатор операции, по которому можно отследить ее выполнение и получить результат после того, как генерация завершится.

Пример потока (Python):

import requests
import time

url = "https://llm.api.cloud.yandex.net/foundationModels/v1/completionAsync"
headers = {"Authorization": "Bearer ", "x-folder-id": ""}
payload = {"modelUri": "gpt:///yandexgpt-lite", "completionOptions": {"stream": false}, "messages": [{"role": "user", "text": "Сгенерируй сценарий для станции"}]}

response = requests.post(url, headers=headers, json=payload)
operation_id = response.json["id"] # 

while True:
 op_resp = requests.get(f"https://operation.api.cloud.yandex.net/operations/{operation_id}", headers=headers)
 if op_resp.json.get("done"):
 result = op_resp.json["response"]
 break
 time.sleep(2)

Неофициальные HTTP API (Реверс-инжиниринг)

⚠️ Предупреждение: Использование недокументированных API нарушает Условия использования сервисов Яндекса. Токены живут недолго, эндпоинты меняются без уведомления. Используйте на свой страх и риск.

Библиотека yapi (ebuyan/yapi)

Популярный Python-обертка для управления станцией через облачный протокол (имитация приложения).

Необходимые данные (скрыты):

• OAUTH_TOKEN — Токен доступа (как в локальном API).
• DEVICE_ID — ID станции (*).
• COOKIE / CSRF, Часто требуется извлечение куков из браузера после логина по логину/паролю.

Пример отправки команды «Скажи текст»

# Концептуальный пример (API библиотеки может отличаться)
from yapi import YandexStation

station = YandexStation(oauth_token="", device_id="")

await station.send_command("Скажи привет мир") 

await station.play_media("https://example.com/audio.mp3", media_type="music")

Прямые HTTP запросы (Пример B2B API / Tanker)

В сниппетах встречается пример обращения к b2b-api.go.yandex.ru. Это внутренний API для партнеров (такси, доставка), не для управления умным домом. Приведен здесь только как пример структуры авторизации:

import requests
headers = {"Authorization": "Bearer "} # OAuth токен
params = {"since_datetime": ""} # ISO формат даты

Сценарии «Умный дом» (Yandex Smart Home API)

Если вы производитель устройств или пишете мост (bridge) для нестандартного железа, вы реализуете Smart Home HTTP API (протокол Яндекс.Умный дом).

В этом случае Яндекс шлет запросы к вам (на ваш эндпоинт), а не вы к станции. Но вы можете инициировать изменение состояния через POST /user/devices/action от имени облака, если у вас есть доступ к платформе партнера;

Структура запроса действия (Action)

POST https://dialogs.yandex.net/api/v1/skills/* /callback/* 
Headers: Authorization: Bearer *
{
 "request_id": "*",
 "payload": {
 "devices": [{
 "id": "*", # ID устройства в вашей системе
 "actions": [{
 "type": "devices.capabilities.on_off",
 "state": {"instance": "on", "value": true}
 }]
 }]
 }
}

Сравнительная таблица методов

Пошаговый чек-лист: Что выбрать?

1. Хочу просто сказать текст со скрипта на Raspberry Pi / сервере в одной сети со станцией.
   → Ставьте Home Assistant + Add-on YandexStation. Это «золотой стандарт» на сегодня.
2. Хочу управлять станцией из интернета (с телефона, с другого сервера) без HA.
   → Пишите Навык Алисы (Яндекс.Диалоги). Используйте директивы audio_player.play или smart_home.
3. Нужно сгенерировать сложный ответ нейросетью и проговорить его.
   → Yandex Cloud AI Studio (Async API) → Ваш бэкенд → Навык Алисы → Станция.
4. Нужно быстро прототипировать на Python без HA и модерации навыков.
   → Попробуйте ebuyan/yapi или AlexxIT/YandexStation как библиотеку (standalone). Готовьтесь к поломкам при обновлении прошивки станции.

Безопасность и хранение секретов

Во всех примерах выше чувствительные данные (OAUTH_TOKEN, DEVICE_ID, FOLDER_ID, IAM_TOKEN) заменены на *.

• Никогда не коммитьте токены в Git. Используйте .env файлы и python-dotenv.
• OAuth токены имеют срок жизни. Реализуйте логику рефреша (refresh_token) или используйте сервисные аккаунты (IAM) для облачных API.
• Device ID не секретен, но позволяет адресовать команды именно вашей колонке. Не публикуйте его в открытую вместе с токенами.
• Для локального API (Home Assistant) токен нужен только при первичной настройке для получения локального ключа шифрования. Дальше работает локальный TLS/ключ.

Типичные ошибки и их решения

Ошибка 401 / 403 (Unauthorized / Forbidden)

• Истек срок действия OAUTH_TOKEN или IAM_TOKEN.
• Неправильный DEVICE_ID (скопирован не полностью или с лишними пробелами).
• Для неофициальных API: изменился User-Agent, заголовки или требуется новый csrf_token.

Станция не говорит (TTS не работает)

• Громкость 0 или режим «Не беспокоить».
• Неверный формат media_content_type (пропущен префикс dialog: или имя навыка не совпадает с консолью).
• Станция оффлайн (нет интернета/питания), локальный API не сработает, облачный вернет ошибку доставки.

Асинхронная операция висит вечно

• Проверьте квоты и лимиты в Yandex Cloud Console (Billing).
• Убедитесь, что опрашиваете правильный эндпоинт операции: operation.api.cloud.yandex.net/operations/{id}.

На ландшафт управления Яндекс.Станцией выглядит так:

• Для DIY и Умного дома: Home Assistant + компонент AlexxIT/YandexStation — лучший баланс функционала, стабильности и отсутствия «костылей».
• Для продуктов и сервисов: Только Яндекс.Диалоги (Навыки) + Yandex Cloud (AI/ML). Это единственный путь к легальной публикации и масштабированию.
• Для быстрых хаков: Библиотеки вроде yapi или прямые запросы к локальному API (если вы умеете извлекать ключи), но с пониманием рисков.

Выбирайте метод, исходя из вашей архитектуры: локальная сеть → Local API; распределенная система → Cloud Skills + Webhooks. И помните: токены (OAUTH, IAM, API Keys) — это ключи от вашей цифровой жизни, храните их в секрете (заменяйте на * в логах и конфигах).