Документация API генерации речи: примеры кода и настройка

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

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

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

Документация API генерации речи: примеры кода и настройка

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

Какой HTTP метод нужно использовать для запроса?

Используйте метод POST для отправки запроса на endpoint /v1/audio/speech. Тело запроса должно содержать JSON с полями model, input, voice и response_format. Это стандартный формат, совместимый с официальными SDK OpenAI при изменении базового URL.

Нужно ли устанавливать специфичный SDK для нашей платформы?

Нет, специального SDK нет. Вы можете использовать официальные SDK OpenAI, просто изменив base_url на https://api.play82q.com/v1. Также подойдет любой HTTP-клиент для отправки POST-запросов. Мобильных SDK или плагинов для WordPress у нас нет.

Можно ли использовать ключ от другого сервиса OpenAI?

Нет, ключи уникальны для каждого аккаунта в нашей сети. Ваш ключ начинается с префикса tts- и действует только для API play82q.com. Ключи от других провайдеров здесь не подойдут для аутентификации.

Как правильно передать текст в JSON теле запроса?

Передайте текст в поле input объекта JSON. Максимальная длина — 4096 символов. Убедитесь, что текст корректно закодирован в UTF-8. Если текст длиннее, разбейте его на части, сгенерируйте аудио отдельно и объедините файлы.

Что означает код ошибки 429?

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

Можно ли генерировать аудио потоком (streaming)?

Нет, потоковая генерация (streaming) не поддерживается. API возвращает готовый аудиофайл в ответе после завершения синтеза. Вы можете получить файл в форматах mp3, wav, opus, flac или pcm, но не частичный поток данных в реальном времени.

Есть ли поддержка SSML тегов в тексте?

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

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

Укажите поле language в запросе с кодом ISO (например, ru, de, es). Если язык не указан, система попытается угадать его по скрипту, но для кириллицы это может быть неверно. Язык должен быть из списка поддерживаемых (23 языка).

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

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

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

Нет, кодировать текст в base64 не нужно. Передавайте текст как обычную строку в поле input JSON-объекта. Система сама обработает строку и преобразует её в речь, используя выбранный голос и модель синтеза.

Как работает параметр speed в запросе?

Параметр speed управляет скоростью речи в диапазоне от 0.25 до 4.0. Значение 1.0 — стандартная скорость. Вы можете ускорить или замедлить озвучку, чтобы адаптировать её под ваш контент, сохраняя естественность звучания голоса.

Влияет ли выбор модели на время генерации?

Модели tts-1 и tts-1-hd используют один и тот же движок синтеза, поэтому время генерации у них одинаковое. Различается только качество звука. Запросы обрабатываются последовательно, поэтому при высокой нагрузке может возникать очередь ожидания.

Где найти список доступных голосов?

Список голосов, языков и форматов доступен по адресу GET /v1/voices. Там также указана цена и технические характеристики. Вы можете использовать этот endpoint для получения актуальной информации перед отправкой запросов на синтез текста в аудио.

Можно ли указать голос по имени или только по ID?

Указывайте голос по его имени (например, aria, nova, luna, felix). Всего доступно 8 предустановленных голосов. Вы не можете загружать собственные голоса или клонировать чужие, только использовать эти стандартные варианты для озвучки вашего текста.

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

curl

curl https://api.play82q.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.play82q.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.play82q.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 TextVoice необходимо создать аккаунт на странице /get-api-key/. Регистрация доступна через Google или по электронной почте с паролем. Важно учитывать, что аккаунт привязывается к конкретному сайту сети.

После авторизации вы получите уникальный API-ключ и начальный баланс. Для пользователей, вошедших через Google, доступен пробный период с кредитом $0.50 (около 50 000 символов), действующим 7 дней. Аккаунты, созданные по email, стартуют без бонусных средств.

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

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

Перейдите на страницу /get-api-key/ и выберите способ входа: через Google или создание учетной записи по email и паролю. Процесс занимает минуту, после чего вы получаете доступ к панели управления.

Просмотр ключа

Просмотр ключа

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

Сброс ключа

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

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

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

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

Для быстрого теста используйте команду curl ниже. Она отправляет короткий текст и возвращает аудио в формате mp3. Убедитесь, что заголовок Authorization содержит ваш активный ключ API, полученный на странице личного кабинета.

