Часто задаваемые вопросы
Какой формат данных ожидает API?
API принимает запросы в формате JSON. В теле запроса необходимо передать текст, модель, голос и другие параметры. Ответ возвращается в виде аудиофайла в выбранном формате. Структура запроса полностью совместима с форматом, используемым в OpenAI, что позволяет использовать стандартные инструменты для отправки данных.
Можно ли использовать библиотеку requests?
Да, вы можете использовать любую HTTP-библиотеку, включая requests. Просто отправьте POST-запрос на конечную точку /v1/audio/speech с правильными заголовками и телом запроса. Библиотека не обязательна, но упрощает работу. Главное — корректно указать заголовок авторизации и параметры модели, голоса и формата вывода.
Как изменить базовый URL в OpenAI SDK?
Для использования нашего API с официальным SDK OpenAI измените параметр base_url на https://api.playbdtjl.com/v1. Затем передайте свой API-ключ и вызовите метод создания речи. Остальная логика кода останется прежней. Это позволяет быстро интегрировать наш сервис в существующие проекты без переписывания всей логики отправки запросов.
Какие модели доступны для озвучки?
Доступны две модели: tts-1 и tts-1-hd. Обе используют один и тот же движок синтеза речи и стоят одинаково. Разница заключается только в качестве аудио. Вы можете выбрать любую из них в зависимости от ваших требований к качеству.
В чем разница между tts-1 и tts-1-hd?
Обе модели используют один и тот же движок и имеют одинаковую стоимость. Модель tts-1-hd предлагает улучшенное качество звука. Для большинства задач достаточно обычной модели, Цена за символ одинакова.
Можно ли отправить аудио в формате FLAC?
Да, вы можете выбрать формат FLAC в параметре response_format. Доступны также mp3, wav, opus и pcm. Выберите тот формат, который лучше всего подходит для вашего проекта. FLAC обеспечивает сжатие без потерь, что полезно для дальнейшего редактирования.
Как указать язык для текста на латинице?
Если текст написан на латинице, но не на английском, обязательно укажите параметр language с кодом ISO нужного языка. Без этого система по умолчанию определит язык как английский. Это гарантирует правильное произношение слов и интонацию. Например, для немецкого текста укажите язык de, чтобы избежать ошибок.
Что такое код авторизации Bearer?
Это стандартный заголовок HTTP Authorization: Bearer <ваш_ключ>. Ваш API-ключ начинается с префикса tts-. Он нужен для идентификации вашего аккаунта и списания средств. Передавайте его в каждом запросе. Ключ можно получить на странице получения ключа. Храните его в секрете, так как он позволяет использовать ваш баланс.
Сколько символов можно отправить за раз?
За один запрос можно отправить текст длиной до 4096 символов. Если ваш текст длиннее, его нужно разбить на части по 4096 символов, озвучить каждую часть отдельно, а затем объединить аудиофайлы. Это стандартный подход для работы с длинными документами. Символы пробела и пунктуации также учитываются.
Почему запрос может зависнуть?
Запросы обрабатываются последовательно, поэтому под нагрузкой они могут стоять в очереди. Также на скорость влияет длина текста: короткие фразы генерируются быстрее, длинные — медленнее. В среднем скорость составляет около 25 символов в секунду. Если вы отправляете много запросов одновременно, время ответа может увеличиться из-за очереди.
Есть ли лимит на скорость генерации?
Лимит составляет 60 запросов в минуту на один ключ. До первого пополнения счета лимит ниже — 10 запросов в минуту. Это ограничение на частоту запросов, а не на скорость синтеза одного файла. Если вы превысите лимит, API вернет ошибку. Планируйте запросы с учетом этих ограничений.
Как обработать ответ с аудиофайлом?
API возвращает аудиофайл непосредственно в теле ответа. Вам нужно сохранить этот бинарный ответ в файл на сервере или передать его дальше. Формат файла зависит от вашего параметра response_format. Не нужно парсить JSON для поиска ссылки, файл приходит сразу. Это упрощает интеграцию в ваши приложения.
Можно ли использовать WebSocket для стриминга?
Нет, у нас нет поддержки потоковой передачи (streaming) через WebSocket или другие протоколы. Вы отправляете текст и получаете готовый аудиофайл целиком. Это подходит для большинства сценариев, где не требуется мгновенная отдача аудио частями. Если вам нужен именно стриминг, наш API не подойдет для этой задачи.
Где найти примеры кода на других языках?
На странице документации доступен готовый пример на curl. Для других языков вы можете использовать официальную документацию OpenAI, так как наш API полностью совместим с их форматом запросов. Просто измените базовый URL и ключ. Это позволяет использовать примеры из любых SDK, поддерживающих стандартный формат OpenAI.
Первый запрос
curl
curl https://api.playbdtjl.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.playbdtjl.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.playbdtjl.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 «Голосок» перейдите на страницу /get-api-key/ и зарегистрируйтесь. Вы можете использовать аккаунт Google или создать учетную запись по электронной почте и паролю. После входа вы получите доступ к панели управления, где сразу виден ваш API-ключ, текущий баланс и статистика использования.
Регистрация через Google или email
Регистрация занимает пару минут. Если вы войдете через Google, вам сразу начислят пробный кредит $0.50 (около 50 000 символов), который действует 7 дней. При регистрации по email пробный бонус не начисляется, но вы можете пополнить счет в любое время.
Где найти ключ в личном кабинете
В личном кабинете на странице /get-api-key/ отображается ваш уникальный ключ, начинающийся с префикса tts-. Рядом показаны текущие лимиты, баланс и пример готового cURL-запроса, который можно сразу скопировать и использовать для тестирования.
Ограничение на один активный ключ
На один аккаунт действует только один активный ключ API. Если вы сгенерируете новый ключ, старый перестанет работать мгновенно. Это упрощает управление доступом: достаточно выпустить новый ключ, если вы считаете, что старый был скомпрометирован.
Первый запрос (cURL)
Для начала работы отправьте текст на эндпоинт POST https://api.playbdtjl.com/v1/audio/speech. Используйте заголовок авторизации Bearer с вашим ключом и JSON-тело запроса.
Базовый запрос POST /v1/audio/speech
Отправляйте запрос через cURL или любой HTTP-клиент. Укажите формат application/json в заголовках. Тело запроса должно содержать обязательные поля для синтеза.
- Endpoint:
https://api.playbdtjl.com/v1/audio/speech - Method:
POST - Content-Type:
application/json
Указание модели и голоса
Выберите модель tts-1 или tts-1-hd. Они используют один движок и стоят одинаково. Укажите один из 8 доступных голосов, например, aria или nova.
- model: "tts-1" или "tts-1-hd"
- voice: "aria", "nova", "luna", "sage", "felix", "milo", "atlas", "orion"
Получение аудио в ответе
В ответе вы получите аудиофайл в выбранном формате (mp3, wav, opus, flac, pcm). Текст должен быть не длиннее 4096 символов.

