Часто задаваемые вопросы
Какой HTTP метод нужно использовать для запроса?
Используйте метод POST для отправки запроса на endpoint /v1/audio/speech. Тело запроса должно содержать JSON с полями model, input, voice и response_format. Это стандартный формат, совместимый с официальными SDK OpenAI при изменении базового URL.
Нужно ли устанавливать специфичный SDK для нашей платформы?
Нет, специального SDK нет. Вы можете использовать официальные SDK OpenAI, просто изменив base_url на https://api.play82q.com/v1. Также подойдет любой HTTP-клиент для отправки POST-запросов. Мобильных SDK или плагинов для WordPress у нас нет.
Можно ли использовать ключ от другого сервиса OpenAI?
Нет, ключи уникальны для каждого аккаунта в нашей сети. Ваш ключ начинается с префикса tts- и действует только для API play82q.com. Ключи от других провайдеров здесь не подойдут для аутентификации.
Как правильно передать текст в JSON теле запроса?
Передайте текст в поле input объекта JSON. Максимальная длина — 4096 символов. Убедитесь, что текст корректно закодирован в UTF-8. Если текст длиннее, разбейте его на части, сгенерируйте аудио отдельно и объедините файлы.
Что означает код ошибки 429?
Код 429 означает превышение лимита запросов. Лимит составляет 60 запросов в минуту на один ключ (10 в минуту до пополнения баланса). Увеличьте интервал между запросами или подождите, пока лимит обновится, чтобы продолжить генерацию аудио.
Можно ли генерировать аудио потоком (streaming)?
Нет, потоковая генерация (streaming) не поддерживается. API возвращает готовый аудиофайл в ответе после завершения синтеза. Вы можете получить файл в форматах mp3, wav, opus, flac или pcm, но не частичный поток данных в реальном времени.
Есть ли поддержка SSML тегов в тексте?
Нет, поддержка SSML тегов отсутствует. Вы передаете обычный текст, и система использует стандартные правила произношения. Паузы и интонация контролируются только через параметры голоса и скорости, без возможности добавлять специальные теги разметки в тело запроса.
Как указать язык для текста на кириллице?
Укажите поле language в запросе с кодом ISO (например, ru, de, es). Если язык не указан, система попытается угадать его по скрипту, но для кириллицы это может быть неверно. Язык должен быть из списка поддерживаемых (23 языка).
Какой максимальный размер одного запроса?
Максимальный размер текста в одном запросе — 4096 символов. Если ваш текст длиннее, разделите его на части до этого лимита. Сгенерируйте аудио для каждой части отдельно, а затем объедините полученные аудиофайлы в один файл.
Нужно ли кодировать текст в base64?
Нет, кодировать текст в base64 не нужно. Передавайте текст как обычную строку в поле input JSON-объекта. Система сама обработает строку и преобразует её в речь, используя выбранный голос и модель синтеза.
Как работает параметр speed в запросе?
Параметр speed управляет скоростью речи в диапазоне от 0.25 до 4.0. Значение 1.0 — стандартная скорость. Вы можете ускорить или замедлить озвучку, чтобы адаптировать её под ваш контент, сохраняя естественность звучания голоса.
Влияет ли выбор модели на время генерации?
Модели tts-1 и tts-1-hd используют один и тот же движок синтеза, поэтому время генерации у них одинаковое. Различается только качество звука. Запросы обрабатываются последовательно, поэтому при высокой нагрузке может возникать очередь ожидания.
Где найти список доступных голосов?
Список голосов, языков и форматов доступен по адресу GET /v1/voices. Там также указана цена и технические характеристики. Вы можете использовать этот endpoint для получения актуальной информации перед отправкой запросов на синтез текста в аудио.
Можно ли указать голос по имени или только по ID?
Указывайте голос по его имени (например, aria, nova, luna, felix). Всего доступно 8 предустановленных голосов. Вы не можете загружать собственные голоса или клонировать чужие, только использовать эти стандартные варианты для озвучки вашего текста.
Первый запрос
curl
curl https://api.play82q.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.play82q.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.play82q.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
Для начала работы с API TextVoice необходимо создать аккаунт на странице /get-api-key/. Регистрация доступна через Google или по электронной почте с паролем. Важно учитывать, что аккаунт привязывается к конкретному сайту сети.
После авторизации вы получите уникальный API-ключ и начальный баланс. Для пользователей, вошедших через Google, доступен пробный период с кредитом $0.50 (около 50 000 символов), действующим 7 дней. Аккаунты, созданные по email, стартуют без бонусных средств.
Регистрация аккаунта
Перейдите на страницу /get-api-key/ и выберите способ входа: через Google или создание учетной записи по email и паролю. Процесс занимает минуту, после чего вы получаете доступ к панели управления.
Просмотр ключа
На главной панели отображается ваш активный ключ (начинается на tts-...), текущий баланс, информация о пробном периоде и количество оставшихся символов. Ключ можно использовать сразу в запросах к API.
Сброс ключа
Вы можете выпустить новый ключ в любой момент. Как только будет создан новый ключ, предыдущий перестает действовать мгновенно. Это позволяет оперативно сменить доступ при утечке данных без изменения настроек в коде.
Первый запрос
API работает по принципу отправки текста и получения аудиофайла. Отправьте POST-запрос на конечную точку, указав модель, голос и текст, и получите готовый звуковой файл в ответе. Это позволяет легко интегрировать озвучку в ваши статьи и посты без сложных настроек.
Для быстрого теста используйте команду curl ниже. Она отправляет короткий текст и возвращает аудио в формате mp3. Убедитесь, что заголовок Authorization содержит ваш активный ключ API, полученный на странице личного кабинета.
Пример curl
Отправьте запрос, заменив YOUR_API_KEY на ваш ключ. Скрипт сохранит результат в файл output.mp3.
- curl -X POST https://api.play82q.com/v1/audio/speech \
- -H 'Authorization: Bearer YOUR_API_KEY' \
- -H 'Content-Type: application/json' \
- -d '{"model": "tts-1", "input": "Привет, это тестовое аудио.", "voice": "nova", "response_format": "mp3"}' \
- -o output.mp3
JSON структура
Тело запроса должно содержать обязательные поля: model, input и voice. Поле input поддерживает текст до 4096 символов, включая пробелы и знаки препинания. Поле response_format определяет кодировку выходного файла.
- model: "tts-1" или "tts-1-hd" (один движок, одинаковая цена)
- input: строка текста (макс. 4096 символов)
- voice: один из 8 доступных голосов (например, aria, nova)
- response_format: mp3, wav, opus, flac или pcm
Ожидаемый ответ
При успешном синтезе API возвращает аудиофайл в запрошенном формате. Если текст превышает лимит символов, потребуется разделить его на части и объединить файлы. Неудачные запросы не списывают средства с баланса.
Использование SDK
Для интеграции с нашим API не нужно изучать проприетарную библиотеку. Мы используем ту же структуру данных, что и OpenAI, поэтому вы можете подключиться к сервису TextVoice через официальные SDK, просто изменив базовый URL. Это позволяет использовать знакомые инструменты без дополнительных зависимостей.
Вам не нужно искать наш собственный SDK или скачивать специфичные пакеты. Достаточно указать адрес https://api.play82q.com/v1 в настройках клиента. Все остальные параметры, такие как модель tts-1 или tts-1-hd, передаются стандартным способом, что упрощает миграцию или добавление озвучки в существующие проекты.
Библиотека OpenAI
Используйте официальный пакет OpenAI (например, openai для Python). Он поддерживает необходимые методы для генерации аудио и полностью совместим с нашим интерфейсом. Вам не нужно устанавливать дополнительные расширения или плагины для WordPress, так как API работает через HTTP-запросы.
Библиотека обрабатывает сериализацию JSON и авторизацию. Вы отправляете текст, получаете аудиофайл в запрошенном формате. Это стандартный подход, который не требует глубокой настройки протокола.
- Поддержка всех популярных языков программирования через OpenAI SDK
- Стандартная структура запроса без кастомных полей
Настройка base_url
Ключевой шаг — изменение базового URL эндпоинта. Укажите https://api.play82q.com/v1 вместо стандартного адреса OpenAI. Это направит запросы к нашим серверам генерации речи.
В заголовке авторизации используйте свой ключ формата tts-.... Лимиты запросов и структура ответов остаются идентичными стандартному протоколу, но обрабатываются нашим бэкендом.
Пример кода на Python
Приведенный ниже код демонстрирует минимально необходимый фрагмент для получения аудиофайла. Убедитесь, что установлен пакет openai версии 1.0 или выше.
Код использует переменную окружения или явную передачу ключа. Результат записывается в файл output.mp3. Вы можете изменить формат на wav или opus в зависимости от требований вашего проекта.
base_url='https://api.play82q.com/v1'model='tts-1-hd'voice='nova'response_format='mp3'
Параметры запроса
Каждый запрос к API требует указания модели, голоса и формата выходного файла. Эти три параметра определяют качество синтеза, тембр звучания и совместимость полученного аудио с вашими инструментами публикации.
Выбор модели не влияет на стоимость (tts-1 и tts-1-hd стоят одинаково), а выбор голоса — на восприятие контента вашим читателем. Все параметры передаются в теле запроса в формате JSON.
Модель tts-1
Для генерации речи доступны две модели: "tts-1" и "tts-1-hd". Они используют один и тот же движок синтеза, поэтому качество звука идентично. Вы можете выбрать любую из них в зависимости от предпочтений, так как цена за символ одинакова для обеих.
Выбор голоса
Система поддерживает восемь предустановленных голосов: Aria, Nova, Luna, Sage, Felix, Milo, Atlas и Orion. Каждый голос имеет характерную интонацию — от спокойной до энергичной. Вы можете использовать любой голос для любого языка из списка поддерживаемых.
- Aria: тёплый, чёткий диктор
- Felix: энергичный, для рекламы
- Atlas: нейтральный, новостной стиль
- Orion: глубокий, документальный стиль
Формат вывода
Вы можете выбрать один из пяти форматов аудио: MP3, WAV, Opus, FLAC или PCM. MP3 и Opus оптимальны для веба, WAV и FLAC обеспечивают высокое качество без сжатия, а PCM — сырой несжатый звук.
Обработка ошибок
API возвращает стандартные HTTP-коды состояния. Ошибки 4xx указывают на проблему с ключом или параметрами, а 5xx — на временные сбои сервера. При сбое синтеза средства возвращаются на баланс, поэтому повторный запрос не будет оплачен дважды.
Коды ответов
Используйте код 200 для успешного получения аудиофайла. Коды 400–401 означают неверный формат запроса или истёкший/неверный ключ API. Код 429 применяется при превышении лимитов (60 запросов в минуту для обычных аккаунтов, 10 — до первого пополнения).
- 200: Успех, аудиофайл в ответе
- 400: Неверный формат JSON или параметры
- 401: Неверный или отсутствующий ключ
- 429: Превышен лимит запросов
Лимиты запросов
Лимит составляет 60 запросов в минуту на один ключ API. Для новых аккаунтов без пополнения лимит ниже — 10 запросов в минуту. Превышение лимита возвращает код 429 до тех пор, пока окно не обновится.
- 60 запросов/мин для стандартных аккаунтов
- 10 запросов/мин до первого пополнения
- Лимит считается на один API-ключ
Обработка таймаутов
Короткие фразы генерируются за несколько секунд, но при высокой нагрузке запросы могут стоять в очереди. Если ответ не приходит более 30 секунд, проверьте баланс и попробуйте запрос снова. Повторный запрос при таймауте безопасен, так как неудачные запросы не списывают средства.

