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

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

Эта страница — практическое руководство для продуктовых команд, которые внедряют синтез речи в голосовых помощников и чат-ботов. Здесь описан полный цикл: от получения API-ключа и настройки авторизации до отправки первого POST-запроса и получения готового аудиофайла. Вы узнаете, как использовать стандартные инструменты вроде OpenAI SDK или cURL, не усложняя интеграцию.

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

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

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

Какой формат запроса ожидает API?

API ожидает POST-запрос на https://api.playok33.com/v1/audio/speech с телом в формате JSON. Поле input содержит текст до 4096 символов, model — «tts-1» или «tts-1-hd», voice — один из 8 вариантов, response_format — mp3, wav, opus, flac или pcm. Скорость регулируется параметром speed (0.25–4.0).

Можно ли использовать свои библиотеки?

Да, структура запроса идентична OpenAI Speech API. Вы можете использовать официальные SDK OpenAI, просто изменив base_url на https://api.playok33.com/v1 и указав ваш API-ключ. Также доступны прямые HTTP-запросы или другие библиотеки, поддерживающие этот формат JSON.

Как указать язык для латиницы?

Если язык не указан, система пытается определить его по тексту, но латиница по умолчанию принимается за английский. Для других языков, использующих латиницу (например, испанского или немецкого), обязательно передайте параметр language с ISO-кодом, чтобы избежать ошибок распознавания.

Что такое модель tts-1-hd?

tts-1-hd — это модель высокого качества, использующая тот же движок синтеза, что и tts-1. Разница заключается только в качестве звука, при этом цена остается идентичной: 10 долларов за 1 миллион символов. Обе модели поддерживают все доступные голоса и форматы.

Как отменить ключ API?

Для отмены текущего ключа просто сгенерируйте новый на странице /get-api-key/. Старый ключ перестанет действовать немедленно, а новый начнет работать сразу. Вы можете выпускать новые ключи в любое время, сохраняя при этом текущий баланс и историю запросов.

Есть ли вебхуки о завершении генерации?

Нет, вебхуки не поддерживаются. API работает синхронно: вы отправляете запрос и получаете аудиофайл в ответе сразу после завершения синтеза. Если генерация занимает время, вы просто ждете ответа от сервера. Очередь обработки может возникать при высокой нагрузке.

Какой максимальный размер текста?

Максимальный размер текста для одного запроса составляет 4096 символов. Для более длинных текстов необходимо разбить их на части по 4096 символов, сгенерировать аудио для каждой части отдельно, а затем объединить полученные аудиофайлы в один длинный файл.

Поддерживается ли параллельная обработка?

Запросы обрабатываются последовательно, поэтому под нагрузкой может возникать очередь. При высокой нагрузке запросы могут стоять в очереди, что увеличивает время генерации. Это означает, что параллельная обработка нескольких запросов может привести к задержкам, поэтому планируйте генерацию длинных текстов заранее.

Нужно ли кодировать текст в base64?

Нет, текст передается как обычная строка в поле JSON input. Кодирование в base64 не требуется. Просто убедитесь, что текст корректно закодирован в UTF-8 и не превышает лимит в 4096 символов для одного запроса к эндпоинту speech.

Как получить список доступных голосов?

Сделайте GET-запрос на https://api.playok33.com/v1/voices. Этот эндпоинт вернет список всех доступных голосов, поддерживаемых языков, форматов аудио и текущих тарифов. Вы также можете посмотреть информацию о моделях через GET https://api.playok33.com/v1/models.

Возвращается ли метаданных запроса?

В ответе возвращается аудиофайл. Метаданные запроса (время, количество символов, статус) сохраняются на сервере для биллинга и отображаются в личном кабинете на странице /get-api-key/, но не возвращаются напрямую в теле HTTP-ответа при генерации аудио.

Есть ли ограничение на длительность аудио?

Ограничение накладывается на длину входного текста: не более 4096 символов на запрос. Длительность аудио зависит от скорости чтения и текста. Типичная скорость генерации близка к реальному времени (около 25 символов в секунду), но короткие фразы могут генерироваться дольше.

