Часто задаваемые вопросы
Какой формат данных принимает API?
API принимает JSON-запросы с полями model, input, voice, response_format и speed. Текст передается в поле input, а аудио возвращается в указанном формате (mp3, wav, opus, flac, pcm). Структура запроса идентична OpenAI, поэтому можно использовать стандартные SDK, изменив base_url на https://api.playpk55.com/v1.
Можно ли использовать библиотеку OpenAI?
Да, официальный SDK OpenAI полностью совместим. Вам нужно лишь изменить base_url на https://api.playpk55.com/v1 и передать свой API-ключ. Это позволяет использовать знакомый интерфейс для генерации аудио без необходимости писать собственный клиент или парсить нестандартные форматы ответов.
Что делать при ошибке лимита запросов?
Лимит составляет 60 запросов в минуту на ключ (10 до первого пополнения). При превышении получите ошибку. Решения: увеличьте интервал между запросами, используйте несколько ключей или пополните баланс. Лимиты применяются к каждому ключу авторизации отдельно, поэтому распределение нагрузки между ключами эффективно.
Как указать язык для текста на латыни?
Если язык не указан, система предполагает английский для латиницы. Для других языков (например, испанского или немецкого) обязательно передайте параметр language с ISO-кодом. Это гарантирует правильное произношение и интонацию, так как язык определяется по скрипту (латиница по умолчанию — английский).
Возвращается ли ключ при смене?
При выпуске нового ключа старый перестает действовать немедленно. Старый ключ не возвращается, он просто становится невалидным. Вы можете выпустить новый ключ в любой момент через личный кабинет. Убедитесь, что обновили ключ во всех сервисах, где он используется, чтобы избежать сбоев.
Какой максимальный размер текста?
Максимальный размер одного запроса — 4096 символов. Для длинных сценариев разбивайте текст на части до этого лимита и объединяйте полученные аудиофайлы. Это стандартный подход для работы с длинными видео. Символы пробела и пунктуации также учитываются в лимите символов для расчета стоимости.
Поддерживает ли API потоковую передачу?
Нет, API не поддерживает потоковую передачу (streaming) или WebSocket. Аудио возвращается как готовый файл после завершения синтеза. Запросы обрабатываются последовательно, поэтому при высокой нагрузке может быть очередь. Для мгновенного аудио используйте короткие фразы, так как генерация занимает время.
Есть ли SSML-теги в ответе?
SSML-теги не поддерживаются. API принимает чистый текст и генерирует аудио на основе выбранных параметров скорости и голоса. Вы не можете управлять интонацией или паузами через разметку. Для контроля темпа используйте параметр speed в диапазоне от 0.25 до 4.0 для ускорения или замедления.
Как получить список доступных голосов?
Отправьте GET-запрос на endpoint /v1/voices. Там будут перечислены все 8 голосов, доступные языки, форматы и цены. Также доступен endpoint /v1/models для получения информации о моделях tts-1 и tts-1-hd. Используйте эти данные для корректного формирования запросов к основному эндпоинту генерации аудио.
Какая скорость генерации аудио?
Скорость примерно равна реальному времени: 25 символов текста в секунду аудио. Короткие фразы генерируются за несколько секунд. При нагрузке запросы могут стоять в очереди. Это не потоковая генерация, а пакетная обработка, поэтому итоговое время зависит от длины текста и загрузки сервера.
Первый запрос
curl
curl https://api.playpk55.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.playpk55.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.playpk55.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 необходимо создать аккаунт на странице регистрации. Доступен вход через Google или регистрация по электронной почте с паролем. Учетные записи привязываются к домену playpk55.com.
На странице управления ключами отображается текущий токен, баланс, остаток символов и история использования. Ключ используется в заголовке Authorization для аутентификации запросов.
Регистрация аккаунта
Зарегистрироваться можно двумя способами: через аккаунт Google или по адресу электронной почты. При входе через Google автоматически начисляется пробный баланс $0.50 (около 50 000 символов) на 7 дней. Аккаунты, созданные по email, начинают работу без пробного баланса.
Регистрация занимает минуту. После подтверждения доступа вы получаете доступ к личному кабинету и странице с API-ключом.
Страница ключей
На странице /get-api-key/ отображается активный токен, текущий баланс и количество оставшихся символов. Здесь также доступна готовая команда curl для первого запроса и история использования.
Ключ передается в заголовке Authorization: Bearer. Один активный ключ на аккаунт. При создании нового старый прекращает действие мгновенно.
Генерация нового ключа
Нажмите кнопку генерации на странице ключей. Новый токен становится активным сразу, старый — недействителен.
Это полезно для разделения доступа между проектами или при подозрении на утечку. Перегенерация не влияет на баланс или историю.
Первый запрос (curl)
Для начала работы отправьте POST-запрос на endpoint /v1/audio/speech. API ожидает JSON-тело с текстом, моделью и голосом, возвращая готовый аудиофайл.
Аутентификация выполняется через заголовок Authorization. Укажите ваш уникальный ключ, полученный после регистрации, чтобы сервис идентифицировал аккаунт и списал средства.
Структура JSON
Тело запроса содержит поля model (tts-1 или tts-1-hd), input (текст до 4096 символов), voice (выбор из 8 presets) и опциональные language, speed, response_format.
Заголовок Authorization
Передавайте ключ в формате Bearer tts-ваш_ключ. Один аккаунт имеет один активный ключ; при выпуске нового старый становится недействительным мгновенно.
Пример команды
Отправьте curl-запрос для генерации аудио. Пример использует голос nova в формате mp3.
- curl -X POST https://api.playpk55.com/v1/audio/speech \ -H "Authorization: Bearer tts-KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Привет, это тестовый текст для YouTube видео.", "voice": "nova", "response_format": "mp3"}'
Интеграция с OpenAI SDK
Используйте официальный OpenAI SDK для Python или Node.js. Это позволяет применять знакомые методы и структуры объектов, минимизируя время на интеграцию в существующие конвейеры генерации аудио.
Установка библиотеки
Установите последнюю версию пакета через стандартный менеджер зависимостей вашего проекта. Библиотека предоставляет все необходимые инструменты для формирования запросов к API без написания дополнительного кода для HTTP-соединений.
Изменение base_url
Переопределите базовый URL клиента, указав адрес нашего API: https://api.playpk55.com/v1. Это перенаправит все вызовы методов синтеза на наши серверы, сохраняя совместимость с исходным форматом данных.
Передача ключа
Передайте ваш API-ключ через заголовок авторизации или переменную окружения. Ключ должен начинаться с префикса tts- и быть активным в аккаунте на странице /get-api-key/.
- Ключи можно регенерировать в любой момент через личный кабинет
- Старый ключ инвалидируется мгновенно при создании нового
Параметры запроса
Для синтеза аудио используется POST-запрос к эндпоинту /v1/audio/speech. Основные параметры передаются в теле запроса в формате JSON. Каждый параметр определяет характер генерируемого аудиофайла.
Поле input (текст)
Поле input принимает строку текста длиной до 4096 символов. Пробелы и знаки препинания учитываются как символы. Для длинных сценариев требуется разбивка на части и последующее склейка аудиофайлов.
Поле voice (голос)
Доступно 8 предустановленных голосов с разными тембрами. Например, aria для ясного нарратива, nova для динамичного контента или atlas для нейтральной подачи. Голос не привязан к языку, но для неанглийского текста латиницей рекомендуется явно указывать поле language.
- aria: теплый, ясный рассказчик
- nova: яркий, энергичный
- luna: мягкий, для историй
- sage: спокойный, инструктивный
- felix: энергичный, для промо
- milo: дружелюбный, разговорный
- atlas: нейтральный, новостной
- orion: глубокий, документальный
Поле model (tts-1, tts-1-hd)
Доступны две модели: tts-1 и tts-1-hd. Обе используют один и тот же движок синтеза и имеют одинаковую стоимость. Выбор модели влияет только на техническое качество, но не на цену или скорость генерации.
Форматы ответа
Выбор формата зависит от этапа конвейера монтажа. MP3 обеспечивает оптимальный баланс между размером файла и совместимостью с большинством видеоредакторов. WAV предпочтителен для черновых версий, где критична бескомпромиссная скорость декодирования без артефактов сжатия.
MP3
Формат по умолчанию для финального экспорта. Обеспечивает сжатие с потерями, снижая объем данных при сохранении приемлемого качества звука. Идеален для прямой загрузки в таймлайн видеоредакторов или отправки на хостинг.
WAV
Некомпрессированный формат без потерь. Подходит для промежуточной обработки аудио, например, при наложении эффектов или эквализации перед финальным рендером. Занимает больше места, но исключает многократное пережатие.
OPUS, FLAC, PCM
OPUS предлагает сжатие с минимальной задержкой. FLAC сохраняет исходное качество без потерь, сжимая данные для экономии места. PCM возвращает сырой аудиопоток.

