Интеграция TTS API: документация и примеры кода

Автор редакция ГласОзвучка · Обновлено 2026-11-19

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

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

Интеграция TTS API: документация и примеры кода

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

Какой URL endpoint для запросов?

Используйте POST https://api.lv7.info/v1/audio/speech. Это стандартный endpoint для синтеза речи. Отправляйте JSON с текстом, голосом и настройками. Ответом будет аудиофайл в запрошенном формате. Для других операций используйте GET /v1/voices или GET /v1/models.

Как изменить base_url в OpenAI SDK?

Установите base_url в https://api.lv7.info/v1. Структура запроса идентична OpenAI, поэтому официальные SDK работают без изменений. Просто замените базовый URL и используйте свой API-ключ. Это позволяет быстро интегрировать синтез в существующие проекты без переписывания логики.

Какие модели доступны для синтеза?

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

Можно ли использовать свой API-ключ?

Да, каждый аккаунт имеет один активный ключ. Вы можете выпустить новый ключ в любой момент через личный кабинет. При этом старый ключ перестает действовать немедленно. Используйте заголовок Authorization: Bearer для аутентификации каждого запроса к API.

Что делать, если лимит запросов исчерпан?

Лимит составляет 60 запросов в минуту на ключ (10 до первого пополнения). Если лимит исчерпан, API вернет ошибку. Просто подождите, пока счетчик обновится, или пополните баланс для повышения лимита. Ошибки не списывают средства с вашего счета.

Поддерживает ли API параллельные запросы?

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

Какой формат заголовка авторизации?

Используйте заголовок Authorization: Bearer <ваш_ключ>. Example: Authorization: Bearer tts-123abc. This authenticates your request. Ensure the key is valid and active. Incorrect or expired keys will result in a 401 error.

Возвращает ли API прямой URL на аудио?

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

Можно ли указать язык явно?

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

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

Это модель высокого качества (HD). Она использует тот же движок, что и tts-1. Цена идентична. Различий в функциональности между ними нет.

Есть ли разница в цене между моделями?

Нет, разница в цене отсутствует. Обе модели стоят $10 за 1 миллион символов. Вы платите за количество символов в тексте. Формат аудио и скорость не влияют на стоимость. Это упрощает расчет бюджета для проектов.

Как обрабатывать тексты длиннее 4096 символов?

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

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

API возвращает статус запроса и код ошибки при сбое. Метаданные (время, символы) хранятся на сервере для биллинга. В ответе с аудио могут быть заголовки с информацией. Используйте эти данные для отладки и учета расходов.

Какие ошибки чаще всего встречаются?

Частые ошибки: превышение лимита запросов (429), неверный ключ (401), неверный формат JSON (400). Также возможны ошибки при превышении длины текста. Проверяйте авторизацию и лимиты. Ошибки синтеза не списывают средства с баланса.

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

curl

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

Для начала работы перейдите на страницу /get-api-key/ и выберите способ регистрации. Доступны два варианта: через Google-аккаунт или стандартный email с паролем. Разница заключается в бонусе: при входе через Google вы сразу получаете пробный баланс $0.50 (около 50 000 символов) сроком на 7 дней. Аккаунты, созданные по email, стартуют без этого бонуса.

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

Регистрация через Google

Регистрация через Google

Нажмите кнопку «Войти через Google» на странице авторизации. Процесс занимает несколько секунд и автоматически создает аккаунт с стартовым балансом $0.50.

  • Мгновенный доступ к API
  • Пополнение пробного баланса $0.50
  • Валидация email через Google

Регистрация по email

Регистрация по email

Введите адрес электронной почты и придумайте пароль. Этот метод подходит, если вам нужен чистый аккаунт без временных бонусов. Баланс останется нулевым до первого пополнения через USDT (TRC-20).

  • Классическая регистрация
  • Без стартового бонуса
  • Полный контроль над паролем

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

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

  • Мгновенная инвалидация старого ключа
  • Один активный ключ на аккаунт
  • Видно в панели /get-api-key/

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

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

Отправка текста через API требует формирования JSON-запроса к конечной точке POST https://api.lv7.info/v1/audio/speech. Ключ авторизации передается в заголовке Authorization: Bearer, а текст ограничивается 4096 символами. Это базовый способ получения аудиофайла без использования сторонних библиотек.

Базовый пример POST запроса

Для тестирования используйте минимальный запрос. Укажите модель tts-1 или tts-1-hd. Параметр input содержит сам текст, а voice — один из восьми голосов (например, nova). Ответом будет аудиофайл в указанном формате.

Указание голоса и языка

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

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

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

Формат аудио указывается в поле response_format. Поддерживаются MP3, WAV, OPUS, FLAC и PCM. MP3 оптимален для веба, FLAC и OPUS экономят трафик. WAV обеспечивает высокую точность без сжатия. Формат не влияет на стоимость генерации.

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

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

Для интеграции достаточно изменить базовый URL в конфигурации SDK на https://api.lv7.info/v1. Это позволяет использовать стандартные библиотеки OpenAI для отправки запросов к нашему API без необходимости писать сложный парсер ответов.

Ключ авторизации передается в заголовке Authorization: Bearer <ваш_ключ>. API совместим с официальными пакетами OpenAI, что упрощает внедрение в существующие проекты.

Изменение base_url

Укажите базовый URL https://api.lv7.info/v1 в настройках вашего SDK. Это перенаправит запросы на нашу инфраструктуру, сохраняя привычную структуру данных.

