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

Интеграция с OpenAI SDK
Используйте официальный OpenAI SDK, изменив базовый URL на https://api.playthanjai.com/v1. Это позволяет применять стандартные методы без переписывания логики запросов. Ключевая настройка — указание правильного endpoint для маршрутизации запросов к нашей инфраструктуре.
Методы SDK работают идентично оригиналу: передайте текст, модель и голос в стандартном формате. Интеграция занимает несколько строк кода, что ускоряет внедрение TTS в приложения голосовых помощников и чат-ботов.
Изменение base_url
Укажите базовый URL https://api.playthanjai.com/v1 при инициализации клиента SDK. Это перенаправляет запросы на наши серверы, сохраняя совместимость с существующей структурой запросов OpenAI. Изменение требует минимум правок в коде клиента.
Использование стандартных методов
Используйте метод .audio.create() для синтеза речи. Передайте параметры input, voice и model в теле запроса. Структура данных полностью соответствует спецификации OpenAI Speech endpoint, что упрощает тестирование и отладку.
Настройка авторизации
Передайте API-ключ в заголовке Authorization: Bearer tts-<ваш_ключ>. Ключ генерируется в личном кабинете после регистрации. Один активный ключ на аккаунт; при смене старый прекращает действие мгновенно.
Параметры запроса
Тело запроса отправляется в формате JSON и содержит обязательные поля. Параметр model принимает значения tts-1 или tts-1-hd. Обе модели используют один и тот же движок синтеза и тарифицируются одинаково, поэтому выбор зависит только от предпочтительного качества звука без изменения стоимости.
Поле input принимает текстовую строку длиной до 4096 символов. Укажите voice из списка доступных вариантов. Параметр response_format определяет формат файла (mp3, wav, opus, flac, pcm). Скорость воспроизведения настраивается полем speed в диапазоне от 0.25 до 4.0.
Поля input, voice, model
Поле input содержит текст для синтеза. Максимальная длина — 4096 символов на один запрос. Если текст длиннее, его необходимо разделить на части и объединить аудиозаписи после обработки.
Параметр model принимает значения tts-1 или tts-1-hd. Обе модели используют один и тот же движок синтеза и тарифицируются одинаково. Выбор модели не влияет на цену за символ.
Параметр voice требует указания одного из восьми предустановленных голосов. Формат ответа задается полем response_format.
- input: строка, до 4096 символов
- model: tts-1 или tts-1-hd
- voice: имя голоса (например, aria)
- response_format: mp3, wav, opus, flac, pcm
Настройка скорости ответа
Параметр speed управляет скоростью произношения. Допустимый диапазон значений составляет от 0.25 до 4.0. Значение 1.0 соответствует стандартной скорости воспроизведения.
Указание языка для текста
Поле language принимает ISO-код языка. Если параметр не указан, язык определяется автоматически по скрипту. Текст на латинице по умолчанию распознается как английский. Для других языков с латинским алфавитом (например, немецкого или французского) язык необходимо задавать явно.
Форматы выходного аудио
API поддерживает пять форматов выходного аудио: MP3, WAV, OPUS, FLAC и PCM. Выбор формата зависит от требований к размеру файла и совместимости плеера в вашем голосовом помощнике или чат-боте.
Для экономии трафика и дискового пространства предпочтительны сжатые форматы. Все форматы возвращаются как бинарные данные в ответе HTTP-запроса без дополнительных заголовков.
Формат MP3
MP3 — формат сжатия с потерями. Он обеспечивает оптимальное соотношение размера файла и качества, что делает его универсальным выбором для большинства голосовых интерфейсов.
Файл MP3 легко воспроизводится в любых современных браузерах и мобильных приложениях без необходимости установки дополнительных кодеков.
- Наиболее компактный размер файла
- Широкая совместимость с плеерами
- Подходит для фоновой озвучки
Формат WAV
WAV предоставляет несжатое аудио с высоким качеством, сохраняя оригинальный звуковой сигнал без артефактов сжатия. Это идеальный вариант, если вам нужна максимальная точность воспроизведения.
Обратите внимание: размер WAV-файла значительно превышает MP3, что может увеличить затраты на хранение и передачу данных в ваших сервисах.
- Отсутствие артефактов сжатия
- Высокая точность звука
- Увеличенный размер файла
Поддержка OPUS и FLAC
OPUS — современный формат с высоким сжатием и отличным качеством даже при низких битрейтах. Он отлично подходит для голосовых сообщений и речевых синтезаторов.
FLAC обеспечивает сжатие без потерь. Если вам нужно сохранить исходное качество для последующей обработки или архивации, FLAC предпочтительнее MP3.
Формат PCM доступен как необработанный бинарный файл, но не подразумевает потоковую передачу в реальном времени. Это просто альтернатива для прямой загрузки аудио-файла.
- OPUS: высокое качество при малом размере
- FLAC: сжатие без потерь данных
- PCM: необработанный бинарный файл

