Часто задаваемые вопросы
Какой base_url нужно использовать?
Используйте базовый URL https://api.playjp303.com/v1. Это позволяет отправлять POST-запросы на конечную точку /v1/audio/speech. Формат тела запроса соответствует стандарту OpenAI, что обеспечивает совместимость с большинством существующих клиентских библиотек и упрощает интеграцию в ваши учебные проекты.
Как установить OpenAI SDK?
Установите официальный пакет через pip: pip install openai. Затем в коде укажите base_url='https://api.playjp303.com/v1' и передайте ваш API-ключ. Это позволит использовать стандартные методы SDK для генерации аудио, адаптировав их под наш сервис без лишних изменений.
Какие модели доступны?
Доступны две модели: tts-1 и tts-1-hd. Они используют один и тот же движок синтеза и стоят одинаково. Выбор зависит только от ваших предпочтений к качеству звука. Обе модели поддерживают все доступные голоса и форматы аудио, указанные в документации.
Можно ли менять голос в запросе?
Да, вы можете выбрать любой из 8 доступных голосов в каждом запросе. Доступны варианты для разных стилей: от новостного до разговорного. Просто укажите параметр voice в теле запроса. Вы можете менять голоса даже внутри одного длинного текста, разбитого на части.
Какой формат аудио выбрать?
Поддерживаются форматы mp3, wav, opus, flac и pcm. MP3 оптимален для веба и экономии трафика. WAV и FLAC обеспечивают высокое качество без потерь. PCM подходит для сырых данных. Выберите формат в зависимости от того, где будет воспроизводиться сгенерированный аудиофайл.
Что такое rate limit?
Лимит составляет 60 запросов в минуту на один ключ API. До первого пополнения баланса лимит ниже — 10 запросов в минуту. Если вы превысите лимит, сервер вернет ошибку. Планируйте генерацию аудио с учетом этих ограничений, особенно при массовом создании уроков.
Как обрабатывать ошибки 429?
Ошибка 429 означает превышение лимита запросов в минуту. Рекомендуется реализовать логику повторных попыток с задержкой (retries). Убедитесь, что вы не отправляете больше 60 запросов в минуту. Для длинных текстов разбивайте их на части и обрабатывайте последовательно, соблюдая паузы.
Можно ли использовать один ключ на нескольких серверах?
Да, один API-ключ можно использовать на нескольких серверах или в разных приложениях одновременно. У вас может быть только один активный ключ на аккаунт. Если выпустить новый ключ, старый перестанет работать мгновенно. Это упрощает управление доступом к сервису синтеза речи.
Как получить список голосов?
Отправьте GET-запрос на конечную точку /v1/voices. Этот эндпоинт вернет информацию о доступных голосах, языках, форматах и ценах. Вы можете использовать эти данные для динамического формирования интерфейса выбора голоса в вашем приложении или скрипте автоматизации подготовки учебных материалов.
Есть ли поддержка SSL?
Да, API доступен по адресу https://api.playjp303.com/v1. Мы не предоставляем отдельных сертификатов или гарантий SLA, но соединение защищено стандартными протоколами.
Как проверить баланс через API?
Текущая документация описывает основные эндпоинты для синтеза речи и получения списка голосов. Информация о балансе, потраченных символах и статусе пробного периода отображается на странице личного кабинета после входа. Для детальной статистики используйте веб-интерфейс, так как отдельного эндпоинта для баланса нет.
Можно ли использовать API в Python?
Да, API полностью совместим с Python. Вы можете использовать официальную библиотеку openai или любые другие HTTP-клиенты, такие как requests. Просто укажите правильный base_url и передайте API-ключ в заголовке Authorization. Это позволяет легко интегрировать синтез речи в ваши скрипты и приложения.
Как работает аутентификация?
Аутентификация осуществляется через заголовок Authorization: Bearer tts-ваш_ключ. Один ключ привязан к аккаунту и используется для всех запросов. Ключ выдается при регистрации или в личном кабинете. Храните его в секрете, так как он обеспечивает доступ к вашему балансу и генерации аудио.
Что делать при таймауте?
Запросы обрабатываются последовательно, поэтому при высокой нагрузке они могут стоять в очереди. Если генерация занимает больше обычного, проверьте статус запроса. Ошибки таймаута могут возникать при длительных текстах. Рекомендуется реализовывать повторные попытки с увеличением задержки и мониторингом статуса генерации аудиофайла.
Первый запрос
curl
curl https://api.playjp303.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.playjp303.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.playjp303.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 озвучки текста для преподавателей и методистов позволяет быстро превращать учебные материалы в аудиоформат. Начните работу за несколько минут, получив ключ и отправив первый запрос.
Интерфейс совместим с популярными SDK, что упрощает интеграцию в ваши рабочие процессы без необходимости изучать сложные протоколы.
Получение API ключа
Перейдите на страницу /get-api-key/ и зарегистрируйтесь через Google или по электронной почте. После входа вы увидите ваш уникальный ключ, баланс и пример кода.
Если вы вошли через Google, вам доступен бесплатный пробный период с кредитом 0,50 доллара (около 50 000 символов), действительный в течение 7 дней.
- Регистрация через Google или email
- Мгновенный доступ к ключу API
- Тестовый кредит 0,50 $ для Google-аккаунтов
Первый запрос через curl
Отправьте POST-запрос на эндпоинт https://api.playjp303.com/v1/audio/speech. В теле запроса укажите модель, текст и голос.
Пример ниже показывает, как сгенерировать аудиофайл в формате MP3 для учебной фразы. Ключ передается в заголовке Authorization.
- Эндпоинт: POST /v1/audio/speech
- Формат: JSON
- Аутентификация: Bearer токен
Настройка OpenAI SDK
Используйте официальную OpenAI SDK, изменив базовый URL на https://api.playjp303.com/v1. Это позволяет использовать знакомые методы для генерации речи.
Метод создает аудиофайл на основе предоставленного текста, голоса и параметров скорости. Ответ содержит бинарные данные аудио.
- Использование стандартного SDK
- Изменение base_url
- Совместимость с существующим кодом
Параметры запроса
В параметрах запроса вы указываете модель, голос и формат вывода. API принимает текст до 4096 символов, возвращая готовый аудиофайл через POST /v1/audio/speech.
Модели tts-1 и tts-1-hd
Доступны две модели: «tts-1» и «tts-1-hd». Они используют один и тот же движок синтеза, поэтому качество звука и стоимость у них идентичны. Вы можете использовать любую из них, указав соответствующее значение в поле model.
Выбор голоса
Для озвучки доступно 8 предустановленных голосов с разными интонациями. Вы можете выбрать женские голоса (Aria, Nova, Luna, Sage) или мужские (Felix, Milo, Atlas, Orion). Каждый голос подходит для любого из 23 поддерживаемых языков, включая английский, но русский язык не поддерживается.
- Aria — теплый, чистый нарратор
- Nova — яркий, энергичный
- Luna — мягкий, для историй
- Sage — спокойный, инструктивный
- Felix — энергичный, для промо
- Milo — дружелюбный, разговорный
- Atlas — нейтральный, новостной
- Orion — глубокий, документальный
Форматы ответа
Вы можете выбрать один из пяти форматов аудио: mp3, wav, opus, flac или pcm. Для веба обычно используют MP3, а для архивов — FLAC или Opus. Формат указывается в поле response_format при отправке запроса.
Ограничения и лимиты
API имеет строгие ограничения, которые важно учитывать при интеграции. Максимальный размер входного текста ограничен 4096 символами на один запрос, а частота обращений к серверу регулируется для стабильной работы сервиса.
Понимание этих лимитов помогает правильно выстраивать архитектуру вашего приложения, особенно если вы генерируете большие учебные материалы или длинные диалоги для языковых курсов.
Лимит 4096 символов
Каждый вызов API принимает текст длиной не более 4096 символов. В этот лимит входят все пробелы, знаки препинания и символы. Если ваш урок длиннее, его нужно разбить на несколько частей перед отправкой.
Ограничение по частоте запросов
Для каждого API-ключа установлен лимит в 60 запросов в минуту. Этого достаточно для большинства учебных задач, но при массовом создании контента очередь запросов может возникнуть. Если вы еще не пополнили счет, лимит составляет 10 запросов в минуту.
Запросы обрабатываются последовательно, поэтому под нагрузкой время ответа может увеличиваться. Типичная скорость генерации составляет около 25 символов текста в секунду сгенерированного аудио.
Обработка длинных текстов
Для работы с длинными текстами разбейте их на фрагменты по 4096 символов на стороне клиента. После получения аудиофайлов от сервера объедините их в один файл. Это стандартный подход, так как прямой стриминг или поддержка SSML в данном API не реализованы.
Форматы аудио
API отдает аудио в форматах mp3, wav, opus, flac или pcm. Выберите формат, который лучше всего подходит для вашей инфраструктуры и устройств учащихся.
MP3 для веба
Оптимальный выбор для веб-плееров и быстрой загрузки. MP3 обеспечивает хорошее соотношение качества и размера файла, что удобно для мобильных устройств.
WAV для качества
Используйте WAV, если вам нужно исходное качество без сжатия. Этот формат подходит для дальнейшей обработки аудио в редакторах.
Opus и FLAC для архивов
Opus эффективен для потоковой передачи, а FLAC сохраняет Lossless-качество. Они полезны для архивирования уроков без потери деталей речи.
Обработка ошибок
Понимание кодов состояния HTTP помогает быстро диагностировать проблемы при интеграции TTS API. Мы используем стандартные HTTP-статусы, чтобы вы могли настроить логику обработки в вашем приложении без дополнительных сложностей.
В случае технических сбоев на стороне сервера Charge не списывается, а запрос считается успешным по оплате, если он был валидным. Это защищает ваш бюджет от ошибок сети.
Коды ошибок
Мы используем стандартные HTTP-статусы для индикации состояния запроса. Код 400 (Bad Request) возвращается при некорректном JSON или недопустимых параметрах. Код 401 (Unauthorized) означает, что ключ API неверен или просрочен. Код 429 (Too Many Requests) указывает на превышение лимита в 60 запросов в минуту. Код 500 (Internal Server Error) означает временную техническую проблему на нашей стороне.
- 400 — Неверный формат запроса или параметры
- 401 — Неверный или неактивный API-ключ
- 429 — Превышен лимит запросов (60 в минуту)
- 500 — Внутренняя ошибка сервера
Повторные запросы
Рекомендуем использовать экспоненциальную задержку при повторных попытках (retry) для кодов 429 и 500. Это позволяет избежать перегрузки сервера и успешно обработать временные пиковые нагрузки. Для кода 400 повторный запрос обычно не изменит результат, так как ошибка связана с параметрами.
Логирование
Для отладки сохраняйте HTTP-статус, код ошибки и тело ответа (если оно есть). Также полезно логировать время запроса и количество символов в input, чтобы отслеживать аномалии в использовании. Это поможет быстро выявить проблемы с интеграцией или лимитами.
- Сохраняйте HTTP-статус и код ошибки
- Логгируйте время запроса и объем данных
- Фиксируйте тело ответа сервера при сбое

