Часто задаваемые вопросы
Как получить API-ключ для синтеза речи?
Зарегистрируйтесь на странице /get-api-key/ через Google или email. После входа вы увидите свой активный ключ, баланс и примеры запросов. Ключ начинается с префикса tts-. Один аккаунт привязан к конкретному сайту. Ключ можно выпустить в любой момент, старый прекращает работу мгновенно.
Можно ли использовать OpenAI SDK для нашего API?
Да, формат запросов идентичен OpenAI. Просто измените base_url на https://api.playkkbd.com/v1 и укажите наш API-ключ. Официальные SDK OpenAI работают напрямую без дополнительных адаптеров. Это упрощает интеграцию в ваши проекты и позволяет быстро начать генерацию аудио.
Какой формат ответа возвращает API?
API возвращает аудиофайл в указанном формате: mp3, wav, opus, flac или pcm. Запрос отправляется методом POST на /v1/audio/speech. Тело запроса содержит текст, модель и настройки голоса. Ответ содержит бинарные данные аудиофайла, готовые к сохранению или воспроизведению.
Что делать, если текст длиннее 4096 символов?
Разбейте текст на части по 4096 символов. Отправьте каждую часть отдельным запросом к API. Затем объедините полученные аудиофайлы в один. Это стандартный подход для длинных документов. Скорость генерации примерно равна реальному времени, поэтому обработка длинных текстов займет соответствующее время.
Есть ли поддержка SSML в запросах?
Нет, поддержка SSML отсутствует. Вы передаете обычный текст в поле input. API не поддерживает теги разметки для управления интонацией или паузами. Для контроля используйте параметры скорости и выбора голоса. Это упрощает структуру запроса и снижает сложность интеграции.
Можно ли менять скорость генерации?
Да, параметр speed принимает значения от 0.25 до 4.0. Это позволяет ускорить или замедлить речь в зависимости от задачи. Стандартная скорость обеспечивает естественное звучание. Настройки скорости применяются к любому из доступных голосов и языков без дополнительных ограничений.
Какие языки можно указать в запросе?
Доступно 23 языка, включая английский, русский, немецкий и японский. Укажите код языка (например, ru) для точного распознавания. Если язык не указан, система пытается определить его автоматически. Поддерживаемые языки перечислены в документации, остальные не поддерживаются.
Как отследить статус запроса?
Статус запроса определяется по HTTP-коду ответа. Успешные запросы возвращают аудиофайл. При ошибке возвращается код состояния и описание проблемы. Метаданные запроса сохраняются для биллинга. Вы можете проверить историю использования и статусов на панели управления после авторизации в аккаунте.
Есть ли WebSocket для потоковой передачи?
Нет, потоковая передача через WebSocket не поддерживается. API возвращает готовый аудиофайл после завершения синтеза. Вы можете получить файл только целиком. Для больших текстов используйте разбивку на части. Это обеспечивает стабильность и простоту интеграции с существующими системами.
Можно ли использовать один ключ для нескольких проектов?
Да, один активный ключ можно использовать в любом количестве проектов. Лимиты применяются на ключ, а не на проект. Вы можете генерировать новый ключ в любой момент, если старый скомпрометирован. Старый ключ перестает действовать мгновенно при выпуске нового.
Как часто нужно обновлять ключ?
Обновлять ключ нужно только по необходимости или при подозрении на утечку. Ключ действует до тех пор, пока вы не выпустите новый. Старый ключ прекращает работу мгновенно. Это позволяет гибко управлять доступом к API без привязки к срокам или подпискам.
Хранятся ли аудиофайлы на сервере?
Нет, сгенерированные аудиофайлы не сохраняются на наших серверах. Они возвращаются в ответе на запрос и передаются вам. Исходный текст используется только для синтеза и не идет на обучение моделей. Метаданные запросов хранятся для учета списаний средств и биллинга.
Первый запрос
curl
curl https://api.playkkbd.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.playkkbd.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.playkkbd.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 синтеза речи необходимо зарегистрироваться на сайте, используя аккаунт Google или электронную почту. После авторизации вы получите доступ к панели управления, где отображается ваш уникальный Bearer-токен, текущий баланс и статистика использования.
Регистрация через Google
Самый быстрый способ получить доступ — авторизация через Google. При регистрации через этот метод вы автоматически получаете пробный кредит в размере $0.50 (около 50 000 символов), который действует в течение 7 дней. Для создания аккаунта перейдите на страницу /get-api-key/.
- Мгновенный доступ к API без ввода карты
- Автоматическое начисление пробного кредита
- Доступно по адресу playkkbd.com/get-api-key/
Получение Bearer-токена
После успешной регистрации система генерирует уникальный ключ в формате tts-.... Этот токен используется в заголовке Authorization: Bearer <ключ> для аутентификации всех запросов к эндпоинту https://api.playkkbd.com/v1/audio/speech.
Смена ключа при необходимости
У каждого аккаунта есть один активный ключ. Вы можете выпустить новый ключ в любой момент через панель управления. При выпуске нового токена старый перестает действовать мгновенно, что обеспечивает безопасность при ротации ключей в CI/CD пайплайнах.
Первый запрос через cURL
Для быстрой проверки работоспособности API используйте cURL. Отправьте POST-запрос на эндпоинт /v1/audio/speech, указав модель, текст и голос в теле запроса. Это стандартный способ интеграции для фрилансеров, работающих в командной строке или скриптах.
Пример ниже демонстрирует минимальный валидный запрос. Он отправляет короткий текст и получает аудиофайл в формате MP3. Ключ авторизации передается в заголовке Authorization.
Базовый запрос POST
Отправьте запрос на https://api.playkkbd.com/v1/audio/speech методом POST. Тело запроса должно содержать JSON с полями model, input, voice и response_format. Убедитесь, что текст не превышает 4096 символов.
- Endpoint: POST https://api.playkkbd.com/v1/audio/speech
- Auth: Bearer ваш-ключ-api
- Body: JSON with model, input, voice
Передача текста и голоса
Укажите модель 'tts-1' или 'tts-1-hd'. Выберите один из 8 голосов, например 'aria' или 'felix'. Текст передается в поле input. Если язык не указан явно, система попытается определить его по скрипту, но для точности лучше задать поле language явно.
Получение аудиофайла
В ответе вы получите бинарные данные аудиофайла. Запрос обрабатывается синхронно: вы получаете готовый файл. При ошибке синтеза возврат средств происходит автоматически.
Использование OpenAI SDK
Ключевой интерфейс API воспроизводит структуру OpenAI, что позволяет использовать официальные SDK без написания кастомной логики. Это устраняет необходимость изучения проприетарных протоколов и сокращает время интеграции в существующие пайплайны генерации аудио.
Разработчики меняют базовый URL на https://api.playkkbd.com/v1, сохраняя стандартные методы отправки запросов. Поддерживаются языки Python и JavaScript, что покрывает большинство сценариев серверной разработки и бэкенда.
Настройка base_url
Для подключения передайте адрес https://api.playkkbd.com/v1 в параметр base_url вашего SDK-клиента. API ожидает тот же формат JSON-тела и заголовков авторизации, что и OpenAI.
- Базовый URL: https://api.playkkbd.com/v1
- Формат ключа: Authorization: Bearer tts-...
Использование стандартных методов
Используйте метод create() для синтеза речи. Передайте текст в поле input, модель (tts-1 или tts-1-hd) и выбранный голос. SDK автоматически сериализует данные и обработает ответ с аудиофайлом.
Поддержка Python и JS
Официальные библиотеки openai для Python и JavaScript работают «из коробки». Настройка ограничивается переопреждением эндпоинта и валидным ключом API. Это обеспечивает стабильную работу без дополнительных адаптеров.
- Поддержка Python и JS
Параметры запроса
API принимает запросы через POST-эндпоинт. Тело запроса содержит обязательные поля: модель, текст ввода и выбранный голос. Неявный язык определяется по скрипту, но для латиницы вне английского его нужно указывать явно.
Модели tts-1 и tts-1-hd
Доступны две модели: tts-1 и tts-1-hd. Они используют один и тот же движок синтеза и имеют одинаковую стоимость. Выбор между ними не влияет на цену, но позволяет настроить качество аудио.
- Обе модели предлагают идентичную цену $0.01 за 1000 символов.
Выбор голоса (8 presets)
Доступно 8 предустановленных голосов: Aria, Nova, Luna, Sage, Felix, Milo, Atlas и Orion. Каждый голос имеет свой тембр и стиль подачи, подходящие для различных типов контента.
- Женские: Aria (нарратор), Nova (энергичная), Luna (сторителлинг), Sage (инструктаж).
- Мужские: Felix (промо), Milo (диалог), Atlas (новости), Orion (документальный).
Форматы MP3, WAV, Opus
Вы можете выбрать формат выходного файла: mp3, wav, opus, flac или pcm. Это позволяет оптимизировать размер файла и совместимость с вашим плеером или редактором.
- mp3: универсальный сжатый формат.
- wav: несжатый аудиофайл высокого качества.
- opus: эффективное сжатие.
Обработка длинных текстов
API принимает текст длиной до 4096 символов за один запрос. Для более длинных сценариев клиент обязан самостоятельно разбить ввод на части и объединить результаты.
Разбиение на части по 4096 символов
Каждый запрос ограничен 4096 знаками, включая пробелы и пунктуацию. Если сценарий длиннее, разбейте текст на сегменты по 4096 символов и отправьте их последовательными запросами к POST /v1/audio/speech.
Склейка аудиофайлов
API возвращает сгенерированный аудиофайл в ответе. Клиентское приложение должно самостоятельно склеить полученные файлы в один непрерывный поток. Это обеспечивает гибкость при работе с большими объемами текста.
Управление скоростью
Параметр speed позволяет ускорить или замедлить речь в диапазоне от 0.25 до 4.0. Используйте его для адаптации таймингов под видео, но помните: генерация происходит последовательно, поэтому скорость влияет на время ожидания в очереди.

