Genius-bot · 9 минут чтения
Если задача — получить текст из записи программно, api распознавания речи сводится к нескольким шагам: загрузить аудиофайл, запустить операцию и забрать результат. В этом материале разберём последовательность запросов, отметки времени и разделение речи по говорящим, не уходя в обзор других решений. Ключ для запросов выдаётся в разделе API после входа.
Для операции расшифровки записи используется операция stt, её цена составляет 10 ₽ за один запуск. Оплата идёт за запуск, без абонентской платы и минимального платежа; при выпуске первого ключа на баланс начисляется 50 ₽ для пробы.
Что умеет распознавание речи и где ошибается
В API операция stt предназначена для расшифровки записи. В прикладном коде это обычная асинхронная задача: сначала файл становится доступен API, затем запускается обработка, после чего клиент получает состояние задачи и результат через отдельный запрос.
По смыслу такой сценарий соответствует тому, что обычно называют speech to text api, api расшифровки аудио или перевод речи в текст api. Термины отличаются, но в коде важна конкретная операция: для расшифровки записи в сервисе используется stt.
При распознавании нельзя считать исходную речь безошибочным источником данных. Результат зависит от самой записи: на разбор влияют слышимость речи, фоновые звуки, одновременная речь и другие особенности исходного аудио. Поэтому текст расшифровки стоит воспринимать как результат автоматической обработки, особенно если дальше он используется в документах или данных.
Для первого запуска полезно отделить две задачи. Сначала проверяется сам обмен с API — авторизация, загрузка, запуск и получение статуса. Затем уже оценивается качество конкретной записи. Такой порядок позволяет не смешивать ошибку запроса с ошибкой распознавания.
Загрузка записи и запуск задачи
Базовый адрес API — https://genius-bot.ru/wp-json/genius/v1. Для авторизации используется заголовок Authorization: Bearer <ключ>. Сам ключ выдаётся в личном разделе API после входа и показывается один раз, поэтому его удобно сразу сохранить в переменную окружения.
Последовательность состоит из четырёх известных маршрутов. POST /uploads принимает файл и возвращает ссылку на него, POST /generate запускает операцию, GET /tasks/{id} возвращает состояние и результат, а GET /balance позволяет проверить остаток баланса.
| Маршрут | Метод | Назначение |
|---|---|---|
/services |
GET | Список операций и цен |
/balance |
GET | Остаток баланса |
/uploads |
POST | Загрузка файла и получение ссылки |
/generate |
POST | Запуск операции |
/tasks/{id} |
GET | Состояние и результат задачи |
При этом в исходной справке для API не задана точная схема тела запросов /uploads и /generate: не указаны названия полей формы, JSON-параметров и формат ответа этих двух конкретных вызовов. Поэтому подставлять вымышленные имена вроде file_url, service или operation в пример было бы неправильно. Для реального запуска эти поля нужно брать из актуальной документации самого API.
Известная часть запроса выглядит так:
curl -X GET "https://genius-bot.ru/wp-json/genius/v1/services" \
-H "Authorization: Bearer $GENIUS_API_KEY"Этот запрос удобен перед первым запуском: он обращается к документированному маршруту /services и возвращает список доступных операций и цен. Для расшифровки в этом списке нужна операция stt.
Проверить баланс можно отдельным запросом:
curl -X GET "https://genius-bot.ru/wp-json/genius/v1/balance" \
-H "Authorization: Bearer $GENIUS_API_KEY"После загрузки файла приложение получает ссылку, передаёт её при запуске операции stt, получает идентификатор задачи и периодически запрашивает /tasks/{id}. Если вместо опроса нужен callback, при запуске можно передать параметр callback_url: когда задача готова, API отправит на этот адрес POST-запрос.
Что приходит в ответе кроме текста
Результат распознавания полезен не только как сплошная строка. Для работы с расшифровкой важны как минимум временная привязка фрагментов и информация о говорящих, если эти данные присутствуют в результате конкретной операции.
Отметки времени позволяют связать участок текста с исходной записью. Например, вместо абзаца без контекста приложение может показать фразу как фрагмент аудио с началом в определённой секунде. Это удобно для расшифровок интервью, лекций и длинных разговоров, где пользователю нужно быстро перейти к исходному месту.
Разделение по говорящим решает другую задачу. Текст разговора можно представить не одной последовательностью реплик, а блоками разных участников: условно, «говорящий 1», затем «говорящий 2», затем снова «говорящий 1». Это важно, если расшифровка должна сохранять структуру диалога.
Здесь есть практический нюанс: в предоставленной справке не зафиксирована точная JSON-схема ответа /tasks/{id}. Поэтому в собственном коде не стоит жёстко предполагать конкретные названия полей для текста, временных меток или говорящих, пока они не подтверждены документацией конкретной версии API. Сначала сохраните полный ответ задачи, а затем привяжите парсер к фактической структуре.
Отметки времени и разделение по говорящим
Если задача возвращает временные границы фрагментов, приложение может хранить их вместе с текстом. Например, внутренняя модель данных может содержать начало и конец сегмента, его текст и идентификатор говорящего. Это уже уровень вашей программы, а не дополнительная операция API.
Для интерфейса расшифровки такой формат позволяет построить список реплик, где рядом с текстом показывается время. Клик по реплике может передавать приложению секунду начала фрагмента, после чего плеер открывает соответствующее место записи.
С говорящими принцип тот же. Если API возвращает идентификатор участника для сегмента, его можно использовать как ключ группировки. Не следует заранее превращать «говорящий 1» в имя человека: автоматическая метка сама по себе не сообщает, кто именно говорит.
Особенно полезно сохранять исходный ответ задачи целиком. Тогда при изменении интерфейса не придётся повторно запускать платную операцию только для того, чтобы получить потерянное поле. Цена операции stt составляет 10 ₽ за запуск, поэтому повторные запуски лучше оставлять для действительно новой обработки.
Форматы и длительность записи
В доступной справке указано, что POST /uploads предназначен для загрузки файла и выдачи ссылки, а stt — для расшифровки записи. При этом конкретный перечень поддерживаемых аудиоформатов и максимальная длительность записи в предоставленных данных не указаны.
Поэтому в клиенте не стоит самостоятельно объявлять список вроде MP3, WAV, M4A и одновременно считать его официальным перечнем поддерживаемых форматов. Если формат или ограничение по длительности критичны для вашего сценария, их нужно проверить по актуальной документации перед отправкой файлов.
Практически удобно проверять параметры записи до загрузки: размер файла, расширение и длительность можно получить средствами вашей программы, а затем уже отправлять файл в /uploads. Это не меняет требования API, зато позволяет отсеивать неподходящие входные данные до платного запуска stt.
Для контроля расходов также имеет смысл смотреть баланс перед серией тестов. Ограничение частоты составляет не более 60 запросов в минуту на один ключ, поэтому приложение, которое постоянно опрашивает несколько задач, должно учитывать этот предел.
Первый рабочий пример
Ниже — минимальная Python-заготовка для документированного первого запроса. Она не пытается угадывать неизвестную схему загрузки или запуска: сначала получает список операций и позволяет проверить, что ключ работает, а затем выводит найденную цену stt, если она присутствует в ответе в ожидаемой структуре.
import os
import requests
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"
API_KEY = os.environ["GENIUS_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}",
}
response = requests.get(
f"{BASE_URL}/services",
headers=headers,
timeout=30,
)
response.raise_for_status()
services = response.json()
print(services)Этот код можно запустить после сохранения ключа в переменной GENIUS_API_KEY. В отличие от примера с выдуманными параметрами загрузки, здесь используются только те сведения, которые определены в справке: адрес API, метод GET, маршрут /services и Bearer-авторизация.
Следующий запрос проверяет баланс:
response = requests.get(
f"{BASE_URL}/balance",
headers=headers,
timeout=30,
)
response.raise_for_status()
print(response.json())После этой проверки цепочка первого запуска выглядит так: /uploads → ссылка на загруженную запись → /generate с операцией stt → идентификатор задачи → /tasks/{id} → результат. Точное тело двух POST-запросов нужно брать из схемы API, поскольку в исходной справке названия их полей не приведены.
Если приложение не хочет заниматься циклическим опросом, можно использовать callback_url. Тогда при готовности задачи API отправит POST на указанный адрес. На практике это удобнее для серверного приложения, которое может принять уведомление и затем сохранить результат.
Для самой операции стоимость фиксирована: один запуск stt стоит 10 ₽. Для ориентира рядом с ней в списке API находятся другие операции:
| Операция | Цена |
|---|---|
stt — расшифровка записи |
10 ₽ за запуск |
ytaudio — звук из видео |
0 ₽ за запуск |
denoise — убрать шум |
36 ₽ за запуск |
tts — озвучка текста |
18 ₽ за 1000 знаков |
vocal — убрать вокал |
45 ₽ за запуск |
Для первого теста достаточно проверить ключ, убедиться, что баланс доступен, найти stt в /services, загрузить запись и запустить задачу по схеме API. После получения результата имеет смысл сохранить не только итоговый текст, но и дополнительные данные ответа, если они возвращаются: временные интервалы и сегменты говорящих пригодятся при последующей обработке расшифровки.
Отдельно стоит помнить об ограничении частоты: один ключ допускает не более 60 запросов в минуту. Если приложение опрашивает статус нескольких задач, запросы к /tasks/{id} нужно распределять так, чтобы общий поток не превышал этот предел.
Частые вопросы
Сколько стоит API распознавания речи?
Операция stt стоит 10 ₽ за один запуск. Оплата производится за запуск, без абонентской платы и минимального платежа. При выпуске первого ключа на баланс начисляется 50 ₽ для пробы.
Какой заголовок нужен для авторизации?
Используется заголовок Authorization: Bearer <ключ>. Ключ выдаётся после входа в разделе API и показывается один раз.
Можно ли получить уведомление, когда расшифровка готова?
Да. При запуске задачи можно передать необязательный параметр callback_url. После готовности задачи на этот адрес приходит POST-запрос.
Где получить статус задачи?
Для этого используется GET /tasks/{id}, где {id} — идентификатор запущенной задачи. Маршрут возвращает состояние и результат.
Какие форматы аудио и максимальная длительность поддерживаются?
В предоставленной справке конкретный список форматов и максимальная длительность не указаны. Поэтому эти ограничения нельзя достоверно перечислить без обращения к актуальной документации API.
Можно ли использовать API с OpenAI-совместимым клиентом?
Совместимость с OpenAI заявлена для маршрутов POST /chat/completions и GET /models. Для них достаточно изменить base_url и ключ в клиентской библиотеке; тариф на чат составляет 40 ₽ за млн токенов запроса и 400 ₽ за млн токенов ответа. Эта совместимость относится к чату и не заменяет отдельную операцию stt для расшифровки записи.
Актуальные данные для подключения, ключ и доступные операции находятся в разделе API сервиса. Для первого запуска лучше сверить с ним именно схему POST-запросов загрузки и генерации, поскольку эти поля не определены в краткой справке.