Передача API-ключа

Используйте заголовок Authorization: Bearer для идентификации аккаунта. Ключ генерируется на странице /get-api-key/ и действует до его замены.

Совместимость с библиотеками

Формат запросов идентичен OpenAI Speech API. Вы можете использовать любые языки и библиотеки, поддерживающие этот стандарт, включая Python и JavaScript.

  • Поддержка Python и Node.js
  • Стандартный JSON формат
  • Быстрое переключение endpoints

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

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

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

Поле input (текст до 4096 символов)

Поле input принимает строку текста. Лимит в 4096 символов действует на один запрос API. При превышении лимита синтез не начнется.

Поле voice (8 доступных вариантов)

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

  • Женские: aria (рассказчик), nova (динамичный), luna (мягкий), sage (инструктивный)
  • Мужские: felix (энергичный), milo (разговорный), atlas (нейтральный), orion (документальный)

Поле speed (диапазон 0.25–4.0)

Параметр speed регулирует скорость озвучки от 0.25 до 4.0. Стандартная скорость равна 1.0. Уменьшение скорости полезно для пользователей с нарушениями слуха или когнитивными особенностями.

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

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

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

MP3 для веб-приложений

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

WAV для высокой точности

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

OPUS и FLAC для экономии трафика

OPUS обеспечивает высокое качество при минимальном размере файла. FLAC предлагает lossless-сжатие для архивации или профессионального использования.

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

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

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

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

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

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

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

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

  • Лимит рассчитывается на один активный ключ.
  • Запросы обрабатываются последовательно, что может создавать очередь.

Лимит 10 запросов до первого пополнения

В период бесплатного тестового доступа (7 дней, кредит $0.50) действует ускоренный лимит: 10 запросов в минуту. Это позволяет проверить работоспособность API, но недостаточно для стабильной работы в продакшене.

После пополнения баланса через USDT (TRC-20 лимит увеличивается до стандартных 60 запросов в минуту. Пополнение происходит автоматически в течение нескольких минут.

  • Тестовый лимит: 10 запросов/мин.
  • Стандартный лимит: 60 запросов/мин.

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

Один запрос API принимает текст длиной не более 4096 символов. Для обработки длинных текстов необходимо разбивать их на части вручную и склеивать полученные аудиофайлы.

Пробелы и знаки препинания учитываются как символы. При превышении лимита API вернет ошибку, и текст не будет озвучен.

  • Максимальная длина: 4096 символов.
  • Пробелы и пунктуация входят в лимит.

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

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

При сбое синтеза API возвращает ошибку HTTP, но списания не происходит. Баланс остается неизменным, что позволяет безопасно обрабатывать временные сбои сети или сервера без рисков для бюджета.

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

Разработчикам достаточно реализовать логику повторной попытки (retry) при получении кодов 4xx или 5xx, так как запрос будет обработан заново без дополнительного списания средств.

Неудачные запросы бесплатны

Если сервер не смог обработать текст или произошла ошибка сети, charge не начисляется. Это критично при пакетной обработке больших объемов текста.

Ошибки синтеза бесплатны, но запросы учитываются в лимитах.

  • Серверные ошибки (5xx) гарантированно бесплатны.
  • Проблемы с сетью клиента также не приводят к списанию.

Коды состояния ответа

API возвращает стандартные HTTP-коды. Успешный ответ — 200 OK с аудиофайлом в теле ответа или ссылкой.

Коды 4xx указывают на проблемы с аутентификацией или параметрами запроса (например, неверный голос или формат).

Коды 5xx означают временную недоступность сервиса синтеза.

  • 200 OK: Успех, аудио возвращено.
  • 400 Bad Request: Неверный JSON или параметр.
  • 401 Unauthorized: Неверный или отсутствующий API-ключ.
  • 500/502/503: Внутренняя ошибка или перегрузка сервера.

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

Списания происходят только после успешного завершения генерации. Если синтез прерван на сервере, средства возвращаются на баланс мгновенно.

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

Гарантия бесплатности сбоев позволяет интегрировать API в приложения для пожилых людей.

Примеры кода

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

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

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

Код на Python с OpenAI SDK

Импортируйте библиотеку openai и укажите базовый URL. Передайте ключ через параметр api_key и вызовите метод audio.speech.create.

  • Укажите модель tts-1 или tts-1-hd.
  • Установите response_format в mp3 или wav.
  • Сохраните бинарный ответ в файл локально.

Код на JavaScript/Node.js

Используйте fetch для POST-запроса на https://api.lv7.info/v1/audio/speech. Заголовки должны содержать Authorization: Bearer и Content-Type: application/json.

  • Отправьте JSON с полем input.
  • Обработайте ответ как Blob или ArrayBuffer.
  • Не забудьте обработать ошибки сети.

Пример на cURL для тестирования

Выполните команду в терминале для быстрой проверки работоспособности ключа. Замените YOUR_API_KEY на ваш реальный токен.

  • Команда возвращает аудиофайл в stdout.
  • Используйте флаг -o output.mp3 для сохранения.
  • Проверьте статус кода ответа 200.

Послушайте 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. OpenAI API reference: create speech
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. ISO 639 language codes
  7. MDN: Web Speech API
  8. Node.js documentation
  9. curl documentation
  10. LibriVox public-domain audiobooks
  11. TRON developer hub: TRC-20
  12. Tether (USDT)

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