Как настроить webhook AssemblyAI для готовой расшифровки

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

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

• URL задаётся webhook_url при создании transcription.
• Endpoint должен быть доступен серверам AssemblyAI.
• Python SDK использует set_webhook и submit без ожидания completed.
• Streaming-webhooks документированы отдельно.

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. Сравните ответ с эталоном: Один transcript id обрабатывается ровно один раз даже после повтора; итог читается авторизованным GET.
7. Выполните отрицательный тест: неверный формат, истёкший token, неподдерживаемая длина или повторный webhook. Система обязана отказать предсказуемо.

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

tid=request.json['transcript_id']
if already_processed(tid): return ('ok',200)
r=requests.get(f'https://api.assemblyai.com/v2/transcript/{tid}',headers=HEADERS)
save_once(tid,r.json())

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

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

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

Ожидаемый выход: Один transcript id обрабатывается ровно один раз даже после повтора; итог читается авторизованным GET.

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

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

• endpoint доступен
• id валидирован
• GET авторизован
• идемпотентность есть
• повтор протестирован

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