Обработка ошибок
API возвращает стандартные HTTP-коды для индикации статуса. Код 400 означает ошибку валидации параметров. Код 500 сигнализирует о временном сбое сервера.
Если синтез не удался, средства за этот запрос возвращаются в полном объеме. Баланс обновляется автоматически.
Коды ответа
Стандартные коды HTTP используются для диагностики. 400 Bad Request возникает при неверных данных. 500 Internal Server Error указывает на временный сбой.
Возврат средств при ошибке
Плата взимается только за успешный синтез. При сбое генерации стоимость запроса возвращается на баланс аккаунта.
Лимиты (429)
Доступно 60 запросов в минуту на ключ (10 до первого пополнения). При превышении лимита сервер возвращает код 429 Too Many Requests.
Параметр speed
Параметр speed управляет скоростью речи в диапазоне от 0.25 до 4.0. Значение по умолчанию равно 1.0. Изменение скорости влияет на длительность сгенерированного аудиофайла и восприятие голоса.
Диапазон 0.25–4.0
Вы можете ускорить или замедлить речь в зависимости от задачи. Значения ниже 1.0 замедляют произношение, значения выше 1.0 — ускоряют. Экстремальные значения могут сделать речь менее разборчивой.
- Минимальное значение: 0.25 (в 4 раза медленнее нормы)
- Максимальное значение: 4.0 (в 4 раза быстрее нормы)
Влияние на длительность
Скорость напрямую влияет на время генерации и длину файла. При стандартной скорости синтез занимает примерно 25 символов текста в секунду. Ускорение сокращает время ожидания в очереди, но увеличивает нагрузку на клиента при обработке.
Качество на высоких скоростях
При значении выше 2.0 интонация может стать менее естественной, а паузы между словами сократятся. Для аудиокниг или обучающих материалов рекомендуется скорость не выше 1.5. Формат аудио и качество синтеза остаются неизменными независимо от скорости.
Конец точки API
API предоставляет три основные конечные точки для интеграции. Основной метод POST генерирует аудиофайл по заданному сценарию. Два дополнительных метода GET позволяют получить метаданные о доступных голосах и моделях без отправки текста на синтез.
Используйте GET-эндпоинты для предварительной проверки доступных опций и получения актуальных списков голосов или моделей перед отправкой основного запроса на генерацию аудио.
POST /v1/audio/speech
Основная конечная точка для синтеза речи. Принимает JSON-тело с текстом и параметрами, возвращает аудиофайл в указанном формате.
Текст ограничивается 4096 символами. Для длинных сценариев требуется разбивка на части и последующее объединение файлов.
- Метод: POST
- Формат ввода: JSON
- Лимит текста: 4096 символов
GET /v1/voices
Возвращает список из 8 доступных голосов, поддерживаемых языков и форматов. Используется для валидации параметра voice перед запросом.
Ответ содержит технические характеристики каждого голоса без генерации аудио.
GET /v1/models
Возвращает доступные модели синтеза: tts-1 и tts-1-hd. Обе модели используют один и тот же движок и тарификацию.
Эндпоинт позволяет убедиться в доступности моделей перед использованием.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Некоторые тембы могут утомлять при длительном прослушивании из-за избыточной энергичности или, наоборот, казаться монотонными.
23 языка
Любой голос может говорить на любом из этих языков.
