speech-recognition
Войти
← На главную

REST API транскрибации аудио и видео

REST API позволяет встроить автоматическую транскрибацию аудио и видео в собственные приложения и сервисы. С помощью API можно создавать задачи на распознавание речи, загружать файлы напрямую или передавать ссылки на записи — с Яндекс.Диска, из VK Видео и YouTube, получать текст расшифровки с тайм-кодами, разделение по спикерам с ролями и AI-саммари, а также отслеживать статус обработки — опросом или через webhook. Для распознавания в реальном времени есть отдельный WebSocket-эндпоинт живых субтитров: поток аудио превращается в текст по мере речи, с переводом на другой язык при необходимости.

Авторизация выполняется по API-ключу: он создаётся в разделе «API-ключи» личного кабинета. Запросы расходуют тот же баланс минут, что и задачи на сайте, — первые 45 бесплатных минут можно потратить на тестирование интеграции. Ниже — полное описание методов, параметров и форматов ответов с примерами запросов, поддерживаемые форматы файлов, режимы обработки и типовые сценарии использования API. Готовые примеры кода на Python, PHP, Node.js, Go и C# — на странице примеров интеграции.

Аутентификация

Передавайте ключ в заголовке Authorization. Базовый адрес — https://speech-recognition.ru.

Authorization: Bearer sk_live_ваш_ключ

Как работает API

  1. Создаёте задачу — в ответ приходит ссылка для загрузки файла.
  2. Загружаете аудио PUT-запросом по этой ссылке.
  3. Запускаете обработку.
  4. Опрашиваете статус или ждёте callback на свой адрес.

Либо короче: создаёте задачу сразу со ссылкой на запись (url) — шаги 2–3 не нужны, скачивание берёт на себя сервис.

Создание задачи

POST/api/v1/jobs

Создать задачу. Поля: fileName, fileSize (байт) — либо вместо них url (Яндекс.Диск, VK Видео, YouTube или прямая ссылка на файл); mode — DIARIZED_SUMMARY (по умолчанию: текст + роли + саммари) или TRANSCRIPT (только текст); summaryTemplate — формат саммари: default (универсальное), meeting (протокол встречи), lecture (конспект лекции), interview (карточка интервью), sales (карточка звонка), social (пост для соцсетей); callbackUrl — необязательный адрес для уведомления о готовности.

curl -X POST https://speech-recognition.ru/api/v1/jobs \
  -H "Authorization: Bearer sk_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "meeting.mp3",
    "fileSize": 5242880,
    "mode": "DIARIZED_SUMMARY",
    "summaryTemplate": "meeting",
    "callbackUrl": "https://ваш-сервер.ru/webhook"
  }'

# Ответ:
{ "jobId": "clx…", "uploadUrl": "https://s3.speech-recognition.ru/…" }

# Или по ссылке — задача сразу уходит в обработку:
curl -X POST https://speech-recognition.ru/api/v1/jobs \
  -H "Authorization: Bearer sk_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://disk.yandex.ru/i/abc123" }'

# Ответ:
{ "jobId": "clx…" }

Загрузка файла

PUT{uploadUrl}

Загрузить файл по полученной ссылке (действует 1 час).

curl -X PUT "{uploadUrl}" --data-binary @meeting.mp3

Запуск обработки

POST/api/v1/jobs/{jobId}/start

Запустить распознавание. Минуты списываются по длительности записи.

curl -X POST https://speech-recognition.ru/api/v1/jobs/{jobId}/start \
  -H "Authorization: Bearer sk_live_ваш_ключ"

Получение результата

GET/api/v1/jobs/{jobId}

Статус и результат. Статусы: QUEUED, DOWNLOADING (для задач по ссылке), TRANSCRIBING, SUMMARIZING, DONE, FAILED.

curl https://speech-recognition.ru/api/v1/jobs/{jobId} \
  -H "Authorization: Bearer sk_live_ваш_ключ"

# Ответ при DONE:
{
  "job": {
    "id": "clx…",
    "status": "DONE",
    "durationSeconds": 634,
    "chargedSeconds": 660,
    "trimStartSeconds": null,
    "trimEndSeconds": null,
    "parentJobId": null,
    "continuationJobId": null,
    "result": {
      "text": "Полный текст расшифровки…",
      "segments": [
        { "start": 0.0, "end": 4.2, "text": "…", "speaker": "SPEAKER_00" }
      ],
      "speakerRoles": { "SPEAKER_00": "Менеджер", "SPEAKER_01": "Клиент" },
      "summary": "**О чём запись:** …"
    }
  }
}

