Расшифровка аудио и видео API

Краткое практическое введение

Расшифровка аудио и видео превращает речь из аудио- или видеофайла в текст. API подходит для расшифровки встреч, интервью, лекций, звонков, подкастов и видео. Можно передать внешний URL файла или ссылку на YouTube-видео.

Результат можно получить как текст, а также в файле .txt, .docx, .pdf или .srt. Каждый запуск создаёт асинхронную операцию: API сразу вернёт её id и стартовый статус, а готовый результат нужно получить отдельной проверкой.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Запрос создаёт новую операцию и сразу возвращает её id и стартовый статус.
• Выполнение асинхронное.

У инструмента два сценария:

• source_type = "file" - расшифровка аудио- или видеофайла по внешнему URL;
• source_type = "youtube" - расшифровка YouTube-видео по ссылке.

Тело запроса

{
  "tool": "audio-video-transcription",
  "input": {
    "source_type": "file",
    "media_url": "https://cdn.example.com/meeting-recording-1.mp3",
    "language": "ru",
    "delivery_format": "text",
    "text_format": "paragraphs"
  }
}

• tool - slug нейросети, всегда "audio-video-transcription".
• input - параметры конкретного запуска.
• Набор полей зависит от source_type и выбранного формата выдачи.
• Параметры передаются напрямую внутри input, без дополнительного вложенного объекта input.input.

Параметры

Пример custom_spelling:

{
  "show_advanced_settings": true,
  "custom_spelling": [
    {
      "from_words": ["декарло", "decarlo"],
      "to": "Decarlo"
    }
  ]
}

duration_seconds передавать не нужно. Для файла длительность определяет сервер до создания операции и расчёта цены. Для YouTube сервер проверяет ссылку и определяет длительность видео сам.

Примеры запросов

Сценарий 1. Расшифровка файла в текст

Используйте этот сценарий для записи встречи, интервью, лекции или видео, которое доступно по внешней ссылке.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "audio-video-transcription",
    "input": {
      "source_type": "file",
      "media_url": "https://cdn.example.com/meeting-recording-1.mp3",
      "language": "ru",
      "delivery_format": "text",
      "text_format": "paragraphs"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'audio-video-transcription',
    input: {
      source_type: 'file',
      media_url: 'https://cdn.example.com/meeting-recording-1.mp3',
      language: 'ru',
      delivery_format: 'text',
      text_format: 'paragraphs',
    },
  }),
})

const operation = await response.json()
console.log(operation.id)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'audio-video-transcription',
        'input': {
            'source_type': 'file',
            'media_url': 'https://cdn.example.com/meeting-recording-1.mp3',
            'language': 'ru',
            'delivery_format': 'text',
            'text_format': 'paragraphs',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 2. Расшифровка YouTube-видео в SRT

Используйте этот сценарий, когда исходное видео уже опубликовано на YouTube. Для формата srt не передавайте text_format.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "audio-video-transcription",
    "input": {
      "source_type": "youtube",
      "youtube_url": "https://www.youtube.com/watch?v=M7lc1UVf-VE",
      "language": "auto",
      "delivery_format": "srt"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'audio-video-transcription',
    input: {
      source_type: 'youtube',
      youtube_url: 'https://www.youtube.com/watch?v=M7lc1UVf-VE',
      language: 'auto',
      delivery_format: 'srt',
    },
  }),
})

const operation = await response.json()
console.log(operation.id)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'audio-video-transcription',
        'input': {
            'source_type': 'youtube',
            'youtube_url': 'https://www.youtube.com/watch?v=M7lc1UVf-VE',
            'language': 'auto',
            'delivery_format': 'srt',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "d9c43f6a-8588-4fd1-9ac3-45c58997fb8a",
  "status": "queued",
  "tool": "audio-video-transcription",
  "cost": 12.5,
  "balance_after": 487.5,
  "created_at": "2026-09-07T09:30:00Z"
}

