Часто задаваемые вопросы
Какой URL нужно использовать для запросов?
Используйте конечную точку POST https://api.play9bd.com/v1/audio/speech. Отправляйте JSON-тело с текстом, голосом и другими параметрами. Аутентификация осуществляется через заголовок Authorization: Bearer с вашим API-ключом. Этот эндпоинт принимает запросы в формате, совместимом с OpenAI, что упрощает интеграцию в ваши рабочие процессы генерации аудио.
Как сгенерировать API-ключ для тестирования?
Перейдите на страницу /get-api-key/ и зарегистрируйтесь через Google или по электронной почте. При входе через Google вы получите пробный кредит $0.50 (около 50 000 символов), действительный 7 дней. Ключ отображается сразу после входа. Если вы используете email, пробный кредит не начисляется, и нужно пополнить баланс.
Поддерживает ли API библиотеку OpenAI?
Да, вы можете использовать официальный SDK OpenAI. Просто измените базовый URL на https://api.play9bd.com/v1 и передайте ваш ключ Vokhlyest. Структура запросов полностью совпадает с эндпоинтом speech OpenAI. Это позволяет использовать знакомые инструменты без необходимости писать собственный код для отправки HTTP-запросов.
Какие форматы аудио доступны на выходе?
API поддерживает пять форматов: mp3, wav, opus, flac и pcm. Укажите желаемый формат в поле response_format запроса. Это позволяет интегрировать аудио в различные платформы без дополнительного конвертирования. Вы можете выбрать формат, наиболее подходящий для вашего видео-потока или системы хранения.
Можно ли указать язык явно в запросе?
Да, вы можете задать язык через параметр language, используя ISO-код. Если язык не указан, система пытается определить его по скрипту (латиница по умолчанию — английский). Для неанглийских текстов на латинице рекомендуется явно указывать язык. Поддерживается 23 языка, включая русский, английский, немецкий и другие.
Что делать, если лимит запросов исчерпан?
Лимит составляет 60 запросов в минуту на ключ. Если вы исчерпаете лимит, запросы будут обрабатываться в очереди или возвращать ошибку. До первого пополнения лимит ниже — 10 запросов в минуту. Для массового производства контента рекомендуется контролировать скорость запросов или использовать несколько ключей при необходимости.
Как обрабатывать ошибки при генерации?
Если синтез не удался, вы получите соответствующий код ошибки в ответе API. Важно знать, что при ошибке синтеза средства не списываются, и полный возврат происходит автоматически. Вы можете повторить запрос или изменить параметры, например, длину текста или формат, чтобы устранить причину сбоя.
Возвращаются ли деньги при ошибке синтеза?
Да, если синтез не удался, charge возвращается в полном объеме. Вы платите только за успешные запросы. Это гарантирует, что вы не потеряете средства из-за технических сбоев или ошибок в параметрах запроса. Баланс обновляется автоматически после возврата средств при неудачной попытке.
Сколько символов можно отправить в одном запросе?
Максимальная длина текста в одном запросе составляет 4096 символов. Если ваш текст длиннее, его нужно разбить на части до 4096 символов, сгенерировать аудио для каждой части и объединить файлы. Пробелы и знаки препинания также считаются символами. Это стандартный подход для обработки длинных сценариев.
Можно ли менять скорость генерации?
Да, параметр speed позволяет регулировать скорость от 0.25 до 4.0. Это полезно для адаптации аудио под тайминг видео. Более высокая скорость ускоряет речь, а низкая — замедляет. Вы можете точно настроить темп озвучки под стиль вашего контента, сохраняя естественность звучания голоса.
Какие модели доступны для синтеза?
Доступны две модели: tts-1 и tts-1-hd. Обе используют один и тот же движок и имеют одинаковую цену. Разница заключается в названии модели, но качество аудио и цена одинаковы. Вы можете выбрать любую модель в зависимости от требований к качеству вашего контента.
Нужно ли устанавливать дополнительные библиотеки?
Нет, для работы достаточно стандартных HTTP-клиентов или SDK OpenAI. Мы не предоставляем собственный SDK, но наш API совместим с официальными библиотеками OpenAI. Просто укажите базовый URL нашего API. Это позволяет использовать привычные инструменты разработки без установки дополнительных зависимостей, специфичных для Vokhlyest.
Первый запрос
curl
curl https://api.play9bd.com/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.play9bd.com/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.play9bd.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | женский |
nova | женский |
luna | женский |
sage | женский |
felix | мужской |
milo | мужской |
atlas | мужской |
orion | мужской |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Получение API-ключа
Для начала работы с Vokhlyest вам нужно создать аккаунт. Вы можете зарегистрироваться на сайте, используя аккаунт Google или создав учетную запись по электронной почте и паролю. Это простой шаг, который дает доступ к панели управления API.
Регистрация через Google или email
Регистрация занимает пару минут. Если вы войдете через Google, вам сразу начислят пробный баланс в размере $0.50 (около 50 000 символов), который действителен в течение 7 дней. При регистрации по email пробный баланс не начисляется, и аккаунт будет пустым до первого пополнения.
Генерация ключа на странице /get-api-key/
После регистрации перейдите на страницу получения ключа. Там вы увидите свой уникальный токен, текущий баланс, количество доступных символов и готовый пример команды curl для быстрого запуска. Этот ключ необходим для авторизации всех ваших запросов к API.
Ограничение на один активный ключ
На одном аккаунте может быть активен только один ключ. Если вам нужно сгенерировать новый токен, старый ключ перестает действовать немедленно. Это упрощает управление доступом: вы можете быстро отозвать доступ к API, просто создав новый ключ.
Первый запрос с помощью curl
Для отправки текста в аудио используется метод POST к эндпоинту /v1/audio/speech. Это стандартный REST-запрос, который позволяет мгновенно получить синтезированный аудиофайл в ответе.
Базовая структура POST-запроса
Запрос отправляется на https://api.play9bd.com/v1/audio/speech с заголовком авторизации и телом в формате JSON. Сервер возвращает готовый аудиофайл, который можно сохранить на диск для последующего монтажа в роликах для YouTube.
Необходимые поля: model, input, voice
Обязательные параметры включают выбор модели (tts-1 или tts-1-hd), текст до 4096 символов в поле input и голос (например, aria или atlas). Язык указывается необязательно; если он не задан, система попытается определить его автоматически, но для точности лучше указывать ISO-код.
Пример кода для быстрого запуска
Вы можете сразу скопировать и запустить этот запрос через терминал, заменив YOUR_API_KEY на ваш ключ и TEXT на ваш сценарий. Это самый быстрый способ проверить качество синтеза перед массовой интеграцией в ваши рабочие процессы.
- curl -X POST https://api.play9bd.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "aria"}'
Интеграция через OpenAI SDK
Поскольку Vokhlyest воспроизводит форму запроса OpenAI Speech, вы можете использовать привычные библиотеки, изменив лишь базовый URL. Это позволяет избежать создания кастомных HTTP-клиентов или написания обёрток для обработки потоков, так как API не поддерживает потоковую передачу, и сразу получить готовый аудиофайл.
Изменение base_url на наш эндпоинт
Для подключения к Vokhlyest достаточно указать base_url как https://api.play9bd.com/v1. Это позволяет использовать стандартные методы SDK, отправляя запросы на наш эндпоинт POST /v1/audio/speech. Аутентификация происходит через заголовок Authorization: Bearer <ваш_ключ>.
Использование стандартных библиотек
Вы можете использовать официальные SDK для Python, Node.js или Go. Передайте текст в поле input, выберите модель tts-1 или tts-1-hd и укажите голос. Библиотека сама сформирует JSON-запрос и обработает двоичный ответ с аудиофайлом.
Совместимость с официальными SDK
Интерфейс полностью совместим с тем, как работает OpenAI Speech API. Вы можете использовать те же структуры данных и параметры, такие как response_format и speed, не адаптируя код под специфичные требования. Это упрощает миграцию и тестирование в ваших пайплайнах генерации контента.
Поддерживаемые форматы аудио
Выбор формата влияет на качество и совместимость с монтажными программами. API поддерживает MP3, WAV, OPUS, FLAC и PCM, позволяя выбрать оптимальный вариант под конкретный проект.
MP3 для веб-плееров и социальных сетей
MP3 — универсальный выбор для публикации в YouTube, Instagram и TikTok. Формат обеспечивает сжатие без значительной потери качества, что ускоряет загрузку видео и снижает объем трафика.
- Оптимально для социальных сетей
- Минимальный размер файла
WAV для профессионального монтажа
WAV обеспечивает высокое качество, необходимое для детального аудио-монтажа. Этот формат предпочтителен для студийной работы, где важно сохранить каждую деталь интонации без артефактов сжатия.
- Высокое качество для монтажа
- Совместимость с DAW
OPUS, FLAC, PCM для специфических задач
OPUS и FLAC предлагают альтернативы с высоким сжатием или lossless-качеством. PCM подходит для получения сырых данных аудиопотока, если требуется дальнейшая обработка на стороне клиента.
- Гибкость для специфичных задач
Параметры запроса и настройки
Параметры запроса позволяют точно настроить генерацию аудио под задачи вашего контента. Вы выбираете модель, скорость речи и язык, чтобы результат соответствовал стилю вашего видео.
Выбор модели tts-1 или tts-1-hd
Обе модели используют один и тот же движок синтеза, поэтому качество аудио идентично. Разница лишь в названии, но цена за 1 млн символов остается неизменной.
Настройка скорости от 0.25 до 4.0
Параметр speed позволяет ускорить или замедлить речь. Это полезно для создания динамичных роликов или, наоборот, для спокойного повествования. Значение по умолчанию обеспечивает естественный темп.
Указание языка через ISO-код
Если вы не укажете язык, система попытается определить его автоматически, предполагая английский для латиницы. Для других языков или точного результата обязательно передавайте ISO-код (например, 'ru', 'en', 'de').