Поля задачи:

Остальные поля ответа (canTrim, canContinue, sourceAvailableUntil, retryCount, shareToken и подобные) — служебные, нужны личному кабинету и не входят в контракт API: их состав может меняться без предупреждения, не опирайтесь на них в интеграции.

Получение информации об аккаунте

GET/api/v1/account

Баланс аккаунта.

curl https://speech-recognition.ru/api/v1/account \
  -H "Authorization: Bearer sk_live_ваш_ключ"

# Ответ:
{ "email": "…", "balanceSeconds": 18000, "balanceMinutes": 300 }

Webhook (Callback)

Если указан callbackUrl, по завершении мы отправим на него POST с JSON-телом из полей jobId, status, mode, originalFileName, durationSeconds, chargedSeconds, trimStartSeconds, trimEndSeconds, parentJobId, continuationJobId, error и result (text, segments, speakerRoles, summary; null при ошибке). Значения те же, что в GET /api/v1/jobs/{jobId}, идентификатор приходит как jobId; служебных полей кабинета (canRetry и т. п.) в callback нет. Если задача была перезапущена на фрагменте из кабинета, придут его границы, а тайминги сегментов останутся в координатах исходного файла. Продолжение остатка, запущенное из кабинета, — отдельная задача с тем же callbackUrl: придёт свой callback с parentJobId первой части. Ответьте 2xx — иначе доставка считается неуспешной (повторов нет, статус всегда можно опросить).

Живые субтитры (WebSocket)

Распознавание в реальном времени: вы отправляете поток аудио по WebSocket и получаете текст по мере речи — черновые фразы, финальные фразы с тайм-кодами и, при желании, построчный перевод. После завершения сессии запись автоматически уходит в обычную обработку — готовая задача с полной расшифровкой появится в GET /api/v1/jobs и в личном кабинете. Не хотите хранить запись — включите режим noRecording.

Получение токена

POST/api/v1/live/token

Одноразовый токен входа в сессию. Действует 60 секунд и гасится при первом использовании — запрашивайте его непосредственно перед подключением, по токену на сессию.

curl -X POST https://speech-recognition.ru/api/v1/live/token \
  -H "Authorization: Bearer sk_live_ваш_ключ"

# Ответ:
{
  "token": "3f9a…",
  "expiresInSeconds": 60,
  "wsUrl": "wss://speech-recognition.ru/api/live/ws"
}

Подключение и поток аудио

WSwss://speech-recognition.ru/api/live/ws

Первым сообщением отправьте start (текстовый JSON-фрейм). Поле lang — auto либо локаль из списка: ru-RU, en-US, tr-TR, de-DE, es-ES, fr-FR, it-IT, uk-UA; необязательный translateTo (те же локали) включает перевод финальных фраз; noRecording: true — приватный режим: сервер не сохраняет запись и не создаёт задачу пост-обработки.

{ "type": "start", "token": "3f9a…", "lang": "ru-RU", "translateTo": "en-US" }

Минимальный клиент на Node.js:

import WebSocket from 'ws';

const { token, wsUrl } = await fetch('https://speech-recognition.ru/api/v1/live/token', {
  method: 'POST',
  headers: { Authorization: 'Bearer sk_live_ваш_ключ' },
}).then((r) => r.json());

const ws = new WebSocket(wsUrl);
ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'start', token, lang: 'ru-RU' }));
});
ws.on('message', (raw, isBinary) => {
  if (isBinary) return;
  const msg = JSON.parse(String(raw));
  if (msg.ev === 'session') {
    // сессия открыта — с этого момента шлите бинарные PCM-фреймы: ws.send(pcmChunk)
  }
  if (msg.ev === 'partial') process.stdout.write('\r' + msg.text);
  if (msg.ev === 'final') console.log('\r' + msg.text);
  if (msg.ev === 'session_end') console.log('Запись ушла в обработку, jobId:', msg.jobId);
});

События сервера

Все события установленной сессии несут монотонный seq — по нему работает реплей при resume. Ошибки, отправленные до открытия сессии (неверный токен, bad_lang, неудачный resume), приходят без seq; pong его тоже не несёт.

Тарификация и лимиты

Ошибки и ограничения API

Поддерживаемые форматы файлов

API принимает те же форматы, что и загрузка на сайте, — из видео звуковая дорожка извлекается автоматически. Один файл — до 2 ГБ и до 4 часов записи. Подробнее о каждом формате — на отдельных страницах:

Режимы обработки

Режим передаётся в поле mode при создании задачи:

Примеры сценариев использования