REST API транскрибации: как встроить расшифровку в свой продукт

Строите свой сервис, CRM или бота для звонков и упёрлись в то, что распознавание речи — это отдельный проект: своя ASR-модель, очередь задач, диаризация, хранилище файлов. На это уходят недели, которые хочется потратить на продукт, а не на инфраструктуру речи. WonderScribe отдаёт всё это одним REST API: час записи превращается в текст с таймкодами и спикерами примерно за 5 минут, а вы получаете JSON вместо своего пайплайна.

Что за API и как его включить

Это не виджет для сайта, а бэкенд-инструмент: вы отправляете файл или ссылку, в ответ получаете текст, спикеров, таймкод каждого слова и готовое саммари. Документация с живыми примерами лежит на wonderscribe.pro/api.

Включается API одним тумблером — Настройки → вкладка «API» в личном кабинете. Авторизация — заголовок X-API-Key со стабильным ключом: без OAuth, без access/refresh-токенов, которые протухают посреди ночи и роняют интеграцию. Base URL один: https://wonderscribe.pro/api/v1.

Шесть методов, которые закрывают весь цикл

• POST /transcribe — загрузка файла: multipart с полями file, language, num_speakers, prompt, domain, summary_template.
• POST /transcribe-url — то же самое по ссылке: YouTube, VK Видео, RuTube, Дзен, Яндекс.Диск или прямой URL — без скачивания файла на свой сервер.
• GET /tasks/{id} — статус, прогресс обработки и позиция в очереди.
• GET /tasks/{id}/result — сегменты с speaker и таймкодом фразы, words[] с таймкодом каждого слова, список спикеров, саммари, язык и длительность записи.
• GET /tasks/{id}/export?format= — тот же результат сразу в TXT, SRT, VTT или JSON.
• POST /meeting — отправить AI-бота на встречу в Zoom, Google Meet, Teams или Яндекс.Телемост сразу или по расписанию.

Запрос на загрузку выглядит так:

curl -X POST https://wonderscribe.pro/api/v1/transcribe -H "X-API-Key: ваш_ключ" -F "file=@zvonok.mp3" -F "num_speakers=2"

В ответ приходит task_id — по нему дальше опрашивается статус и забирается результат.

Деньги: тариф отдельный от сайта, и он прогрессивный

API считается по собственному ₽-балансу, отдельному от обычной подписки: предоплата, минута — по длительности записи, а не по времени, которое сервис потратил на обработку. Упавшая задача не списывает ничего.

Шкала за календарный месяц устроена как ступени подоходного налога: минуты внутри уже пройденной ступени остаются по своей ставке, переход на следующую происходит автоматически.

• 0–10 000 минут в месяц — 0,50 ₽/мин
• 10 000–50 000 минут — 0,44 ₽/мин
• 50 000–200 000 минут — 0,40 ₽/мин
• свыше 200 000 минут — 0,36 ₽/мин

Накопительно это выглядит так: 10 000 минут в месяц — 5 000 ₽, 50 000 минут — 22 600 ₽, 200 000 минут — 82 600 ₽, 500 000 минут — 190 600 ₽, то есть в среднем 0,38 ₽/мин на таком объёме.

В цену уже включено всё, а не докупается отдельно: диаризация до 6 голосов, пунктуация и таймкоды по фразам и по каждому слову, AI-саммари из 91 шаблона, экспорт в TXT/SRT/VTT/JSON, 99 языков. Пополнить баланс можно от 500 ₽ картой или от 3 000 ₽ по счёту для юрлиц, и он не сгорает.

Если баланс кончился — файл не потеряется

Это пункт документации, из-за которого обычно перестают бояться заводить платный API в продакшн. Если денег на балансе не хватает, POST /transcribe не отклоняет запрос и не удаляет загрузку. Он возвращает status: "awaiting_balance" — файл сохранён, задача создана и ждёт.

Как только баланс пополняется, расшифровка стартует сама в течение нескольких минут — без повторной загрузки файла. Опрашивать её можно тем же GET /tasks/{id}: пока задача ждёт оплаты, в ответе будет флаг awaiting_balance: true, а как только деньги на балансе появились — обычный прогресс.

Для интеграции это значит одно: не нужно городить у себя отдельную очередь «на случай если кончились деньги» — WonderScribe уже держит её сам.

Что ещё важно, кроме списка эндпоинтов

• Idempotency-Key — заголовок с любым уникальным значением от вас. Повторный запрос с тем же ключом, например ретрай после таймаута, вернёт тот же task_id, а не создаст вторую задачу и повторное списание.
• Лимиты: файл до 8 ГБ и до 4 часов записи, до 20 задач одновременно на аккаунт. Запросов в минуту на ключ: 10 загрузок и 60 запросов статуса или результата, сверх этого API отвечает 429.
• Ошибки приходят одним форматом — detail с полями error_code и message, ветвить обработку стоит по error_code, а не по тексту сообщения.
• Скорость: час записи обрабатывается примерно за 5 минут.
• Данные хранятся на серверах в России, обработка соответствует 152-ФЗ.

Запрос по ссылке с защитой от дублей на ретраях:

curl -X POST https://wonderscribe.pro/api/v1/transcribe-url -H "X-API-Key: ваш_ключ" -H "Idempotency-Key: order-48213" -d "{\"url\": \"https://youtu.be/xxxxxxx\"}"

Дальше — обычный опрос: GET /tasks/{id} с тем же заголовком X-API-Key, пока статус не станет завершённым, и запрос результата или экспорта в нужном формате.

Отдельно: потокового распознавания в реальном времени (WebSocket-стрим прямо во время разговора) в API пока нет — в документации на это честно стоит пометка «скоро». Если сценарий держится именно на live-транскрипции, закладывайте это в план заранее, а не в момент интеграции.

Как начать

Ключ включается в кабинете за минуту: Настройки → вкладка «API» → тумблер. Дальше — документация с живыми примерами на wonderscribe.pro/api, туда стоит нести первый тестовый запрос.

На бесплатном тарифе доступно 30 минут расшифровки в месяц с полным набором функций — этого достаточно, чтобы прогнать пилотную интеграцию и увидеть реальный JSON-ответ, прежде чем закладывать API в архитектуру продукта.

Попробовать бесплатно

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