cost рассчитывается после определения длительности сервером. В этом примере запись длится 1250 секунд, поэтому стоимость составляет 1250 × 0,01 ₽ = 12,50 ₽.

Ответ после завершения

Для delivery_format = "text" готовая расшифровка возвращается в result.text:

{
  "id": "d9c43f6a-8588-4fd1-9ac3-45c58997fb8a",
  "status": "completed",
  "tool": "audio-video-transcription",
  "cost": 12.5,
  "created_at": "2026-09-07T09:30:00Z",
  "completed_at": "2026-09-07T09:32:14Z",
  "result": {
    "type": "text",
    "text": "Добрый день. Начинаем встречу по итогам недели."
  },
  "error_message": null
}

Ответ при ошибке выполнения

{
  "id": "d9c43f6a-8588-4fd1-9ac3-45c58997fb8a",
  "status": "failed",
  "tool": "audio-video-transcription",
  "cost": 12.5,
  "created_at": "2026-09-07T09:30:00Z",
  "completed_at": "2026-09-07T09:31:03Z",
  "result": null,
  "error_message": "Не удалось выполнить расшифровку"
}

Проверка статуса

Сохраните id, который вернулся после создания операции, и используйте его для проверки статуса.

• Endpoint: GET /api/v1/operations/{id}
• Не запрашивайте статус одной операции чаще одного раза в секунду.

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/d9c43f6a-8588-4fd1-9ac3-45c58997fb8a

JavaScript / TypeScript

const operationId = 'd9c43f6a-8588-4fd1-9ac3-45c58997fb8a'

const response = await fetch(
  `https://bratuha.ru/api/v1/operations/${operationId}`,
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  },
)

const operation = await response.json()
console.log(operation.status, operation.result)

Формат результата

Формат result зависит от delivery_format.

Текст в ответе

При delivery_format = "text":

{
  "type": "text",
  "text": "Готовая расшифровка записи"
}

Файл для скачивания

При delivery_format = "txt", "docx", "pdf" или "srt":

{
  "type": "file",
  "files": [
    {
      "url": "https://storage.bratuha.ru/results/audio-video-transcription/transcription.srt"
    }
  ]
}

• type - тип результата: text или file.
• text - готовая расшифровка, если выбран текстовый формат.
• files - массив файлов для скачивания, если выбран файл. Даже если сейчас возвращается один файл, обрабатывайте это поле как массив.

Ценообразование

Цена зависит только от длительности исходной записи:

• ставка - 0,01 ₽ за секунду;
• длительность определяет сервер, клиент не передаёт её в запросе;
• неполные секунды округляются вверх;
• минимальная длительность - 1 секунда;
• максимальная длительность - 36 000 секунд, или 10 часов.

Примеры расчёта:

• запись на 61 секунду: 61 × 0,01 ₽ = 0,61 ₽;
• запись на 1250 секунд: 1250 × 0,01 ₽ = 12,50 ₽;
• запись на 10,2 секунды: ceil(10,2) × 0,01 ₽ = 0,11 ₽.

Язык, формат текста, словарь исправлений и формат выдачи на цену не влияют.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую операцию и повторно списывает стоимость.
• Операции выполняются асинхронно: сохраните id из первого ответа и проверяйте статус отдельным запросом.
• Для media_url используйте только внешние http/https URL. localhost, loopback, private IP и внутренние адреса не принимаются.
• Один API-запрос в file-режиме принимает один файл. Механика пакетной загрузки из интерфейса сайта не относится к Public API.
• Для внешнего файла сервер определяет длительность до создания операции. Если файл недоступен, превышает 128 МиБ, имеет неподдерживаемую структуру или длительность не удалось определить, операция не создаётся и средства не списываются.
• Для YouTube сервер проверяет ссылку, нормализует её и определяет длительность. Если ссылка некорректна, видео недоступно или длиннее 10 часов, операция не создаётся.
• При delivery_format = "srt" не передавайте text_format и expected_speakers.
• Если передаёте дополнительные настройки, установите show_advanced_settings в true.