API Аудио предоставляет один endpoint для преобразования речи в текст:

  • transcriptions

Загрузка файлов ограничена 1 ГБ (если вам нужна поддержка файлов большего размера, вы можете написать в Поддержку). Поддерживаются следующие типы файлов: mp3, wav, m4a, flac, ogg, opus, mp4, mov, avi и mkv. Также, поддерживается отправка файлов по их ссылкам и нейронное разделение на говорящих (диаризация).

​
Транскрибация

API транскрибации принимает на вход аудио (или видео) файл, который вы хотите транскрибировать (либо ссылку на этот файл), и желаемый формат вывода. Модель поддерживает следующие форматы вывода (json, text, srt, verbose_json, vtt). Подробнее о форматах вывода читайте на странице Форматы ответа.

import requests

url = "https://api.nexara.ru/api/v1/audio/transcriptions"
api_key = "NEXARA_API_KEY"  # Замените своим настоящим ключом

headers = {
    "Authorization": f"Bearer {api_key}",
}

file_path = "audio/example.mp3"

with open(file_path, "rb") as audio_file:
    files = {
        "file": (file_path, audio_file, "audio/mp3"),  # Поменяйте MIME тип, если нужно
    }

    # Или вы можете передать параметр "url" и отправить прямую ссылку на аудиофайл.
    data = {
        "response_format": "json",
        # "task": "diarize" # если вы хотите выполнить диаризацию
        # По умолчанию, `task` равен "transcribe"
    }

    response = requests.post(url, headers=headers, files=files, data=data)

    transcription = response.json()
    print(transcription)

По умолчанию тип ответа будет json:

{
  "text": "Восемьдесят семь лет тому назад наши отцы основали на этом континенте новую нацию, зачатую в свободе и посвященную утверждению, что все люди созданы равными.
...
}

​
Поддерживаемые языки

В настоящее время мы поддерживаем следующие языки через endpoint /transcriptions:

Африкаанс, Арабский, Армянский, Азербайджанский, Белорусский, Боснийский, Болгарский, Каталанский, Китайский, Хорватский, Чешский, Датский, Нидерландский, Английский, Эстонский, Финский, Французский, Галисийский, Немецкий, Греческий, Иврит, Хинди, Венгерский, Исландский, Индонезийский, Итальянский, Японский, Каннада, Казахский, Корейский, Латышский, Литовский, Македонский, Малайский, Маратхи, Маори, Непальский, Норвежский, Персидский, Польский, Португальский, Румынский, Русский, Сербский, Словацкий, Словенский, Испанский, Суахили, Шведский, Тагальский, Тамильский, Тайский, Турецкий, Украинский, Урду, Вьетнамский и Валлийский.

Хотя модель была обучена на 98 языках, список выше содержит только языки, у которых Word Error Rate (WER) не больше 50%. Полный список языков и их кодов в формате ISO-639-1 смотрите на странице Supported Languages.

​
Временные метки

Чтобы получить временные метки вместе с результатом, вы можете использовать параметр timestamp_granularities[]. Для того, чтобы использовать эту функцию, установите verbose_json в параметре response_format. Для получения более подробной информации посетите Документацию API.

В настоящее время доступны два уровня детализации временных меток:

  1. Уровень segment:

    • Как запросить: Добавьте параметр timestamp_granularities[]='segment' в API-запрос вместе с response_format='verbose_json'.
    • Что возвращается: В ответе формата verbose_json будет массив segments. Каждый элемент этого массива представляет собой 30-секундный фрагмент аудио и содержит:
      • время начала (start),
      • время окончания (end),
      • транскрибированный текст (text) для данного сегмента.

  2. Уровень word:

    • Как запросить: Добавьте timestamp_granularities[]='word' в запрос (также с response_format='verbose_json').
    • Что возвращается: Это самый подробный уровень временных меток. В ответе вы получите:
      • Массив words, где каждый объект содержит отдельное слово с точными временами начала (start) и окончания (end) в секундах.
      • Массив segments, как и при сегментной детализации. Даже если вы запрашиваете уровень word, структура segments всё равно включается в ответ — это позволяет получить как точные метки слов, так и более широкие сегменты в одном ответе.

В итоге:

  • Используйте segment, если вам нужно примерное разбиение по времени.
  • Используйте word, если вам нужны точные времена начала/конца для отдельных слов. Запрос гранулярности word удобно предоставляет как массив words, так и массив segments.
  • Помните, что для обоих вариантов нужен response_format='verbose_json'.
