Документация API озвучки текста для разработчиков

Автор Редакция PlayPK · Обновлено 2026-11-18

Эта страница содержит техническую документацию по API озвучки текста для разработчиков, создающих контент для YouTube. Здесь описаны форматы запросов, параметры генерации аудио и способы интеграции с вашими скриптами. Вы найдете готовые примеры кода на curl и Python, а также описание всех доступных конечных точек.

Документация поможет вам автоматизировать превращение сценариев в готовые аудиодорожки, готовые для монтажа. Мы охватили основные сценарии использования: от первого запроса до обработки ошибок и управления скоростями. Все примеры основаны на реальных данных API и подходят для быстрой интеграции в ваши рабочие процессы без лишних абстракций.

Документация API озвучки текста для разработчиков

Часто задаваемые вопросы

Какой формат данных принимает 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.mp3

Python (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中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Получение API-ключа

Иллюзация звуковой волны для: Получение API-ключа

Для работы с API необходимо создать аккаунт на странице регистрации. Доступен вход через Google или регистрация по электронной почте с паролем. Учетные записи привязываются к домену playpk55.com.

На странице управления ключами отображается текущий токен, баланс, остаток символов и история использования. Ключ используется в заголовке Authorization для аутентификации запросов.

Регистрация аккаунта

Регистрация аккаунта

Зарегистрироваться можно двумя способами: через аккаунт Google или по адресу электронной почты. При входе через Google автоматически начисляется пробный баланс $0.50 (около 50 000 символов) на 7 дней. Аккаунты, созданные по email, начинают работу без пробного баланса.

Регистрация занимает минуту. После подтверждения доступа вы получаете доступ к личному кабинету и странице с API-ключом.

Страница ключей

Страница ключей

На странице /get-api-key/ отображается активный токен, текущий баланс и количество оставшихся символов. Здесь также доступна готовая команда curl для первого запроса и история использования.

Ключ передается в заголовке Authorization: Bearer. Один активный ключ на аккаунт. При создании нового старый прекращает действие мгновенно.

Генерация нового ключа

Нажмите кнопку генерации на странице ключей. Новый токен становится активным сразу, старый — недействителен.

Это полезно для разделения доступа между проектами или при подозрении на утечку. Перегенерация не влияет на баланс или историю.

Первый запрос (curl)

Иллюзация звуковой волны для: Первый запрос (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

Используйте официальный 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

Параметр 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

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 из одного и того же предложения. Некоторые тембы могут утомлять при длительном прослушивании из-за избыточной энергичности или, наоборот, казаться монотонными.

Аватар голоса aria
ariaженский
Аватар голоса nova
novaженский
Аватар голоса luna
lunaженский
Аватар голоса sage
sageженский
Аватар голоса felix
felixмужской
Аватар голоса milo
miloмужской
Аватар голоса atlas
atlasмужской
Аватар голоса orion
orionмужской

23 языка

Любой голос может говорить на любом из этих языков.

Источники и дополнительные материалы

  1. Wikipedia
  2. IETF RFC 7845: Ogg Opus
  3. Tether (USDT)
  4. MDN: Web Speech API
  5. Creative Commons Attribution 4.0
  6. Python documentation
  7. openai-node on GitHub
  8. ISO 639 language codes
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. openai-python on GitHub
  11. LibriTTS-R corpus (OpenSLR 141)
  12. TRON developer hub: TRC-20

Больше на этом сайте