Аутентификация
Для доступа к API необходим ключ, передаваемый в заголовке Authorization: Bearer tts-.... У каждого аккаунта действует только один активный ключ в данный момент.
Заголовок Authorization
Передавайте токен в HTTP-заголовке авторизации. Формат строго фиксирован: префикс Bearer и пробел перед самим ключом.
- Ключ генерируется на странице аккаунта.
- Проверяйте корректность префикса.
Формат ключа
Ключи начинаются с префикса tts- и следуют сразу за ним. Используйте ключ, сгенерированный в личном кабинете.
Смена ключа
Вы можете выпустить новый ключ в любой момент. При issuance нового токена предыдущий перестаёт действовать мгновенно, поэтому обновите его в своих скриптах.
Примеры кода
API совместим с официальными SDK OpenAI, что позволяет использовать привычные инструменты. Просто укажите базовый URL вашего домена и ключ авторизации.
Ниже приведены готовые примеры для Python, JavaScript и cURL, которые можно скопировать и запустить сразу после получения ключа на странице /get-api-key/.
Python с OpenAI SDK
Используйте стандартный пакет openai. Укажите base_url как https://api.playjp303.com/v1 и передайте ваш ключ через параметр api_key.
Текст до 4096 символов будет обработан за несколько секунд (или дольше при высокой нагрузке). Для длинных материалов разбейте текст на части программно.
- pip install openai
- from openai import OpenAI
- client = OpenAI(base_url='https://api.playjp303.com/v1', api_key='tts-...')
JavaScript запрос
Отправляйте POST-запрос на endpoint /v1/audio/speech. Используйте fetch API или библиотеки вроде axios.
Тело запроса должно содержать модель, голос, текст и желаемый формат аудио (например, mp3).
- const response = await fetch('https://api.playjp303.com/v1/audio/speech', {
- method: 'POST',
- headers: { 'Authorization': 'Bearer tts-...', 'Content-Type': 'application/json' },
Дополнительные эндпоинты
Помимо основного эндпоинта генерации аудио, API предоставляет дополнительные методы для управления ресурсами и контроля состояния аккаунта. Эти инструменты позволяют разработчикам динамически подгружать список доступных голосов, моделей и форматов, а также отслеживать расход средств без необходимости заходить в личный кабинет.
GET /v1/voices
Этот эндпоинт возвращает список всех доступных голосов, поддерживаемых языков и форматов аудио. Вы можете использовать эти данные для создания динамического интерфейса выбора озвучки в вашем приложении или LMS-системе.
- Возвращает 8 голосов (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion)
- Указывает доступные языки и форматы для каждого голоса
- Возвращает актуальную стоимость генерации в реальном времени
GET /v1/models
Возвращает доступные модели синтеза речи. На данный момент поддерживаются модели tts-1 и tts-1-hd с одинаковой ценой и качеством, что упрощает выбор конфигурации для ваших задач.
- tts-1 и tts-1-hd
- Одинаковый движок синтеза
- Одинаковая стоимость за символ
Проверка статуса баланса
Хотя основной баланс отображается на странице аккаунта, разработчики могут интегрировать проверку доступных средств напрямую в код приложения. Это позволяет автоматически приостанавливать генерацию, если средств недостаточно, и информировать преподавателей о необходимости пополнения через USDT.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Однако для латинского алфавита по умолчанию устанавливается английский, что может исказить произношение в других европейских языках.
23 языка
Любой голос может говорить на любом из этих языков.
Источники и дополнительные материалы
- Wikipedia
- TRON developer hub: TRC-20
- LibriVox public-domain audiobooks
- Node.js documentation
- ISO 639 language codes
- FFmpeg documentation
- LibriTTS-R paper (arXiv 2305.18802)
- W3C WAI: making audio and video accessible
- LibriTTS-R corpus (OpenSLR 141)
- openai-node on GitHub
- Tether (USDT)
- Creative Commons Attribution 4.0
