Часто задаваемые вопросы
Какой 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.mp3Python (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 | 中文 |
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-ключа
Для начала работы перейдите на страницу /get-api-key/ и выберите способ регистрации. Доступны два варианта: через Google-аккаунт или стандартный email с паролем. Разница заключается в бонусе: при входе через Google вы сразу получаете пробный баланс $0.50 (около 50 000 символов) сроком на 7 дней. Аккаунты, созданные по email, стартуют без этого бонуса.
Каждый аккаунт привязан к конкретному сайту сети и может иметь только один активный ключ. Если ключ скомпрометирован или нужно сменить окружение, его можно перегенерировать в личном кабинете. Старый ключ перестает действовать мгновенно.
Регистрация через Google
Нажмите кнопку «Войти через Google» на странице авторизации. Процесс занимает несколько секунд и автоматически создает аккаунт с стартовым балансом $0.50.
- Мгновенный доступ к API
- Пополнение пробного баланса $0.50
- Валидация email через Google
Регистрация по email
Введите адрес электронной почты и придумайте пароль. Этот метод подходит, если вам нужен чистый аккаунт без временных бонусов. Баланс останется нулевым до первого пополнения через USDT (TRC-20).
- Классическая регистрация
- Без стартового бонуса
- Полный контроль над паролем
Генерация нового ключа
В разделе настроек личного кабинета доступна кнопка «Выдать новый ключ». При нажатии старый ключ инвалидируется немедленно, а новый становится активным. Это полезно при смене серверов или обнаружении утечки.
- Мгновенная инвалидация старого ключа
- Один активный ключ на аккаунт
- Видно в панели /get-api-key/
Первый запрос через 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
Для интеграции достаточно изменить базовый 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 из одного и того же предложения.
23 языка
Любой голос может говорить на любом из этих языков.