Как отладить ошибку авторизации?

Убедитесь, что заголовок Authorization содержит корректный токен в формате «Bearer tts-...». Проверьте, не истек ли срок действия ключа и активен ли он. Убедитесь, что вы используете правильный base_url: https://api.playok33.com/v1, а не основной домен сайта.

Поддерживается ли кэширование запросов?

API не предоставляет встроенного механизма кэширования. Если вы отправляете один и тот же текст с теми же параметрами, сервер сгенерирует аудио заново. Для экономии средств и времени вы можете самостоятельно кэшировать результаты на стороне клиента, сохраняя полученные аудиофайлы.

Первый запрос

curl

curl https://api.playok33.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.playok33.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.playok33.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 ключа

Для начала работы с VoiceBase API необходимо создать аккаунт на странице /get-api-key/. Доступна регистрация через Google или по адресу электронной почты с паролем. Учетные записи привязаны к конкретному сайту, поэтому каждый домен предоставляет свои учетные данные.

После регистрации вы получите уникальный API-ключ. Он используется для аутентификации всех запросов к API через заголовок Authorization: Bearer.

Регистрация на сайте

Регистрация на сайте

Регистрация занимает пару минут. При входе через Google вы получаете пробный баланс $0.50, которого хватит примерно на 50 000 символов текста на 7 дней. Если вы выберете регистрацию по электронной почте и паролю, пробный баланс не начисляется.

Аккаунты создаются независимо для каждого сайта сети. Это позволяет легко изолировать тестовые и продакшен-среды, если вы используете разные домены.

  • Регистрация через Google или email + пароль
  • Пробный баланс $0.50 только при входе через Google
  • Действует в течение 7 дней

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

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

На панели управления доступен инструмент для выпуска нового API-ключа. Вы можете сгенерировать его в любой момент, если считаете, что текущий ключ мог быть скомпрометирован.

Важная особенность: при выпуске нового ключа старый становится недействительным мгновенно. Это обеспечивает надежную защиту доступа к вашему сервису без задержек.

Отображение баланса и лимитов

После авторизации вы видите текущий баланс, оставшиеся символы и статистику использования. Лимит составляет 60 запросов в минуту на один ключ (до первого пополнения — 10 запросов в минуту).

Все метаданные запросов сохраняются для биллинга, но сам текст и аудио не используются для обучения моделей. Вы можете отслеживать расходы в реальном времени.

  • Лимит: 60 запросов/мин (10 до пополнения)
  • Пробный баланс: $0.50 (Google) или $0 (email)
  • Статистика использования в реальном времени

Первый запрос через cURL

Иллюзация звуковой волны для: Первый запрос через cURL

Для быстрого тестирования интерфейса используйте cURL. Это позволяет сразу увидеть, как API обрабатывает текст и возвращает аудио, не настраивая сложные среды разработки.

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

Подготовка JSON тела запроса

Тело запроса должно содержать обязательные поля: model (например, tts-1), voice (выберите один из доступных вариантов, таких как nova или aria), input с вашим текстом и response_format. Укажите язык, если он отличается от английского, чтобы избежать ошибок распознавания скрипта.

Отправка POST запроса

Отправьте данные методом POST на эндпоинт https://api.playok33.com/v1/audio/speech. Не забудьте добавить заголовок авторизации Authorization: Bearer YOUR_API_KEY. Убедитесь, что текст не превышает 4096 символов, иначе синтез не начнётся.

Получение аудиофайла в ответе

В ответ вы получите бинарные данные аудиофайла в выбранном формате (mp3, wav и др.). Если синтез прошёл успешно, файл готов к использованию в вашем приложении. При ошибке сервер вернёт код состояния и описание проблемы.

Интеграция с OpenAI SDK

Иллюзация звуковой волны для: Интеграция с OpenAI SDK

Интеграция с OpenAI SDK позволяет использовать знакомый инструментарий для работы с VoiceBase API. Вам не нужно изучать новые библиотеки или писать сложный парсинг ответов.

Достаточно изменить базовый URL и указать ключ. Методы и структура запросов остаются идентичными, что ускоряет внедрение в существующие проекты голосовых помощников.