Лимиты и ограничения
API обрабатывает запросы последовательно, что влияет на пропускную способность при высокой нагрузке. Лимиты рассчитываются на один активный ключ API, поэтому важно правильно масштабировать архитектуру вашего сервиса.
Лимит 60 запросов в минуту
Стандартный лимит составляет 60 запросов в минуту на один ключ API. Для новых аккаунтов без пополнения лимит ниже — 10 запросов в минуту. Это ограничение помогает поддерживать стабильность сервиса при массовых генерациях.
Ограничение длины текста
Один запрос может содержать текст длиной до 4096 символов. Для более дливых сценариев (например, полного сценария голосового помощника) рекомендуется разбивать текст на части и объединять полученные аудиофайлы.
Очередь обработки запросов
Запросы обрабатываются последовательно. При высокой нагрузке новый запрос может ожидать в очереди перед генерацией аудио. Среднее время генерации составляет около 25 символов в секунду для длинных текстов.
Коды ошибок и статусы
API возвращает стандартные HTTP-статусы для диагностики. Код 400 Bad Request возникает при некорректных параметрах, например, если указан неверный ID голоса или превышен лимит символов. Состояние 429 Too Many Requests сигнализирует о превышении лимита в 60 запросов в минуту. Серверные ошибки (500–599) означают временный сбой на стороне платформы.
Обработка HTTP ошибок
Для отладки анализируйте поле error в ответе JSON. При ошибке 429 добавьте логику повторной попытки (retry) с экспоненциальной задержкой. Если ошибка сохраняется, проверьте лимиты в личном кабинете или назовите ключ заново.
- 400: неверные параметры запроса
- 401: недействительный API-ключ
- 429: превышение лимита запросов
- 500–599: внутренние ошибки сервера
Статусы синтеза аудио
Синтез обрабатывается асинхронно в зависимости от нагрузки. Короткие фразы генерируются за несколько секунд, длинные тексты — в реальном времени (около 25 символов в секунду). Запросы обрабатываются последовательно, поэтому в периоды пиковой нагрузки возможна очередь.
- Очередь обработки запросов
- Генерация в реальном времени
- Возврат аудиофайла в ответе
Возврат средств при сбое
Если синтез не удался, заряд списывается не будет. Возврат средств происходит автоматически и полностью. Это гарантирует, что вы платите только за успешные запросы. Проверьте статус ответа, чтобы убедиться в успешности генерации аудиофайла.

Список доступных моделей и голосов
API поддерживает две модели синтеза: "tts-1" и "tts-1-hd". Они используют один и тот же движок, поэтому качество звука и стоимость за символ идентичны. Разница заключается только в названии для совместимости с экосистемой OpenAI.
Модели tts-1 и tts-1-hd
Обе модели принимают текст до 4096 символов и поддерживают все 8 голосов. Выбор модели не влияет на цену ($0.01 за 1000 символов) или скорость генерации. Для интеграции достаточно указать любую из них в поле model.
8 предустановленных голосов
Доступны 8 голосов: Aria, Nova, Luna, Sage (женские) и Felix, Milo, Atlas, Orion (мужские). Каждый голос может произносить текст на любом из 23 поддерживаемых языков без дополнительной настройки. Голоса основаны на лицензированных записях LibriTTS-R.
Эндпоинт для получения списка голосов
Текущий список доступных голосов, форматов и цен можно получить через GET-запрос к эндпоинту /v1/voices. Это позволяет динамически обновлять интерфейс выбора голоса в приложении без хардкода значений.
Ответ содержит метаданные для каждого голоса, включая доступные языки и форматы вывода (mp3, wav, opus, flac, pcm).
- GET https://api.playthanjai.com/v1/voices
- GET https://api.playthanjai.com/v1/models
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Голосовые помощники и чат-боты помогают стартапам автоматизировать рутинные задачи и улучшать клиентский опыт.
23 языка
Любой голос может говорить на любом из этих языков.
