Yandex SpeechKit API: Распознать короткое голосовое сообщение

Сценарий из mcp-everything. Актуально на 2026-10-24.

Голосовые сообщения в боте, голосовой поиск, короткие команды — аудио до 30 секунд.

1. Создай сервисный аккаунт с ролью ai.speechkit-stt.user и API-ключ; передавай его в заголовке Authorization: Api-Key <ключ>. С пользовательским аккаунтом (IAM-токен) нужен ещё параметр folderId.
2. Отправь аудио: POST /speech/v1/stt:recognize на stt.api.cloud.yandex.net — в теле двоичное содержимое файла (до 1 МБ, до 30 секунд, один канал), в строке запроса lang = ru-RU и format.
3. Голосовые из Telegram и большинства мессенджеров — OggOpus, это формат по умолчанию. Для «сырого» PCM передай format = lpcm и sampleRateHertz.
4. Распознанный текст — в поле result. Числа по умолчанию приходят цифрами; число тарифицированных единиц — в заголовке YaCloud-Billing-Units.

curl -X POST "https://stt.api.cloud.yandex.net/speech/v1/stt:recognize?lang=ru-RU&format=oggopus" \
  -H "Authorization: Api-Key $YANDEX_API_KEY" \
  --data-binary @voice.ogg
# → {"result": "привет хочу заказать доставку на завтра"}

Базовые URL

• Синхронное распознавание: https://stt.api.cloud.yandex.net
• Асинхронное распознавание: https://transcribe.api.cloud.yandex.net
• Синтез речи: https://tts.api.cloud.yandex.net
• Операции: https://operation.api.cloud.yandex.net

Авторизация

Тип: Bearer-токен

• IAM-токен: Authorization: Bearer <IAM-токен>
• API-ключ сервисного аккаунта: Authorization: Api-Key <API-ключ>

При авторизации пользовательским аккаунтом нужен параметр folderId; для сервисного аккаунта он не используется. Асинхронное распознавание доступно только сервисным аккаунтам (роли ai.speechkit-stt.user и storage.uploader).

Методы сценария

POST /speech/v1/stt:recognize — Синхронное распознавание

Тело — двоичное содержимое аудиофайла: до 1 МБ, до 30 секунд, один канал.

Параметр	Где	Тип	Обяз.	Описание
lang	query	string	нет	Язык распознавания, по умолчанию ru-RU
topic	query	string	нет	Языковая модель, по умолчанию general
profanityFilter	query	boolean	нет	Исключать ненормативную лексику, по умолчанию false
rawResults	query	boolean	нет	Числа прописью (true) или цифрами (false, по умолчанию)
format	query	string	нет	lpcm (без WAV-заголовка) или oggopus (по умолчанию)
sampleRateHertz	query	integer	нет	48000 (по умолчанию), 16000 или 8000; только для lpcm
folderId	query	string	нет	ID каталога (для пользовательского аккаунта)

Пример ответа:

HTTP/1.1 200 OK
YaCloud-Billing-Units: 15
{
  "result": "твой номер 212-85-06"
}

Нюансы

• Число тарифицируемых единиц возвращается в заголовке ответа YaCloud-Billing-Units.
• Для lpcm передаётся «сырое» аудио без WAV-заголовка; частота задаётся явно.
• Для OggOpus и MP3 число каналов не указывается — оно есть в самом файле.
• Для асинхронного распознавания файл сначала загружают в бакет Object Storage.

Другие сценарии

• Расшифровать длинную запись разговора
• Озвучить текст

---

Если этого недостаточно — официальная документация: https://aistudio.yandex.ru/ru/docs/speechkit/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandex-speechkit.md