Пример curl

Отправьте запрос, заменив YOUR_API_KEY на ваш ключ. Скрипт сохранит результат в файл output.mp3.

  • curl -X POST https://api.play82q.com/v1/audio/speech \
  • -H 'Authorization: Bearer YOUR_API_KEY' \
  • -H 'Content-Type: application/json' \
  • -d '{"model": "tts-1", "input": "Привет, это тестовое аудио.", "voice": "nova", "response_format": "mp3"}' \
  • -o output.mp3

JSON структура

Тело запроса должно содержать обязательные поля: model, input и voice. Поле input поддерживает текст до 4096 символов, включая пробелы и знаки препинания. Поле response_format определяет кодировку выходного файла.

  • model: "tts-1" или "tts-1-hd" (один движок, одинаковая цена)
  • input: строка текста (макс. 4096 символов)
  • voice: один из 8 доступных голосов (например, aria, nova)
  • response_format: mp3, wav, opus, flac или pcm

Ожидаемый ответ

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

Использование SDK

Иллюзация звуковой волны для: Использование SDK

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

Вам не нужно искать наш собственный SDK или скачивать специфичные пакеты. Достаточно указать адрес https://api.play82q.com/v1 в настройках клиента. Все остальные параметры, такие как модель tts-1 или tts-1-hd, передаются стандартным способом, что упрощает миграцию или добавление озвучки в существующие проекты.

Библиотека OpenAI

Используйте официальный пакет OpenAI (например, openai для Python). Он поддерживает необходимые методы для генерации аудио и полностью совместим с нашим интерфейсом. Вам не нужно устанавливать дополнительные расширения или плагины для WordPress, так как API работает через HTTP-запросы.

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

  • Поддержка всех популярных языков программирования через OpenAI SDK
  • Стандартная структура запроса без кастомных полей

Настройка base_url

Ключевой шаг — изменение базового URL эндпоинта. Укажите https://api.play82q.com/v1 вместо стандартного адреса OpenAI. Это направит запросы к нашим серверам генерации речи.

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

Пример кода на Python

Приведенный ниже код демонстрирует минимально необходимый фрагмент для получения аудиофайла. Убедитесь, что установлен пакет openai версии 1.0 или выше.

Код использует переменную окружения или явную передачу ключа. Результат записывается в файл output.mp3. Вы можете изменить формат на wav или opus в зависимости от требований вашего проекта.

  • base_url='https://api.play82q.com/v1'
  • model='tts-1-hd'
  • voice='nova'
  • response_format='mp3'

Параметры запроса

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

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

Выбор модели не влияет на стоимость (tts-1 и tts-1-hd стоят одинаково), а выбор голоса — на восприятие контента вашим читателем. Все параметры передаются в теле запроса в формате JSON.

Модель tts-1

Для генерации речи доступны две модели: "tts-1" и "tts-1-hd". Они используют один и тот же движок синтеза, поэтому качество звука идентично. Вы можете выбрать любую из них в зависимости от предпочтений, так как цена за символ одинакова для обеих.

Выбор голоса

Система поддерживает восемь предустановленных голосов: Aria, Nova, Luna, Sage, Felix, Milo, Atlas и Orion. Каждый голос имеет характерную интонацию — от спокойной до энергичной. Вы можете использовать любой голос для любого языка из списка поддерживаемых.

  • Aria: тёплый, чёткий диктор
  • Felix: энергичный, для рекламы
  • Atlas: нейтральный, новостной стиль
  • Orion: глубокий, документальный стиль

Формат вывода

Вы можете выбрать один из пяти форматов аудио: MP3, WAV, Opus, FLAC или PCM. MP3 и Opus оптимальны для веба, WAV и FLAC обеспечивают высокое качество без сжатия, а PCM — сырой несжатый звук.

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

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

API возвращает стандартные HTTP-коды состояния. Ошибки 4xx указывают на проблему с ключом или параметрами, а 5xx — на временные сбои сервера. При сбое синтеза средства возвращаются на баланс, поэтому повторный запрос не будет оплачен дважды.

Коды ответов

Используйте код 200 для успешного получения аудиофайла. Коды 400–401 означают неверный формат запроса или истёкший/неверный ключ API. Код 429 применяется при превышении лимитов (60 запросов в минуту для обычных аккаунтов, 10 — до первого пополнения).

  • 200: Успех, аудиофайл в ответе
  • 400: Неверный формат JSON или параметры
  • 401: Неверный или отсутствующий ключ
  • 429: Превышен лимит запросов