import requests

url = "https://api.nexara.ru/api/v1/audio/transcriptions"
api_key = "NEXARA_API_KEY"  # Замените своим настоящим ключом

headers = {
    "Authorization": f"Bearer {api_key}",
}

file_path = "audio/example.mp3"

with open(file_path, "rb") as audio_file:
    files = {
        "file": (file_path, audio_file, "audio/mp3"),  # Поменяйте MIME тип, если нужно
    }
    data = {
        "response_format": "verbose_json",
        "timestamp_granularities[]": "word", # Возвращает временные метки
    }

    response = requests.post(url, headers=headers, files=files, data=data)

    transcription = response.json()
    print(transcription)

Пример вывода:

{
  "duration": 109.69609977324264,
  "language": "en",
  "task": "transcribe",
  "text": "Four score and seven years ago, our fathers brought forth on this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal. ... ",
  "words": [
    {
      "end": 0.62,
      "prob": 0.07,
      "start": 0,
      "word": "Four"
    },
    {
      "end": 1.12,
      "prob": 0.21,
      "start": 0.62,
      "word": "score"
    },
    {
      "end": 1.44,
      "prob": 0.84,
      "start": 1.12,
      "word": "and"
    },
    {
      "end": 1.82,
      "prob": 0.95,
      "start": 1.44,
      "word": "seven"
    },
    {
      "end": 2.18,
      "prob": 0.99,
      "start": 1.82,
      "word": "years"
    },
    {
      "end": 3.54,
      "prob": 0.68,
      "start": 2.18,
      "word": "ago,"
    },
    {
      "end": 3.84,
      "prob": 0.94,
      "start": 3.54,
      "word": "our"
    },
    {
      "end": 4.16,
      "prob": 0.46,
      "start": 3.84,
      "word": "fathers"
    },
    {
      "end": 4.52,
      "prob": 0.97,
      "start": 4.16,
      "word": "brought"
    },
    {
      "end": 4.94,
      "prob": 0.97,
      "start": 4.52,
      "word": "forth"
    },
    {
      "end": 5.16,
      "prob": 0.92,
      "start": 4.94,
      "word": "on"
    },
    {
      "end": 5.28,
      "prob": 0.77,
      "start": 5.16,
      "word": "this"
    },
    {
      "end": 5.64,
      "prob": 0.93,
      "start": 5.28,
      "word": "continent"
    },
    {
      "end": 6.12,
      "prob": 0.82,
      "start": 5.64,
      "word": "a"
    },
    {
      "end": 6.18,
      "prob": 0.98,
      "start": 6.12,
      "word": "new"
    },
    {
      "end": 7.94,
      "prob": 0.75,
      "start": 6.18,
      "word": "nation,"
    },
    {
      "end": 8.16,
      "prob": 0.98,
      "start": 7.94,
      "word": "conceived"
    },
    {
      "end": 8.46,
      "prob": 0.95,
      "start": 8.16,
      "word": "in"
    },
    {
      "end": 8.8,
      "prob": 0.98,
      "start": 8.46,
      "word": "liberty"
    },
    {
      "end": 9.64,
      "prob": 0.43,
      "start": 8.8,
      "word": "and"
    },
    {
      "end": 10.02,
      "prob": 1,
      "start": 9.64,
      "word": "dedicated"
    },
    {
      "end": 10.64,
      "prob": 0.96,
      "start": 10.02,
      "word": "to"
    },
    {
      "end": 10.86,
      "prob": 1,
      "start": 10.64,
      "word": "the"
    },
    {
      "end": 11.32,
      "prob": 0.98,
      "start": 10.86,
      "word": "proposition"
    },
    {
      "end": 11.78,
      "prob": 1,
      "start": 11.32,
      "word": "that"
    },
    {
      "end": 11.88,
      "prob": 0.91,
      "start": 11.78,
      "word": "all"
    },
    {
      "end": 12.1,
      "prob": 0.99,
      "start": 11.88,
      "word": "men"
    },
    {
      "end": 12.4,
      "prob": 0.98,
      "start": 12.1,
      "word": "are"
    },
    {
      "end": 12.68,
      "prob": 0.98,
      "start": 12.4,
      "word": "created"
    },
    {
      "end": 14.68,
      "prob": 0.95,
      "start": 12.68,
      "word": "equal."
    }
  ],
  "segments": [
    {
      "avg_logprob": -1,
      "compression_ratio": 2.4,
      "end": 29,
      "id": 0,
      "no_speech_prob": 0.5,
      "seek": 0,
      "start": 0,
      "temperature": 1,
      "text": "Four score and seven years ago, our fathers brought forth on this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal. ...",
      "tokens": [
        7451, 6175, 293, 3407, 924, 2057, 11, 527, 23450, 3038, 5220, 322, 341,
        18932, 257, 777, 4790, 11, 34898, 294, 22849, 293, 8374, 281, 264,
        24830, 300, 439, 1706, 366, 2942, 2681, 13, 823, 321, 366, 8237
      ]
    }
  ]
}