Ограничения и очереди
API обрабатывает запросы последовательно, что влияет на скорость генерации при высокой нагрузке. Если в очереди уже есть задачи, новый запрос будет выполнен только после их завершения.
60 запросов в минуту
Лимит составляет 60 запросов в минуту на один ключ API. До первого пополнения баланса этот лимит снижен до 10 запросов в минуту.
- Максимум: 60 запросов/мин
- Новые аккаунты: 10 запросов/мин
- Лимит на один ключ
Очередь обработки
Запросы обрабатываются по очереди. При большой нагрузке время ожидания может увеличиться. Каждая задача выполняется последовательно.
Время ответа
Длинные тексты генерируются примерно в реальном времени (около 25 символов текста в секунду аудио). Короткие фразы могут занимать несколько секунд. При нагрузке в очереди время ответа возрастает.
Поддержка языков
Сервис поддерживает 23 языка, включая русский, английский, немецкий и французский. Каждый голос способен воспроизводить любой из доступных языков без дополнительных настроек. Список включает арабский, китайский, датский, греческий, иврит, хинди, японский, корейский, малайский, норвежский, польский, португальский, шведский, турецкий и суахили. Языки, не указанные в этом списке, такие как вьетнамский или украинский, не поддерживаются.
Параметр language
Вы можете явно указать язык в запросе с помощью ISO кода. Это гарантирует корректное произношение, особенно если текст написан латиницей, но не на английском. Например, используйте "ru" для русского или "de" для немецкого. Если параметр не указан, система попытается определить язык автоматически.
- ar — Arabic
- zh — Chinese
- da — Danish
- de — German
- en — English
- es — Spanish
- fi — Finnish
- fr — French
- el — Greek
- he — Hebrew
- hi — Hindi
- it — Italian
- ja — Japanese
- ko — Korean
- ms — Malay
- nb — Norwegian
- pl — Polish
- pt — Portuguese
- ru — Russian
- sv — Swedish
- tr — Turkish
- sw — Swahili
Автоопределение
Если вы не укажете язык, система попытается определить его по тексту. Для текста на латинице по умолчанию выбирается английский. Это упрощает настройку для русскоязычных авторов, пишущих на родном языке кириллицей, так как автоопределение справляется с этим сценарием без дополнительных параметров.
Примеры кодов
Передавайте код языка в поле language вашего JSON-запроса. Это гарантирует, что синтезатор использует правильные фонетические правила для выбранного языка. Например, для немецкого текста используйте "de", а для испанского — "es".
Форматы аудио
API поддерживает пять форматов выходного аудио: mp3, wav, opus, flac и pcm. Выбор формата зависит от ваших требований к качеству, размеру файла и совместимости с плеером. Все форматы возвращают один и тот же синтезированный аудиопоток в указанной кодировке.
MP3 и WAV
MP3 — универсальный сжатый формат с потерями, оптимальный для веб-плееров и мобильных приложений. WAV обеспечивает несжатое аудио высокого качества, подходящее для профессионального монтажа или записи в студийном качестве. Вес файла в WAV значительно превышает MP3 при том же содержимом.
- MP3: сжатие, малый размер, совместимость
- WAV: несжатый, высокое качество, больший размер
Opus и FLAC
Opus предлагает эффективное сжатие с низким битрейтом, сохраняя хорошее качество речи. FLAC — формат без потерь, идеальный для архивации или дальнейшего редактирования без деградации звука. Оба формата поддерживаются для всех голосов и языков.
- Opus: эффективное сжатие, низкий битрейт
- FLAC: без потерь, для архивации
PCM сырой звук
Формат PCM возвращает необработанные сырые аудиоданные без заголовков контейнера. Он подходит для интеграции с системами, требующими прямого доступа к бинарному потоку, или для последующей упаковки в собственный контейнер разработчиком.
- PCM: сырые данные, без заголовков
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения.
23 языка
Любой голос может говорить на любом из этих языков.
