# 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.

```bash
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 каталога (для пользовательского аккаунта) |

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

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

## Нюансы

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

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

- [Расшифровать длинную запись разговора](https://mcp-everything.ru/integrations/yandex-speechkit/scenarios/rasshifrovat-dlinnuyu-zapis-razgovora.md)
- [Озвучить текст](https://mcp-everything.ru/integrations/yandex-speechkit/scenarios/ozvuchit-tekst.md)

---

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