​
Форматы ответа

API Nexara позволяет указать формат, в котором вы хотите получить результаты. Используя параметр response_format в вашем запросе, вы можете настроить вывод так, чтобы он наилучшим образом соответствовал вашим потребностям, будь то простой текст, структурированные данные или готовые к использованию файлы субтитров. Примеры смотрите в документации API.

API поддерживает следующие форматы вывода:

  • json: Возвращает стандартный JSON-объект, содержащий транскрибированный текст.
  • text: Возвращает транскрипцию в виде одной строки простого текста.
  • verbose_json: Возвращает подробный JSON-объект, содержащий текст, язык, продолжительность, а также, возможно, временные метки на уровне сегментов и слов (если запрошено через timestamp_granularities[]).
  • srt: Возвращает транскрипцию, отформатированную как файл субтитров SRT.
  • vtt: Возвращает транскрипцию, отформатированную как файл субтитров WebVTT.
Когда запрашиваете ответ в формате субтитров, (srt или vtt) не используйте response.text если делаете запрос через request библиотеку в Python. Используйте response.json, как и для остальных форматов ответа.

​
Диаризация

API Nexara поддерживает нейронное разделение на говорящих (диаризацию). Диаризация — это процесс разделения аудио на отдельные голоса, иными словами, определение, кто, когда и что говорит.

Также вы можете использовать параметр num_speakers для указания количества говорящих в аудиофайле. Обратите внимание, что этот параметр не гарантирует, что вы получите ровно столько говорящих, сколько указали вы, но помогает модели определить, сколько говорящих в аудиофайле.

Модель поддерживает три режима диаризации:

  • general: Общий режим.
  • meeting: Режим для встреч.
  • telephonic: Режим для телефонных разговоров.

Обратите внимение, что диаризация - более ресурсоемкая операция, чем транскрибация. Поэтому, время выполнения запроса может быть больше, чем при транскрибации. Стоимость минуты аудио при диаризации - 0,72 ₽ / мин.

import requests

url = "https://api.nexara.ru/api/v1/audio/transcriptions"
api_key = "NEXARA_API_KEY"  # Замените на ваш API ключ

headers = {
    "Authorization": f"Bearer {api_key}",
}

file_path = "audio/example.mp3"

with open(file_path, "rb") as audio_file:
    files = {
        "file": (file_path, audio_file, "audio/mp3"),  # Замените MIME тип, если нужно
    }

    # Или вы можете передать параметр "url" и отправить прямую ссылку на аудиофайл.
    data = {
        "task": "diarize",
        # "num_speakers": 2,
        # "diarization_setting": "telephonic"
    }

    response = requests.post(url, headers=headers, files=files, data=data)

    transcription = response.json()
    print(transcription)

Ответ содержит следующие поля:

  • task: Тип задачи.
  • language: Язык аудиофайла.
  • duration: Продолжительность аудиофайла.
  • text: Транскрибированный текст.
  • segments: Сегменты аудиофайла с информацией о начале, конце сегмента, ID говорящего и тексте, который он сказал.

Когда вы запрашиваете диаризацию, API всегда будет возвращать следующий JSON, вне зависимости от параметра response_format.

{
    "task": "diarize",
    "language": "en",
    "duration": 9.12,
    "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.",
    "segments": [
        {
            "speaker": "speaker_0",
            "start": 0.00,
            "end": 5.00,
            "text": "The beach was a popular spot on a hot summer day."
        },
        {
            "speaker": "speaker_1",
            "start": 5.00,
            "end": 9.12,
            "text": "People were swimming in the ocean, building sandcastles, and playing beach volleyball."
        }
    ]
}

Обратите внимание, что Nexara не поддерживает канальную диаризацию. Это означает, что API будет игнорировать стерео информацию и идентифицировать говорящих на основе содержимого аудиофайла.