Изменение base_url

Укажите базовый URL https://api.playok33.com/v1 при инициализации клиента. Это перенаправляет все запросы к нашему API вместо серверов OpenAI.

Использование тех же методов

Используйте метод audio.speech для генерации аудиофайла. Параметры model, input, voice и response_format передаются в том же формате JSON, что и в оригинальном SDK.

Настройка авторизации

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

Поддерживаемые параметры

Иллюзация звуковой волны для: Поддерживаемые параметры

Этот эндпоинт принимает JSON-тело с обязательными параметрами. Вы указываете модель, голос, формат и текст. Остальные настройки опциональны.

Указание модели и голоса

Выберите модель "tts-1" или "tts-1-hd" — они используют один движок и стоят одинаково. Голос задаётся именем пресета, например, "aria" или "atlas".

  • tts-1 или tts-1-hd
  • 8 голосов: aria, nova, luna, sage, felix, milo, atlas, orion

Настройка скорости от 0.25 до 4.0

Параметр speed управляет темпом речи в диапазоне от 0.25 до 4.0. Значение 1.0 соответствует стандартной скорости. Это позволяет адаптировать речь под стиль голосового помощника.

Выбор формата вывода

Укажите формат в response_format: mp3, wav, opus, flac или pcm. MP3 оптимален для веба, WAV сохраняет высокое качество, а PCM подходит для прямой обработки.

  • mp3, wav, opus, flac, pcm

Форматы аудиофайлов

Иллюзация звуковой волны для: Форматы аудиофайлов

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

MP3 для веба и мобильных

Формат MP3 обеспечивает оптимальное соотношение качества и размера файла. Он универсально поддерживается всеми браузерами и мобильными ОС, что делает его идеальным выбором для веб-интерфейсов и мобильных приложений.

WAV для высокого качества

WAV предоставляет несжатое аудио, сохраняя исходное качество синтеза. Этот формат подходит для систем, требующих максимальной точности или проводящих дальнейшую обработку сигнала без потерь.

OPUS, FLAC и PCM для специфичных задач

OPUS эффективен для сжатия с низким битрейтом. FLAC сохраняет качество без сжатия с потерями, а PCM выдает необработанные сырые данные для прямой записи или специфичных процессоров.

Форматы аудиофайлов

Обработка длинных текстов

Иллюзация звуковой волны для: Обработка длинных текстов

API ограничивает один запрос 4096 символами, включая пробелы и знаки препинания. Для длинных текстов необходимо самостоятельно разбивать ввод на части. Это гарантирует успешную обработку и корректный расчёт стоимости, так как каждый фрагмент считается отдельной транзакцией.

Если текст превышает лимит, разбивайте его логически, сохраняя целостность смысловых блоков. Используйте простой алгоритм: отправляйте последовательно каждую часть, получая аудиофайл на выходе. Это позволяет избежать ошибок и гарантирует, что весь контент будет озвучен.

Разбиение на части по 4096 символов

Каждый запрос к эндпоинту POST /v1/audio/speech должен содержать не более 4096 символов в поле input. Если ваш текст длиннее, разделите его на сегменты. Пробелы и пунктуация учитываются в лимите. Это стандартное ограничение, которое нужно учитывать при проектировании интеграции.

Рекомендуется разбивать текст по предложениям или абзацам, чтобы не разрезать слова. Это обеспечит естественное звучание каждого фрагмента. Вы можете использовать любую библиотеку для токенизации или простую нарезку по символам, если точность не критична.

  • Лимит: 4096 символов на один запрос.
  • Учитываются пробелы и знаки препинания.
  • Разбивайте текст логически, сохраняя смысл.

Построчная генерация аудио

Отправляйте каждый фрагмент текста отдельным HTTP-запросом. API обрабатывает их последовательно, поэтому под нагрузкой может возникать очередь. Скорость генерации примерно равна реальному времени произношения: около 25 символов в секунду.

Каждый успешный запрос возвращает аудиофайл в выбранном формате. Если синтез не удался, средства не списываются. Вы можете отправлять несколько запросов с разными фрагментами, соблюдая лимит в 60 запросов в минуту на ключ.

