Genius-bot · 11 минут чтения
Если задача — получить первый mp3 из текста без отдельного интерфейса, text to speech api сводится к нескольким HTTP-запросам: взять ключ, выбрать операцию tts, передать текст и дождаться результата. В этом материале разберём именно практическое подключение: от первого запроса до готового файла. Ключ для API выдаётся после входа в раздел API и показывается один раз.
Для примеров будем использовать базовый адрес https://genius-bot.ru/wp-json/genius/v1. API синтеза речи работает через операцию tts, а стандартный сценарий построен вокруг запуска задачи и последующей проверки её состояния.
Стоимость озвучки считается не как фиксированная цена за любой файл, а за 1000 знаков. Поэтому ещё до первого запуска можно посчитать бюджет по длине текста. Это удобно, если озвучка вызывается из скрипта или ставится в очередь для большого количества материалов.
Что нужно знать про синтез речи до первого запроса
Перед подключением достаточно понимать четыре вещи: где находится API, как передаётся ключ, какой маршрут запускает операцию и где забирается результат. Базовый URL один: https://genius-bot.ru/wp-json/genius/v1. Для авторизации используется HTTP-заголовок Authorization: Bearer <ключ>.
Ключ создаётся в личном разделе API после входа. Важная практическая деталь: ключ показывается один раз, поэтому его стоит сразу сохранить в переменной окружения или другом защищённом хранилище, а не вставлять непосредственно в исходный код приложения.
У API есть отдельные маршруты для разных этапов работы. GET /services возвращает список операций и цен, GET /balance позволяет проверить остаток, POST /generate запускает операцию, а GET /tasks/{id} используется для проверки состояния и получения результата.
Для синтеза речи нужная операция называется tts. В справке цена этой операции указана как 18 ₽ за 1000 знаков. При этом общая схема оплаты — за запуск, без абонентской платы и минимального платежа; для первого ключа на баланс начисляется 50 ₽ для пробного использования.
Есть и техническое ограничение по частоте: не более 60 запросов в минуту на один ключ. Для единичного скрипта это обычно означает лишь необходимость не создавать лишние запросы в цикле. При массовой обработке текстов ограничение уже стоит учитывать в очереди задач.
До интеграции удобно один раз запросить список доступных операций:
curl https://genius-bot.ru/wp-json/genius/v1/services \
-H "Authorization: Bearer $GENIUS_API_KEY"Такой запрос не запускает озвучку. Он позволяет получить актуальный список операций и цен непосредственно из API, вместо того чтобы зашивать тарифы в приложение.
Запрос: текст, голос, язык — и что из этого обязательно
Логика запуска начинается с POST /generate. В запросе нужно указать операцию и параметры, необходимые для неё. Для tts ключевым входом является текст, который требуется озвучить; параметры голоса и языка следует передавать в соответствии с доступными для операции полями.
Здесь важно не путать обязательные данные HTTP-запроса с настройками конкретного голоса. Обязательным элементом авторизации является заголовок Bearer с ключом. Сам текст должен быть передан как вход операции tts, а конкретные поля выбора голоса и языка зависят от формата параметров операции, который возвращается API.
Практический подход — сначала посмотреть описание операции через список сервисов, а затем отправить минимальный запрос с текстом. Это лучше, чем сразу строить клиент вокруг предположений о названиях параметров: в справке сервиса доступны конкретные операции, а лишние поля в собственном коде только усложняют отладку.
Типовой вызов запуска выглядит следующим образом:
curl -X POST https://genius-bot.ru/wp-json/genius/v1/generate \
-H "Authorization: Bearer $GENIUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service": "tts",
"text": "Это тестовая фраза для синтеза речи."
}'В этом примере показан минимальный сценарий: авторизация, JSON-тело и запуск операции tts. Если API в ответ возвращает идентификатор задачи, его нужно сохранить. Именно этот идентификатор понадобится следующему запросу к /tasks/{id}.
Для Python тот же сценарий можно оформить через requests. Ключ лучше получать из переменной окружения, чтобы он не оказался в репозитории:
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}",
"Content-Type": "application/json",
}
payload = {
"service": "tts",
"text": "Это тестовая фраза для синтеза речи.",
}
response = requests.post(
f"{base_url}/generate",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
task = response.json()
print(task)Если ваш сценарий должен выбирать голос программно, не стоит хранить список голосов как вечную константу без проверки API. Сначала получите актуальную информацию об операции, затем подставляйте нужные параметры в тело запроса. Так клиент меньше зависит от предположений о текущем наборе настроек.
Отдельно существует совместимость с OpenAI для маршрутов POST /chat/completions и GET /models: они работают в том же формате, что и у OpenAI, поэтому в клиентской библиотеке достаточно поменять base_url и ключ. Для этой статьи это не основной путь, поскольку озвучка текста запускается через операцию tts, но при наличии существующего клиента это может быть полезной частью общей интеграции API.
Цена за тысячу знаков: считаем стоимость до запуска
У озвучки текста тариф отличается от большинства перечисленных операций: 18 ₽ начисляются за 1000 знаков. Поэтому стоимость можно рассчитать непосредственно из длины исходного текста до отправки запроса.
| Объём текста | Расчёт | Стоимость |
|---|---|---|
| 500 знаков | 500 / 1000 × 18 ₽ | 9 ₽ |
| 1000 знаков | 1000 / 1000 × 18 ₽ | 18 ₽ |
| 2500 знаков | 2500 / 1000 × 18 ₽ | 45 ₽ |
| 5000 знаков | 5000 / 1000 × 18 ₽ | 90 ₽ |
| 10000 знаков | 10000 / 1000 × 18 ₽ | 180 ₽ |
Для автоматического расчёта достаточно получить длину строки и умножить её на 18 / 1000. Например, текст из 7200 знаков даёт расчётную стоимость 129,60 ₽. Такой расчёт полезно выполнять до вызова /generate, если пользователь самостоятельно загружает большие тексты и должен видеть предполагаемый расход.
В Python формула выглядит совсем просто:
text = "Ваш текст для озвучки"
characters = len(text)
estimated_cost = characters / 1000 * 18
print(f"Знаков: {characters}")
print(f"Расчётная стоимость: {estimated_cost:.2f} ₽")При подсчёте стоит заранее определить правило, по которому ваше приложение считает знаки, и использовать его последовательно. Если вы сначала делите материал на части, расчёт лучше делать по каждому фрагменту и затем суммировать значения.
Для проверки остатка баланса предусмотрен отдельный маршрут GET /balance. Его можно вызывать перед постановкой задачи, если приложение должно самостоятельно контролировать доступный бюджет.
curl https://genius-bot.ru/wp-json/genius/v1/balance \
-H "Authorization: Bearer $GENIUS_API_KEY"Это особенно удобно для пакетной обработки: приложение может не отправлять новую задачу, если расчётная стоимость очередного текста превышает доступный остаток. Сам тариф на tts при этом остаётся фиксированным в рамках указанной цены — 18 ₽ за 1000 знаков.
Получение готового файла и его формат
После запуска операции не следует строить приложение вокруг предположения, что HTTP-ответ /generate уже является готовым аудиофайлом. Маршрут запускает операцию, а состояние и результат задачи проверяются через GET /tasks/{id}.
Если в ответе на запуск получен идентификатор, следующий шаг — запросить соответствующую задачу. Пример:
curl https://genius-bot.ru/wp-json/genius/v1/tasks/TASK_ID \
-H "Authorization: Bearer $GENIUS_API_KEY"Замените TASK_ID на идентификатор, который вернул запуск операции. Ответ содержит состояние задачи и, когда обработка завершена, результат, который можно использовать дальше в вашем приложении.
Для автоматической системы есть два варианта контроля готовности. Первый — периодически запрашивать /tasks/{id}. Второй — передать при запуске параметр callback_url: когда задача будет готова, API отправит POST на указанный адрес.
Webhook удобнее, если озвучка является частью фонового процесса. Например, сервер создаёт задачу, сохраняет её ID вместе с записью пользователя и ждёт входящего POST, вместо того чтобы постоянно опрашивать API. При получении уведомления сервер может проверить состояние задачи и продолжить обработку результата.
Для первого прототипа polling проще отлаживать: отправили текст, получили ID, сделали запрос состояния и посмотрели ответ. Когда такой код начинает обрабатывать десятки или сотни задач, callback_url позволяет перенести ожидание на событийную модель.
Само аудио в пользовательском сценарии можно рассматривать как последний результат цепочки: исходный текст → запуск tts → ID задачи → готовность → результат. Если приложение должно сохранить файл локально или передать его дальше, делайте это после подтверждения готовности задачи, а не сразу после POST /generate.
Длинный текст: разбиение и склейка без швов
Длинный материал лучше не превращать в один гигантский запрос без необходимости. Разбиение на логические фрагменты позволяет отдельно контролировать стоимость, повторно запускать только неудачный участок и ограничивать размер одной задачи.
Для разбиения подходят абзацы, предложения или заранее выбранные блоки по количеству знаков. Практическое правило здесь не в фиксированном числе символов, а в сохранении естественных границ речи: фрагмент желательно заканчивать на точке, вопросительном или восклицательном знаке, а не посреди слова или предложения.
При этом каждый фрагмент тарифицируется по объёму текста, поэтому перед отправкой всей очереди можно суммировать количество знаков. Например, если после разбиения получилось 12 частей общей длиной 18 000 знаков, расчётный расход для tts составит 324 ₽.
Для каждого фрагмента удобно хранить собственную запись: порядковый номер, исходный текст, ID задачи, статус и результат. Тогда после завершения обработки можно собрать части строго в исходном порядке.
Если используется polling, не стоит отправлять запросы к состоянию слишком часто. Ограничение составляет не более 60 запросов в минуту на ключ, поэтому частоту проверки и количество параллельных задач нужно учитывать в архитектуре очереди.
При использовании callback_url схема становится проще: каждая задача сообщает о готовности отдельно. Сервер получает событие, связывает его с сохранённым ID, получает результат и отмечает конкретный фрагмент как готовый.
Чтобы при склейке не было заметных скачков, важнее всего одинаковые параметры озвучки для всех частей. Не стоит без причины менять голос между фрагментами одного материала. Границы должны приходиться на естественные паузы, а текст — содержать нормальную пунктуацию, поскольку именно она влияет на структуру произнесённой фразы.
Отдельно полезно предусмотреть повторный запуск одного фрагмента. Не нужно повторять весь документ, если проблема возникла только с одной частью. Сохранённые ID и исходные тексты позволяют заменить только соответствующий результат.
Проверка качества: на чём слышно разницу между голосами
Качество синтеза удобнее проверять не по одной короткой фразе, а на тексте, похожем на реальную задачу. Для теста возьмите несколько предложений с запятыми, числами, сокращениями, вопросительной интонацией и длинной фразой. Так быстрее обнаруживаются особенности конкретного голоса.
Первое, на что стоит слушать, — ударения и произношение терминов. Если в материале есть технические слова, названия продуктов или аббревиатуры, проверьте их отдельно. Ошибка в одном термине может быть заметнее, чем небольшая разница в тембре.
Второй критерий — паузы. Сравните одну и ту же фразу с разной пунктуацией: запятая, точка и тире могут менять естественность произнесения. Поэтому перед сменой голоса иногда полезнее сначала привести текст к нормальному письменному виду.
Третий критерий — длинные предложения. На коротком «Проверка связи» почти любой голос может звучать приемлемо, но в предложении на несколько строк становятся заметны темп, паузы и то, как голос проходит через последовательность придаточных частей.
Четвёртый критерий — числа и смешанный текст. Если сценарий содержит даты, проценты, денежные значения или обозначения вроде API и HTTP, их стоит включить в тестовый фрагмент. Такой тест ближе к реальному использованию, чем демонстрационная фраза из нескольких слов.
Выбирать голос имеет смысл после такого короткого прогона. Если в приложении предусмотрено несколько вариантов, сохраните тестовую строку и прогоняйте её при изменении настроек. Тогда сравнение будет происходить на одном и том же исходном материале.
В результате интеграция text to speech api остаётся обычным API-процессом: получить ключ, определить параметры tts, отправить текст через /generate, сохранить ID задачи и дождаться результата через /tasks/{id} или webhook. Цена рассчитывается по количеству знаков — 18 ₽ за 1000 знаков, поэтому бюджет можно вычислить до запуска.
Частые вопросы
Сколько стоит озвучка текста?
Операция tts стоит 18 ₽ за 1000 знаков. Например, 5000 знаков дают расчётную стоимость 90 ₽.
Где взять API-ключ?
После входа ключ выдаётся в разделе API. Он показывается один раз, поэтому его нужно сохранить сразу после выпуска.
Нужно ли самостоятельно постоянно опрашивать задачу?
Нет. Можно использовать GET /tasks/{id} для проверки состояния либо передать параметр callback_url и получить POST на свой адрес после готовности задачи.
Есть ли ограничение на частоту запросов?
Да. Для одного ключа разрешено не более 60 запросов в минуту. Это ограничение нужно учитывать при массовой обработке текстов и частом polling.
Можно ли проверить баланс программно?
Да. Для этого предусмотрен GET /balance с авторизацией через Bearer-ключ.
Подходит ли tts api для длинных текстов?
Для длинных материалов практичнее разбивать текст на логические фрагменты, обрабатывать их отдельно и затем собирать результаты в исходном порядке. Стоимость при этом можно заранее посчитать по суммарному количеству знаков.
Начать подключение можно с раздела документации и получения API-ключа, после чего проверить баланс, запустить тестовую озвучку и получить результат задачи. Такой путь позволяет пройти всю цепочку озвучка текста через api на небольшом примере до добавления очередей, webhook и пакетной обработки.
