Часто задаваемые вопросы
Какие модели доступны в API?
Доступны две модели: tts-1 и tts-1-hd. Они используют один и тот же движок синтеза и имеют одинаковую стоимость. Вы можете выбрать любую из них в зависимости от требуемого качества аудио, передавая соответствующее значение в поле model при отправке запроса на endpoint /v1/audio/speech.
Как указать язык для текста на латинице?
Если поле language не задано, система угадывает язык по скрипту, и текст на латинице по умолчанию считается английским. Для других языков, использующих латиницу (например, немецкого или испанского), необходимо явно указать код языка в параметре запроса, чтобы синтез прошел корректно.
Можно ли использовать один ключ для нескольких проектов?
Да, у аккаунта есть один активный ключ API. Вы можете использовать его в любом количестве проектов или сервисов одновременно. Лимиты скорости применяются к ключу в целом, а не к отдельному приложению. Если нужно, старый ключ можно отозвать и выпустить новый.
Какой максимальный размер текста в одном запросе?
Максимальный размер текста составляет 4096 символов на один запрос. Если ваш текст длиннее, его нужно разбить на части по 4096 символов, сгенерировать аудио для каждой части отдельно, а затем соединить полученные файлы в один. Пробелы и знаки препинания учитываются как символы.
Поддерживается ли WebSocket для потоковой передачи?
Нет, потоковая передача через WebSocket не поддерживается. API возвращает готовый аудиофайл в ответе после завершения синтеза. Для получения результата нужно дождаться завершения обработки запроса и скачать файл.
Есть ли лимит на количество генераций в минуту?
Лимит составляет 60 запросов в минуту на один ключ API. Для новых аккаунтов без пополнения лимит ниже — 10 запросов в минуту. Запросы обрабатываются последовательно, поэтому при высокой нагрузке может возникать очередь, и ответ будет возвращен с задержкой.
Как быстро возвращается ответ сервера?
Скорость синтеза примерно равна реальному времени воспроизведения: около 25 символов текста в секунду аудио. Короткие фразы генерируются за несколько секунд. При высокой нагрузке запросы могут стоять в очереди, поэтому время ответа может увеличиваться в зависимости от загруженности сервера.
Можно ли изменить скорость речи в реальном времени?
Изменение скорости происходит во время генерации, а не в реальном времени во время воспроизведения. Вы можете задать параметр speed в диапазоне от 0.25 до 4.0 в запросе. Сгенерированный аудиофайл уже будет иметь установленную скорость, которую нельзя изменить без повторного синтеза.
Какие форматы поддерживаются для скачивания?
Поддерживаются форматы mp3, wav, opus, flac и pcm. Укажите нужный формат в поле response_format вашего запроса. Аудиофайл будет возвращен в теле ответа в выбранном формате. Все сгенерированные файлы содержат невидимый водяной знак, обозначающий синтетическое происхождение голоса.
Как отозвать старый ключ API?
Вы можете выпустить новый ключ API в любое время через личный кабинет. При этом старый ключ становится неактивным мгновенно. У аккаунта может быть только один активный ключ одновременно. Это позволяет быстро сменить доступ, если ключ был скомпрометирован или больше не нужен.
Возвращаются ли деньги за сбой синтеза?
Да, если синтез завершился сбоем, средства возвращаются в полном объеме. Вы не платите за неудачные запросы. Это гарантирует, что вы оплачиваете только успешно сгенерированные аудиофайлы. Баланс обновляется автоматически после обработки статуса запроса.
Нужно ли устанавливать дополнительные библиотеки?
Нет, специальные библиотеки не требуются. Вы можете использовать стандартные HTTP-клиенты или официальные SDK от OpenAI, просто изменив базовый URL на https://api.3r3r.info/v1. Поддерживается формат запросов, аналогичный OpenAI, поэтому интеграция происходит через обычные POST-запросы с JSON-телом.
Поддерживается ли кэширование результатов?
Каждый запрос генерирует аудио заново. Если вам нужно воспроизвести тот же текст, вы можете сохранить полученный файл самостоятельно. Метаданные запросов хранятся для биллинга, но само аудио не кэшируется для повторного использования.
Как определить код ошибки при сбое?
При сбое синтеза API возвращает стандартный HTTP-код ошибки и описание в теле ответа. Проверьте тело ответа для деталей.
Первый запрос
curl
curl https://api.3r3r.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.3r3r.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.3r3r.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
API ключ — это ваш доступ к сервису синтеза речи. Он привязан к вашему аккаунту и используется для авторизации всех запросов. Ключ выглядит как строка, начинающаяся с tts-.
Для начала работы вам потребуется активный ключ. Его можно получить сразу после регистрации, указав email и пароль, или через Google аккаунт. На странице личного кабинета ключ отображается в открытом виде вместе с балансом.
Регистрация аккаунта
Аккаунт создается на странице /get-api-key/. Вы можете зарегистрироваться, используя Google аккаунт или обычную почту с паролем. При регистрации через Google вы сразу получаете пробный баланс $0.50 на 7 дней. Аккаунты, созданные по email, пробного баланса не имеют.
Получение токена
Токен (ключ) генерируется автоматически при создании аккаунта. Он отображается на странице управления ключами. Для авторизации запросов передавайте его в заголовке Authorization: Bearer tts-.... Ключ действует до тех пор, пока вы его не смените.
- Ключ начинается с префикса
tts-. - После смены ключа старый перестает работать мгновенно.
Управление ключами
В личном кабинете доступен один активный ключ. Если вам нужно сгенерировать новый, просто нажмите соответствующую кнопку. Старый ключ будет отозван немедленно, а новый начнет работать сразу. Это полезно, если ключ был передан стороннему сервису или вы хотите сменить доступ.
Первый запрос
В этом разделе мы разберём, как отправить первый запрос к API и получить готовый аудиофайл. Мы покажем, как правильно сформировать запрос и что ожидать от сервера.
Примеры ниже используют стандартный формат JSON, который легко адаптировать под любой язык программирования или инструмент вроде curl.
Пример curl команды
Самый быстрый способ протестировать API — использовать curl. Замените YOUR_API_KEY на ваш реальный ключ и запустите команду в терминале. Это отправит текст на синтез и сохранит результат в файл output.mp3.
Команда работает с любой модели tts-1 или tts-1-hd, так как они используют один и тот же движок и цену.
- Замените
YOUR_API_KEYна ваш ключ из личного кабинета. - Убедитесь, что у вас установлен curl версии 7.34.0 или выше.
Формат JSON тела
Тело запроса должно быть в формате JSON. Основные поля: model (выбор между стандартным и HD качеством), input (текст до 4096 символов), voice (один из 8 голосов) и response_format (mp3, wav, opus, flac или pcm).
Поле language необязательно: система попытается определить язык автоматически по скрипту текста, но для неанглийских текстов на латинице рекомендуется указать его явно.
Ответ сервера
При успешном выполнении сервер вернёт аудиофайл в указанном формате в теле ответа HTTP. Если синтез не удался, вы получите код ошибки и описание проблемы.
Не забудьте проверить заголовок Content-Type, чтобы правильно обработать бинарные данные аудио в вашем приложении.
Использование OpenAI SDK
Для удобства интеграции вы можете использовать официальные SDK OpenAI, просто изменив базовый URL. Это позволяет сохранить привычный интерфейс библиотеки и минимизировать количество кастомного кода при подключении к нашему API.
Базовый URL для запросов: https://api.3r3r.info/v1. Токен авторизации передаётся в заголовке Authorization, как и в стандартной схеме работы с OpenAI API.
Настройка base_url
Укажите базовый URL https://api.3r3r.info/v1 в конфигурации вашей библиотеки. Это единственный параметр, который нужно изменить по сравнению со стандартной настройкой OpenAI.
Пример для Python-библиотеки openai:
Инициализация клиента
Создайте экземпляр клиента, передав ваш API-ключ в параметре api_key и настроив base_url.
Код инициализации на Python:
- from openai import OpenAI
- client = OpenAI(api_key="tts-...", base_url="https://api.3r3r.info/v1")
Вызов метода speech
Используйте метод audio.speech.create, передав текст, модель и голос. Ответ будет содержать бинарные данные аудиофайла.
Пример вызова:
Параметры запроса
Для синтеза аудио доступны две модели: tts-1 и tts-1-hd. Они используют один и тот же движок и стоят одинаково. Выберите ту, что лучше подходит под ваш сценарий, не переплачивая за лишние функции.
Модели tts-1 и tts-1-hd
Обе модели поддерживают все форматы ответа и имеют одинаковую цену. Если вам не критично максимальное качество, tts-1 справится с новостными заметками быстро и эффективно.
Выбор голоса
Доступно 8 предустановленных голосов с разными тембрами. Aria и Luna подойдут для художественных текстов, Atlas — для новостей, а Felix — для промо-материалов. Каждый голос поддерживает 23 языка, включая русский и английский.
- Aria: теплый, ясный нарратор
- Atlas: нейтральный, новостной
- Felix: энергичный, промо
Установка скорости
Параметр speed регулирует темп речи от 0.25 до 4.0. Стандартная скорость (1.0) обеспечивает примерно реальное время звучания: около 25 символов текста в секунду. Увеличьте скорость для быстрых дайджестов или замедлите её для сложных терминов.
Форматы аудио
API возвращает аудиофайл в запрошенном формате. Выбор формата зависит от ваших задач: от универсальности MP3 до качества FLAC или экономии трафика с OPUS.
MP3 и WAV
Формат MP3 оптимизирован для сжатия и широко поддерживается. WAV обеспечивает несжатое качество, что удобно для последующего монтажа в студиях.
OPUS и FLAC
OPUS обеспечивает высокое качество при малом размере файла, что полезно для мобильных приложений. FLAC предоставляет lossless-сжатие без потери качества.
PCM для прямых потоков
PCM возвращает необработанные аудиоданные. Этот формат удобен для программной обработки или записи в файлы.