Лимиты запросов

Лимит составляет 60 запросов в минуту на один ключ API. Для новых аккаунтов без пополнения лимит ниже — 10 запросов в минуту. Превышение лимита возвращает код 429 до тех пор, пока окно не обновится.

  • 60 запросов/мин для стандартных аккаунтов
  • 10 запросов/мин до первого пополнения
  • Лимит считается на один API-ключ

Обработка таймаутов

Короткие фразы генерируются за несколько секунд, но при высокой нагрузке запросы могут стоять в очереди. Если ответ не приходит более 30 секунд, проверьте баланс и попробуйте запрос снова. Повторный запрос при таймауте безопасен, так как неудачные запросы не списывают средства.

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

Ограничения и очереди

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

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

60 запросов в минуту

Лимит составляет 60 запросов в минуту на один ключ API. До первого пополнения баланса этот лимит снижен до 10 запросов в минуту.

  • Максимум: 60 запросов/мин
  • Новые аккаунты: 10 запросов/мин
  • Лимит на один ключ

Очередь обработки

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

Время ответа

Длинные тексты генерируются примерно в реальном времени (около 25 символов текста в секунду аудио). Короткие фразы могут занимать несколько секунд. При нагрузке в очереди время ответа возрастает.

Поддержка языков

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

Сервис поддерживает 23 языка, включая русский, английский, немецкий и французский. Каждый голос способен воспроизводить любой из доступных языков без дополнительных настроек. Список включает арабский, китайский, датский, греческий, иврит, хинди, японский, корейский, малайский, норвежский, польский, португальский, шведский, турецкий и суахили. Языки, не указанные в этом списке, такие как вьетнамский или украинский, не поддерживаются.

Параметр language

Вы можете явно указать язык в запросе с помощью ISO кода. Это гарантирует корректное произношение, особенно если текст написан латиницей, но не на английском. Например, используйте "ru" для русского или "de" для немецкого. Если параметр не указан, система попытается определить язык автоматически.

  • ar — Arabic
  • zh — Chinese
  • da — Danish
  • de — German
  • en — English
  • es — Spanish
  • fi — Finnish
  • fr — French
  • el — Greek
  • he — Hebrew
  • hi — Hindi
  • it — Italian
  • ja — Japanese
  • ko — Korean
  • ms — Malay
  • nb — Norwegian
  • pl — Polish
  • pt — Portuguese
  • ru — Russian
  • sv — Swedish
  • tr — Turkish
  • sw — Swahili

Автоопределение

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

Примеры кодов

Передавайте код языка в поле language вашего JSON-запроса. Это гарантирует, что синтезатор использует правильные фонетические правила для выбранного языка. Например, для немецкого текста используйте "de", а для испанского — "es".

Форматы аудио

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

API поддерживает пять форматов выходного аудио: mp3, wav, opus, flac и pcm. Выбор формата зависит от ваших требований к качеству, размеру файла и совместимости с плеером. Все форматы возвращают один и тот же синтезированный аудиопоток в указанной кодировке.

MP3 и WAV

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

  • MP3: сжатие, малый размер, совместимость
  • WAV: несжатый, высокое качество, больший размер

Opus и FLAC

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

  • Opus: эффективное сжатие, низкий битрейт
  • FLAC: без потерь, для архивации

PCM сырой звук

Формат PCM возвращает необработанные сырые аудиоданные без заголовков контейнера. Он подходит для интеграции с системами, требующими прямого доступа к бинарному потоку, или для последующей упаковки в собственный контейнер разработчиком.

  • PCM: сырые данные, без заголовков

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

Каждый образец ниже сгенерирован этим API из одного и того же предложения.

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

23 языка

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

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

  1. Wikipedia
  2. LibriTTS-R corpus (OpenSLR 141)
  3. openai-node on GitHub
  4. Creative Commons Attribution 4.0
  5. W3C WAI: making audio and video accessible
  6. openai-python on GitHub
  7. Node.js documentation
  8. ISO 639 language codes
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. Python documentation
  11. IETF RFC 7845: Ogg Opus
  12. curl documentation

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