Голосовой ввод

Распознавание речи: приложение записывает короткую фразу, сервер возвращает её текстом. Ручка одна и ни к какому экрану не привязана: текст дальше уходит туда, куда его ввели бы с клавиатуры, например в поиск по каталогу.

Распознать запись

Запись передаётся файлом в поле audio формы multipart/form-data:

curl -X POST "$BASE_URL/v1/speech/transcriptions?locale=ru" \
  -H "Authorization: Bearer $TOKEN" \
  -F "audio=@speech.m4a;type=audio/mp4"

Ответ 200:

{ "text": "Неоновый город.", "language": "ru" }

• text - расшифровка как есть: одной строкой, с заглавными буквами и знаками препинания, которые поставила модель, любой длины. Сервер её не правит и не укорачивает.
• language - код языка, который услышала модель (ru, en, …). Может отличаться от locale и может быть null.
• locale - язык, на котором говорит человек: передавай язык интерфейса (по умолчанию ru, как у остальных ручек; en-US читается как en). Если модель такого языка не знает, она определяет его сама.
• Речь не распознана - это не ошибка: ответ 200, text пустой. Показывай «не расслышали», а не сбой.
• Запись на сервере не хранится, идентификатора у расшифровки нет: повторный запрос распознаёт заново.

Что принимается

Формат	audio/mp4 (m4a, AAC), audio/mpeg (mp3), audio/wav, audio/webm. Тип берётся из Content-Type части формы, а сам файл обязан читаться как один из этих форматов
Длина	не больше 15 секунд
Размер	не больше 512 КиБ (524 288 байт)

Под размер проходит и несжатая запись: 15 секунд WAV 16 кГц моно занимают 480 КиБ, AAC или Opus той же длины в разы меньше. Пиши моно 16 кГц: стерео и 44,1 кГц только увеличивают файл, и несжатая запись с ними в предел уже не поместится. Ogg (в том числе Opus в ogg) не принимается.

Ошибки

Общий формат тот же, что у остальных ручек.

HTTP	code	Когда	Что делать
401	auth_required	нет токена или он протух	обновить токен и повторить
403	registration_required	запрос от гостя	отправить на регистрацию
413	payload_too_large	запись длиннее или тяжелее предела	остановить запись раньше; тот же файл не повторять
415	unsupported_media_type	формат не из списка, либо файл не читается как звук	это ошибка сборки приложения, не пользователя
422	validation_error	в форме нет поля audio	починить запрос
429	rate_limited	слишком часто	подождать Retry-After секунд
503	provider_unavailable	распознавание сейчас недоступно или не уложилось во время	предложить ввести текст руками; повторить можно

Гостю распознавание закрыто, потому что каждый запрос стоит сервису денег, а кредитов не списывает. Лимит запросов свой, на пользователя, и заметно уже остальных: рассчитан на то, что человек нажал кнопку микрофона и договорил, а не на отправку фрагментов по мере записи.

Пример: найти эффект голосом

Два запроса: распознать, затем искать обычным поиском.

TEXT=$(curl -s -X POST "$BASE_URL/v1/speech/transcriptions?locale=ru" \
  -H "Authorization: Bearer $TOKEN" \
  -F "audio=@speech.m4a;type=audio/mp4" | jq -r .text)

curl -G "$BASE_URL/v1/effects" --data-urlencode "search=$TEXT" -d "locale=ru"

Между шагами покажи text в строке поиска: человек видит, что услышал сервер, и может поправить руками. При пустом text второй запрос не нужен: search без текста вернёт весь каталог, а не «ничего не найдено». search принимает не больше 300 символов, расшифровку длиннее обрежь по границе слова.