Склейка фрагментов в один файл

Получив список аудиофайлов, объедините их в один файл на стороне клиента или сервера. Это обеспечивает непрерывное воспроизведение без пауз между частями. Формат склейки зависит от выбранного response_format.

Например, для формата MP3 используйте библиотеки вроде ffmpeg или lamejs. Для WAV — бинарное склеивание данных. Для OPUS и FLAC потребуется специфичная обработка контейнеров. PCM можно просто склеить как сырые байты.

Ограничения и лимиты

Иллюзация звуковой волны для: Ограничения и лимиты

Лимиты скорости и очереди влияют на стабильность генерации. Потоки запросов обрабатываются последовательно, поэтому при высокой нагрузке может возникать ожидание в очереди.

60 запросов в минуту на ключ

Каждый активный API-ключ ограничен 60 запросами в минуту. Это позволяет избежать перегрузки сервера и обеспечивает предсказуемое время отклика для ваших ботов и голосовых помощников.

Ограничение 10 запросов до пополнения

Для новых аккаунтов без пополнения баланса действует ограничение в 10 запросов в минуту. Это позволяет протестировать качество синтеза перед началом активной интеграции.

Обработка запросов в очереди

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

Коды ошибок и статусы

Иллюзация звуковой волны для: Коды ошибок и статусы

API возвращает стандартные коды состояния для диагностики. 200 означает успешный синтез, 400 — ошибка валидации (например, текст слишком длинный или указан неизвестный голос), 401 или 403 — невалидный или отозванный ключ API, 429 — превышение лимита в 60 запросов в минуту, 500/502 — временная ошибка сервера.

При сбое синтеза средства возвращаются на баланс в полном объеме. Если запрос завис или вернул нетипичный статус, проверьте статус ключа в личном кабинете и убедитесь, что лимиты не исчерпаны.

Обработка HTTP ошибок

Статус 429 означает, что вы превысили лимит в 60 запросов в минуту на один ключ. При новых аккаунтах лимит снижается до 10 запросов в минуту до первого пополнения. Сервис обрабатывает запросы в очереди, поэтому при высокой нагрузке время ответа может увеличиваться.

Рекомендуем реализовывать экспоненциальную задержку (retry with backoff) при получении статусов 429 или 500. Это предотвратит перегрузку API и снизит риск блокировки из-за кратковременных пиков трафика.

  • 400: Неверный формат JSON или параметр input превышает 4096 символов.
  • 401/403: Ключ API отсутствует, недействителен или был отозван при генерации нового.
  • 429: Превышен лимит запросов (60/мин или 10/мин для новых аккаунтов).
  • 500/502: Внутренняя ошибка сервера или временная недоступность сервиса синтеза.

Возврат средств при сбое

Если синтез не удался из-за ошибки сервера, стоимость запроса возвращается на ваш баланс полностью. Это гарантирует, что вы платите только за успешные генерации аудиофайлов.

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

Отслеживание статуса генерации

API является синхронным: вы отправляете POST-запрос и получаете аудиофайл в ответе или код ошибки. Отдельных эндпоинтов для асинхронного отслеживания статуса генерации пока не предусмотрено.

Для отладки используйте логи HTTP-статусов и заголовков ответа. Если аудио не возвращается, проверьте корректность переданных параметров voice и model.

Послушайте 8 голосов

Каждый образец ниже сгенерирован этим API из одного и того же предложения. Голосовые помощники и чат-боты становятся ключевыми инструментами для продуктивных команд, упрощая взаимодействие с клиентами и автоматизируя рутинные задачи в современном цифровом пространстве

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

23 языка

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

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

  1. Wikipedia
  2. openai-python on GitHub
  3. openai-node on GitHub
  4. ISO 639 language codes
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. IETF RFC 7845: Ogg Opus
  7. Python documentation
  8. W3C WAI: making audio and video accessible
  9. OpenAI API reference: create speech
  10. LibriTTS-R corpus (OpenSLR 141)
  11. curl documentation
  12. LibriVox public-domain audiobooks

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