Лимиты и ограничения
API ограничивает нагрузку до 60 запросов в минуту на один ключ. До первой поправки баланса лимит составляет 10 запросов в минуту. Это обеспечивает стабильность работы при тестировании интеграций.
60 запросов в минуту
Максимальная пропускная способность ограничена 60 запросами в минуту на активный ключ API. При достижении этого лимита новые запросы будут отклоняться, пока не истечет текущая временная секунда.
- Лимит: 60 запросов/мин на ключ после пополнения
- Начальный лимит: 10 запросов/мин до первого пополнения
- Счетчик сбрасывается каждую минуту
Очередь при высокой нагрузке
Требования к авторизации
Каждый запрос должен содержать заголовок Authorization: Bearer <ваш_ключ>. Без валидного токена запросы будут отклонены с ошибкой 401. Ключ можно выпустить новый в любое время в личном кабинете.
- Заголовок:
Authorization: Bearer tts-... - Один активный ключ на аккаунт
- Старый ключ блокируется при выпуске нового
Коды ошибок
При взаимодействии с API могут возникать стандартные ошибки, связанные с авторизацией, лимитами или валидацией данных. Понимание кодов ответа HTTP помогает быстро диагностировать и устранять проблемы в рабочем процессе генерации аудио.
Ошибка авторизации
Возникает, если ключ Bearer указан неверно, истёк или аккаунт не авторизован. Убедитесь, что заголовок Authorization содержит актуальный токен формата tts-....
Превышение лимита
Сервер возвращает ошибку, если количество запросов превышает 60 в минуту для одного ключа. При высокой нагрузке запросы могут стоять в очереди, что увеличивает время ответа.
Неверный формат данных
Возникает при отправке некорректных JSON-полей или значений вне допустимых диапазонов (например, скорость вне 0.25–4.0). Проверьте структуру тела запроса и типы данных полей.
Безопасность и данные
Текст, отправленный на синтез, используется исключительно для создания аудиофайла и не включается в датасеты для обучения моделей. Сгенерированное аудио возвращается в ответе и не сохраняется на серверах после передачи клиенту.
Для защиты соединения используется стандартное HTTPS-шифрование. Мы не храним сами тексты или итоговые аудиофайлы длительно, что минимизирует риски утечки контента разработчиков.
Шифрование передачи
Все запросы к API защищены протоколом TLS 1.2+. Это обеспечивает конфиденциальность данных при передаче.
Неиспользование текста для обучения
Ваш исходный текст не используется для дообучения базовых моделей TTS. Мы сохраняем только техническую информацию для корректного начисления баланса.
Хранение метаданных для биллинга
Мы сохраняем метаданные запросов: время, объем текста в символах и статус выполнения. Эти данные нужны исключительно для выставления счетов и аудита расходов. Личные данные пользователей не передаются третьим лицам.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Английский язык поддерживается всеми голосами с высокой точностью.
23 языка
Любой голос может говорить на любом из этих языков.