Обработка ошибок и статусов
Когда синтез завершается успешно, API возвращает аудиофайл в теле ответа. Однако в процессе работы могут возникать технические сбои или ограничения, которые важно отслеживать для стабильной работы пайплайна генерации контента.
Коды ответов HTTP API
API использует стандартные HTTP-статусы для информирования о статусе запроса. Код 200 означает успешную генерацию аудио. Коды 4xx указывают на ошибки в параметрах (например, неверный ключ или формат), а 5xx — на временные проблемы на стороне сервера.
Возврат средств при сбое синтеза
Если синтез не удался, средства возвращаются на баланс в полном объеме. Это гарантирует, что вы платите только за успешные результаты генерации, что особенно важно при массовом создании видео для YouTube.
Логирование ошибок для отладки
В случае ошибки API возвращает JSON-объект с описанием проблемы. Используйте эти данные для логирования и автоматической обработки сбоев в ваших скриптах, чтобы минимизировать простои в процессе локализации дубляжа.
Лимиты и ограничения API
API Vokhlyest имеет четкие технические ограничения, которые важно учитывать при массовой генерации аудио для YouTube. Знание лимитов помогает правильно настроить очередь запросов и избежать задержек при обработке больших объемов текста.
Система обрабатывает запросы последовательно, поэтому в пиковые нагрузки возможны очереди. Для стабильной работы рекомендуется учитывать скорости генерации и лимиты на ввод текста.
60 запросов в минуту на ключ
Максимальная пропускная способность составляет 60 запросов в минуту на один активный API-ключ. Если превысить этот лимит, новые запросы будут возвращать ошибку 429 (Too Many Requests).
Для команд, генерирующих длинные ролики, важно не превышать эту границу. Если система перегружена, запросы могут стоять в очереди, что увеличивает время получения аудиофайла.
Лимит 4096 символов на тело запроса
Один POST-запрос может содержать текст длиной до 4096 символов. Считаются все символы, включая пробелы и знаки препинания.
Для более длинных сценариев необходимо разбить текст на части. Сгенерированные аудиофайлы затем объединяются в единый файл.
Если текст превышает лимит, API вернет ошибку. Разбивайте текст логически, сохраняя целостность предложений.
Ограничение 10 запросов до первого пополнения
В начале работы, до первого пополнения баланса, доступно всего 10 запросов в минуту. Это ограничение помогает избежать нагрузки на серверы новыми аккаунтами.
После первого пополнения через USDT (TRC-20) лимит увеличивается до стандартных 60 запросов в минуту. Транзакция зачисляется автоматически в течение нескольких минут.
Баланс не имеет срока действия, и средства не сгорают.
Структура ответа API
В ответе на успешный запрос вы получаете готовый аудиофайл в указанном формате (mp3, wav, opus, flac или pcm). Аудио возвращается напрямую в теле ответа, что позволяет сразу сохранить его на диск или передать в пайплайн обработки видео.
Для сложных сценариев, когда текст превышает лимиты, используется метод последовательного объединения. Вы разбиваете текст на части до 4096 символов, генерируете их по отдельности и склеиваете результат в единый файл.
Возврат аудиофайла в теле ответа
Сервер возвращает бинарные данные с заголовком Content-Type, соответствующим выбранному формату. Это позволяет использовать стандартные HTTP-клиенты для сохранения файлов без дополнительных преобразований.
- Форматы: mp3, wav, opus, flac, pcm
- Лимит текста: 4096 символов на один запрос
- Аудио содержит невидимый цифровой водяной знак
Заголовки ответа и метаданные
В заголовках ответа передаются метаданные, необходимые для биллинга и отладки. Информация о затраченных символах и статусе обработки помогает точно контролировать расходы и логировать процессы.
Обработка длинных текстов
Поскольку максимальный объем текста ограничен 4096 символами, для длинных сценариев требуется предварительная сегментация. Сгенерированные фрагменты аудио необходимо объединить в последовательный файл для финального монтажа.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения.
23 языка
Любой голос может говорить на любом из этих языков.
Источники и дополнительные материалы
- Wikipedia
- LibriTTS-R corpus (OpenSLR 141)
- OpenAI API reference: create speech
- MDN: Web Speech API
- ISO 639 language codes
- Creative Commons Attribution 4.0
- Tether (USDT)
- openai-node on GitHub
- W3C WAI: making audio and video accessible
- LibriVox public-domain audiobooks
- Python documentation
- openai-python on GitHub