Использование OpenAI SDK
Поскольку наш API совместим с форматом запросов OpenAI, вы можете использовать официальные SDK без переписывания логики. Вам нужно лишь изменить базовый URL на https://api.playbdtjl.com/v1 и передать ваш API-ключ.
Это позволяет использовать стандартные методы генерации аудио, знакомые по работе с другими сервисами. Такой подход упрощает интеграцию и экономит время на настройку.
Изменение base_url на наш домен
Укажите базовый URL нашего API в настройках SDK. Это единственный параметр, который нужно изменить по сравнению со стандартной конфигурацией OpenAI.
- base_url: https://api.playbdtjl.com/v1
Использование стандартных методов
Используйте метод создания аудио, передавая текст, голос и другие параметры. SDK автоматически сериализует запрос в JSON, как того требует наш API.
Пример кода на Python и JS
Вот простой пример на Python для генерации аудиофайла:
import os from openai import OpenAI client = OpenAI( api_key="tts-...", base_url="https://api.playbdtjl.com/v1" ) with client.audio.speech.create( model="tts-1", voice="nova", input="Привет! Это тестовый текст для озвучки.", response_format="mp3" ) as response: with open("output.mp3", "wb") as f: f.write(response.content)
Пример на JavaScript:
Параметры запроса
Параметры запроса определяют, как именно ваш текст превратится в аудиофайл. Правильная настройка этих полей позволяет получить оптимальное качество звука и нужный формат для вашего проекта.
Поле input: текст до 4096 символов
Поле input принимает строку текста длиной не более 4096 символов. В расчете учитываются все пробелы и знаки препинания. Если ваш текст длиннее, разделите его на части и объедините аудиофайлы позже.
Поле voice: выбор из 8 пресетов
Вы можете выбрать один из 8 доступных голосов: Aria, Nova, Luna, Sage, Felix, Milo, Atlas или Orion. Каждый голос имеет свою тембральную окраску и подходит для разных сценариев использования.
Поле response_format: mp3, wav, opus и др.
Формат выходного файла указывается в поле response_format. Доступны варианты: mp3, wav, opus, flac и pcm. Выберите формат, который лучше всего совместим с вашим приложением или игровым движком.
- mp3 — универсальный и компактный
- wav — высокое качество, обычно без сжатия
- opus — отличный баланс качества и размера
- flac — сжатие без потерь, подходит для архивации
- pcm — сырой аудиопоток
Настройка скорости речи
Скорость речи — это гибкий инструмент настройки темпа озвучки в вашем проекте. Вы можете замедлить или ускорить генерацию аудио, чтобы текст звучал естественно или соответствовал техническим требованиям вашего приложения.
Диапазон от 0.25x до 4.0x
Параметр speed принимает значения от 0.25 до 4.0. Значение по умолчанию равно 1.0. Уменьшение значения замедляет речь, увеличение — ускоряет. Это позволяет адаптировать голос под разные сценарии использования без переключения моделей.
Влияние скорости на время генерации
Изменение скорости напрямую влияет на время обработки запроса. Время генерации зависит от длины итогового аудио: быстрая речь создает более короткий файл, который обрабатывается быстрее. Это может помочь уложиться в лимиты скорости, если вы отправляете много запросов подряд.
Рекомендации для разных задач
Для аудиокниг или обучающих материалов рекомендуется использовать значения 0.8–1.0 для комфортного восприятия. В играх или уведомлениях можно ускорить речь до 1.5–2.0x, чтобы не задерживать пользователя. Экспериментируйте с параметром, чтобы найти идеальный баланс между понятностью и динамикой.
- Нормальная речь: 1.0
- Быстрый темп: 1.5–2.0
- Замедленный темп: 0.5–0.8