Обработка ошибок
Сервер возвращает HTTP-коды 2xx при успешной генерации аудио и 4xx/5xx в случае проблем. При ошибках сервер возвращает код статуса и описание проблемы в формате JSON.
Ключевые коды включают 401 (неверный или отсутствующий токен), 429 (превышен лимит запросов) и 413 (текст превышает 4096 символов). Эти статусы помогают быстро локализовать причину сбоя.
Текстовые сообщения об ошибках
В случае ошибки тело ответа содержит JSON с полями "error" и "message", описывающими проблему. Например, при неверном голосе будет указан код ошибки.
- 400 Bad Request: некорректный формат JSON или отсутствующие обязательные поля.
- 401 Unauthorized: ключ API отсутствует или неверен.
- 429 Too Many Requests: превышен лимит 60 запросов в минуту.
Повторные запросы
Рекомендуется использовать экспоненциальную задержку при повторных попытках (retry logic) для кодов 429 и 503. Это позволяет избежать перегрузки очереди синтеза.
Если синтез не удался,_charge_ не списывается, поэтому повторный запрос безопасен. Однако при стабильных ошибках (4xx) повторять запрос бессмысленно — проверьте параметры.
- Не повторяйте запросы чаще, чем позволяет лимит (60 rpm).
- Проверяйте поле "message" в ответе перед повторной отправкой.
Лимиты и ограничения
API накладывает ограничения, которые влияют на скорость генерации и стоимость. Зная лимиты, вы можете правильно настроить архитектуру приложения и избежать ошибок при высоких нагрузках.
Все ограничения действуют на уровне ключа API. При превышении лимитов сервер вернёт соответствующий статус, а при ошибке синтеза средства будут возвращены.
Лимит запросов в минуту
Доступно 60 запросов в минуту на один ключ. До первого пополнения баланса лимит составляет 10 запросов в минуту.
- Лимит: 60 запросов/мин (10 до топ-апа)
Максимальная длина текста
Максимальный размер входного текста — 4096 символов на один запрос. Для более длинных статей их нужно разбить на части и объединить аудиофайлы.
Очереди обработки
Запросы обрабатываются последовательно. При высокой нагрузке запрос может стоять в очереди. Типичная скорость — около 25 символов текста в секунду для длинных текстов.
Часто задаваемые вопросы
API обрабатывает запросы последовательно, поэтому при высокой нагрузке может возникать очередь. Если аудио не возвращается в течение нескольких секунд, это нормальная ситуация для коротких фраз или пиковых нагрузок.
Для стабильной работы используйте встроенные механизмы повторных попыток с экспоненциальной задержкой. API возвращает статусы, позволяющие понять причину задержки или сбоя.
Как обрабатывать большие тексты?
Максимальная длина текста — 4096 символов. Если ваш материал длиннее, разбейте его на части. После получения аудиофайлов для каждого фрагмента объедините их в один файл на стороне клиента.
Что делать при таймауте?
Запросы обрабатываются по порядку. Если очередь большая, время генерации может превысить стандартные таймауты. Увеличьте таймаут вашего HTTP-клиента. Повторный запрос без изменений будет бесплатным, если синтез не удался.
Как проверить доступность API?
Отправьте GET-запрос к эндпоинту /v1/models. Если сервер отвечает кодом 200, API работает. Также доступен эндпоинт /v1/voices для проверки доступных голосов и форматов.
Послушайте 8 голосов
Каждый образец ниже сгенерирован этим API из одного и того же предложения. Идеальный вариант для классической новостной подачи или аудиокниг.
23 языка
Любой голос может говорить на любом из этих языков.
Источники и дополнительные материалы
- Wikipedia
- IETF RFC 7845: Ogg Opus
- OpenAI API reference: create speech
- FFmpeg documentation
- Tether (USDT)
- ISO 639 language codes
- LibriTTS-R paper (arXiv 2305.18802)
- openai-node on GitHub
- MDN: Web Speech API
- Creative Commons Attribution 4.0
- LibriVox public-domain audiobooks
- W3C WAI: making audio and video accessible
