Как расшифровать аудио через AssemblyAI API и дождаться completed

Перед внедрением зафиксируйте поколение API или SDK, speech model, язык, регион и формат аудио. Каталог моделей и совместимость функций меняются. Постоянный ASSEMBLYAI_API_KEY держите на backend или в менеджере секретов; в клиентское приложение допустим только специально созданный временный streaming token.

Подтверждённые данные

• Ключ передаётся в заголовке authorization без Bearer.
• Локальные байты загружают на /v2/upload, затем upload_url передают как audio_url.
• GET /v2/transcript/{id} опрашивают до completed либо error.
• Документация указывает до 5 ГБ для /v2/transcript, до 2,2 ГБ для /v2/upload и длительность 160 мс–10 часов.

AssemblyAI разделяет pre-recorded, real-time и Sync STT. Первый режим создаёт асинхронный transcript, streaming работает в WebSocket-сессии, а Sync предназначен для короткого завершённого клипа. У них разные endpoints, состояния и ограничения; переносить параметры между режимами без проверки нельзя.

Подготовка контрольного файла

1. Создайте обезличенную запись с известным текстом. Для диаризации нужны известные границы и достаточная речь каждого участника; для тональности — заранее размеченные предложения.
2. Выполните ffprobe и запишите container, codec, sample rate, channels и duration. Расширение .wav или .mp3 не гарантирует фактическое содержимое.
3. Составьте эталон: обязательные слова, язык, число спикеров, интервалы или ожидаемые captions.
4. Для A/B-теста используйте идентичные байты и меняйте один параметр. Иначе разницу нельзя отнести к модели, prompt или keyterms.
5. Не используйте реальные платёжные, медицинские и паспортные сведения. Синтетический секрет должен легко находиться точным поиском.

file: control.wav
duration_seconds: 30
sample_rate: 16000
channels: 1
expected_language: ru
expected_phrase: "заказ сорок два готов"
contains_real_personal_data: false

Это форма карточки, а не универсальные требования. Заполните её фактическими данными файла. Для streaming добавьте размер chunk, период отправки и момент намеренного обрыва.

Настройка по шагам

1. Создайте отдельный ключ тестовой среды и экспортируйте его как ASSEMBLYAI_API_KEY. Не печатайте значение в CI и shell history.
2. Выберите один режим: pre-recorded, streaming или Sync. Сверьте endpoint, модель и ограничения длительности.
3. Запустите минимальный шаблон ниже без автоматических retry. Так сохранятся исходный HTTP-код и тело ошибки.
4. Для async различайте completed, error и промежуточные статусы. Ограничьте polling общим deadline и добавьте backoff.
5. Разберите только документированные поля. Отсутствующее поле — ошибка контракта, а не пустая строка.
6. Сравните ответ с эталоном: Контрольная запись возвращает completed, непустой text, сохранённый id и ожидаемую фразу; error никогда не выдаётся пользователю.
7. Выполните отрицательный тест: неверный формат, истёкший token, неподдерживаемая длина или повторный webhook. Система обязана отказать предсказуемо.

Готовый шаблон

upload=$(curl -sS -X POST https://api.assemblyai.com/v2/upload -H 'authorization: KEY' --data-binary @control.wav)
# передайте upload_url в POST /v2/transcript и опрашивайте GET /v2/transcript/{id}

Идентификаторы и файлы заменяются значениями из текущей документации и вашей среды. Никогда не вставляйте рабочий ключ в статью или frontend. После теста сохраните transcript id, request metadata и исходный JSON без секрета.

Вход и ожидаемый выход

Контрольный вход должен быть реалистичным для продукта: голосовое сообщение, звонок, встреча или ролик. Один диктор в тишине не проверяет контакт-центр, а десятисекундный диалог не показывает устойчивость speaker labels. Подготовьте 20–50 обезличенных кейсов, включая шум, акцент, паузы и редкие термины.

Ожидаемый выход: Контрольная запись возвращает completed, непустой text, сохранённый id и ожидаемую фразу; error никогда не выдаётся пользователю.

Проверка текста включает не только непустое поле. Считайте WER или долю обязательных фраз, отдельно фиксируйте ошибки имён, сумм и артикулов. Для streaming сверяйте отсутствие дублей partial/final, для subtitles — порядок таймкодов, для webhook — идемпотентность.

Критерии приёмки

• upload_url получен
• id сохранён
• completed подтверждён
• text непустой
• эталон совпал

Сохраняйте model used, language code, transcript id, длительность, confidence, latency и итог PASS/FAIL. Порог confidence определяйте на своей размеченной выборке: универсального безопасного значения для всех микрофонов и языков нет.