Обработка ошибок
Синтез речи — асинхронный процесс, который может занять время. Если сервер занят, запрос попадает в очередь. Ошибки обычно связаны с сетью или превышением лимитов, а не с качеством голоса.
Коды ответов API
Статус 200 означает успешное получение аудиофайла. Коды 4xx (например, 401 или 429) указывают на проблемы с ключом или лимитами. Код 5xx означает временную техническую ошибку на нашей стороне.
- 200: Успех, аудио возвращено.
- 401: Неверный API-ключ.
- 429: Превышен лимит запросов.
- 500–503: Внутренняя ошибка сервера.
Что делать при таймауте
При высокой нагрузке генерация может задерживаться. Это нормально, так как запросы обрабатываются по очереди. Не прерывайте соединение сразу, дайте серверу время на обработку. Если ошибка повторится, проверьте баланс и лимиты.
- Увеличьте таймаут подключения до 30 секунд.
- Проверьте статус ключа в личном кабинете.
- Повторите запрос через несколько секунд.
Возврат средств при ошибке
Если синтез не удался, списание не происходит (или средства возвращаются). Списание происходит только после успешного создания аудиофайла. Баланс пополнится автоматически в течение нескольких минут.
Лимиты и ограничения
Мы установили четкие лимиты, чтобы сервис оставался стабильным даже при высокой нагрузке. Один API-ключ ограничен 60 запросами в минуту. Этого достаточно для большинства сценариев использования, включая генерацию аудио для веб-приложений или игр.
Если вы еще не пополнили баланс, лимит снижен до 10 запросов в минуту. Это позволяет тестировать интеграцию без риска превысить лимиты. После пополнения лимиты автоматически восстанавливаются до стандартных значений.
60 запросов в минуту на ключ
Лимит в 60 запросов в минуту действует для всех активных ключей. Этого объема достаточно для обработки средних объемов текста. Если вам нужно больше параллельных запросов, рассмотрите использование нескольких ключей.
10 запросов в минуту до пополнения
До первого пополнения лимит составляет 10 запросов в минуту. Это позволяет безопасно протестировать API перед тем, как добавить средства. После пополнения баланс автоматически обновляется, и лимиты возвращаются к стандартным.
Ограничение длины текста
Максимальная длина текста в одном запросе — 4096 символов. Если ваш текст длиннее, разбейте его на части. Каждая часть будет обработана отдельно, а результаты можно объединить в один аудиофайл.

Тестирование и отладка
Убедитесь, что ваш API-ключ работает, отправив простой запрос на получение списка доступных голосов через GET /v1/voices. Если ответ вернется успешно, ключ авторизован и готов к работе.
В личном кабинете отображается история ваших запросов: время отправки, статус и затраченные символы. Это помогает отслеживать использование баланса и выявлять аномалии без дополнительных инструментов.
Проверка ключа авторизации
Используйте заголовок Authorization: Bearer tts-... в каждом запросе. Если ключ неактивен или удален, API вернет ошибку 401. Протестируйте доступность, сделав GET-запрос к эндпоинту /v1/voices.
Логи запросов в кабинете
Все метаданные запросов сохраняются в вашем профиле. Вы можете видеть дату, статус синтеза и объем текста. Это полезно для аудита расходов и отладки проблем с интеграцией.
Отправка тестового текста
Отправьте короткий текст (до 100 символов) через POST /v1/audio/speech. Это позволит проверить формат вывода и скорость синтеза без существенных затрат из вашего баланса.
- Используйте формат mp3 для быстрой проверки
- Проверьте корректность выбора голоса
- Убедитесь в получении аудиофайла в ответе
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Создавайте игры без кода и запустите свой инди-проект быстро и просто.
23 языка
Любой голос может говорить на любом из этих языков.
Источники и дополнительные материалы
- Wikipedia
- LibriTTS-R paper (arXiv 2305.18802)
- MDN: Web Speech API
- Python documentation
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
- ISO 639 language codes
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
- IETF RFC 7845: Ogg Opus
- FFmpeg documentation
- LibriVox public-domain audiobooks
