Документация API: автоматизация озвучки текста

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

Эта документация описывает протокол взаимодействия с REST API сервиса VoiceCore, предназначенного для автоматизации создания аудиоматериалов в LMS и платформах онлайн-обучения. Вы узнаете, как интегрировать синтез речи в бэкенд-систему для генерации аудио из учебных текстов без привлечения живых дикторов, используя стандартные HTTP-запросы и официальные SDK OpenAI.

Руководство охватывает полный цикл работы: от получения API-ключа и настройки параметров синтеза до обработки ответов сервера и лимитов. Описаны технические детали передачи данных, поддержка форматов MP3, WAV, FLAC и OPUS, а также методы обработки длинных текстов и ошибок. Материалы ориентированы на технических специалистов команд, внедряющих TTS-решения в корпоративные образовательные продукты.

Документация API: автоматизация озвучки текста

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

Как получить API-ключ?

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

Какой формат запроса используется?

Используется POST-запрос на https://api.rb3774d.com/v1/audio/speech с телом в формате JSON. Требуется передать текст в поле input, выбрать модель и голос. Заголовок Authorization должен содержать Bearer токен.

Можно ли использовать SDK от других провайдеров?

Да, структура запроса идентична OpenAI. Официальные SDK OpenAI работают, если изменить base_url на https://api.rb3774d.com/v1 и указать ваш API-ключ. Это позволяет интегрировать сервис в существующие системы без написания нового кода.

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

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

Как указать язык текста?

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

Можно ли изменить скорость речи?

Да, параметр speed позволяет регулировать скорость от 0.25 до 4.0. Это полезно для адаптации аудиоматериалов под разные темпы восприятия. Значение по умолчанию (1.0) обеспечивает стандартную скорость речи.

Какие форматы аудио поддерживаются?

Поддерживаются форматы mp3, wav, opus, flac и pcm. Вы можете выбрать подходящий формат в поле response_format. MP3, WAV, OPUS, FLAC и PCM поддерживаются API.

Что делать при ошибке запроса?

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

Какой лимит запросов в минуту?

Лимит составляет 60 запросов в минуту на один ключ. До первого пополнения лимит ниже — 10 запросов в минуту. При высокой нагрузке запросы могут ставиться в очередь, что увеличивает время генерации.

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

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

Нужно ли устанавливать библиотеки?

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

Как проверить баланс аккаунта?

Баланс отображается на странице личного кабинета после входа. Там же видны остатки пробного периода и использованные символы. Данные обновляются автоматически после каждого запроса. Точная статистика доступна в разделе использования.

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

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

Как выглядит ответ API?

API возвращает аудиофайл в запрошенном формате. Ответ содержит бинарные данные аудио. Метаданные запроса (время, статус) сохраняются для биллинга, но не передаются в ответе. Ошибки возвращают стандартный код HTTP и описание проблемы.

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

curl

curl https://api.rb3774d.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.rb3774d.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.rb3774d.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

Для начала работы с VoiceCore API необходимо создать учётную запись на странице /get-api-key/. Регистрация доступна через Google или через связку email и пароль. Каждая учётная запись привязана к конкретному домену сети.

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

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

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

  • Регистрация через Google или email + пароль
  • Пробный кредит $0.50 только для Google-аккаунтов
  • Баланс не истекает

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

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

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

  • Один активный ключ на аккаунт
  • Ключ виден в личном кабинете
  • Баланс обновляется автоматически

Ревизия ключа

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

  • Мгновенная инвалидация старого ключа
  • Выпуск нового ключа в один клик

Первый запрос (cURL)

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

Для начала работы с VoiceCore API отправьте POST-запрос на endpoint https://api.rb3774d.com/v1/audio/speech. Этот метод позволяет преобразовать учебный текст в аудиофайл в одном запросе, что является основой для интеграции в LMS-системы.

Ниже приведен минимальный рабочий пример на cURL, использующий модель tts-1 и голос nova. Запрос возвращает аудиофайл, который можно сразу использовать в плеере курса.

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

Выполните следующую команду в терминале. Она генерирует MP3-файл с текстом "Привет, это первый урок".

```bash curl -X POST "https://api.rb3774d.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 audio.mp3 ```

Структура JSON

Тело запроса должно содержать поля model, input и voice. Поле input поддерживает текст до 4096 символов. Поле model принимает значения tts-1 или tts-1-hd.

Дополнительные параметры, такие как speed (от 0.25 до 4.0) и response_format, являются опциональными. Если формат не указан, сервер возвращает аудио в формате по умолчанию (обычно MP3).

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

Ответ сервера

При успешном выполнении сервер возвращает аудиофайл в указанном формате. Время генерации зависит от длины текста: короткие фразы обрабатываются за несколько секунд.

Если синтез завершился ошибкой, возвращается стандартный код HTTP ошибки и сообщение. В случае сбоя средства за запрос не списываются.

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

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

Использование SDK OpenAI упрощает интеграцию в ваши LMS-системы. Вам не нужно писать собственный клиент для HTTP-запросов: достаточно изменить базовый URL, чтобы библиотека направляла запросы на наш сервер.

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

Изменение base_url

Укажите базовый URL вашего API-эндпоинта в конфигурации клиента. Это перенаправит все запросы на https://api.rb3774d.com/v1, сохраняя структуру сообщений совместимой с OpenAI.

Пример для Python: base_url="https://api.rb3774d.com/v1".

  • Базовый URL: https://api.rb3774d.com/v1
  • Совместимость: структура запроса идентична OpenAI
  • Языки: Python, JavaScript, Go, Java и другие, поддерживающие HTTP-клиенты.

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

Передайте ваш уникальный токен авторизации через заголовок Authorization. Ключ формируется как Bearer tts-... и предоставляется в личном кабинете после регистрации.

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

  • Формат: Bearer tts-<ваш_ключ>
  • Один активный ключ на аккаунт
  • Действует для всех эндпоинтов

Обработка ответа

Сервер возвращает аудиофайл в указанном формате (mp3, wav, opus, flac, pcm) или JSON с ошибкой. SDK автоматически десериализует ответ в байты или файл.

В случае ошибки вы получите стандартный код статуса и сообщение. Убедитесь, что обрабатывает исключения для корректного ведения лога в вашей LMS.

  • Форматы ответа: аудиофайл или JSON
  • Коды ошибок: 4xx, 5xx
  • Автодесериализация через SDK

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

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

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

Параметры задаются в теле JSON-запроса. Неправильные значения приводят к ошибке, поэтому важно использовать строго указанные в документации варианты для стабильного результата в LMS-системах.

Указание модели

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

Для большинства задач онлайн-курсов достаточно стандартной модели tts-1. Модель tts-1-hd доступна для выбора.

  • tts-1: стандартная модель синтеза
  • tts-1-hd: модель повышенной четкости
  • Обе модели стоят одинаково

Выбор голоса

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

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

  • 8 предустановленных голосов
  • Любой голос может говорить на любом из 23 языков
  • Автоматическое определение языка по тексту

Настройка скорости

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

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

  • Диапазон: от 0.25 до 4.0
  • Стандартная скорость: 1.0
  • Не влияет на тарификацию

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

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

Выбор формата зависит от требований вашей LMS и целевых устройств студентов. API поддерживает MP3, WAV, FLAC и OPUS, позволяя оптимизировать баланс между качеством звука и размером файла.

MP3 для веба

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

WAV для качества

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

FLAC и OPUS

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

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

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

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

При сбое синтеза API возвращает стандартные HTTP-коды ошибок (4xx, 5xx). Это позволяет внедрить логику повторных запросов в автоматизированные конвейеры генерации аудио для ваших LMS.

Коды статуса

Сервер возвращает коды 400–499 при некорректных параметрах запроса или истечении лимитов. Коды 500–599 указывают на временные сбои на стороне сервера. Используйте эти коды для определения стратегии повторных попыток (retry logic) в ваших скриптах.

Возврат средств

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

Логирование

Метаданные запросов (время, количество символов, статус) сохраняются для биллинга. Вы можете использовать эти данные для аудита расходов команды и контроля объемов озвучки курсов.

Лимиты и ограничения

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

Для стабильной работы интеграции с LMS-системами важно учитывать технические ограничения API. Стандартный лимит составляет 60 запросов в минуту на один ключ. Перед первым пополнением баланса этот порог снижается до 10 запросов в минуту, что требует предварительного тестирования при высоком объеме генерации учебных материалов.

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

Лимит действует на каждый активный API-ключ независимо от количества пользователей в команде. Превышение скорости приводит к получению HTTP 429. Рекомендуется внедрять логику повторных попыток с экспоненциальной задержкой в ваших скриптах автоматизации.

Лимит символов

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

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

Запросы обрабатываются последовательно, поэтому в периоды высокой нагрузки может формироваться очередь. Генерация коротких фраз занимает несколько секунд, тогда как длинные тексты генерируются примерно в реальном времени (25 символов в секунду). Учитывайте это время ожидания при построении пользовательского интерфейса.

Примеры кода

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

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

Примеры покрывают основные сценарии: синхронная генерация аудио и пакетная обработка больших учебных материалов. Все примеры используют стандартные библиотеки и открытые SDK.

Python скрипт

Используйте библиотеку openai для отправки запросов. Укажите базовый URL https://api.rb3774d.com/v1 и ваш API-ключ в заголовке авторизации. Скрипт сохраняет бинарный ответ в файл WAV или MP3.

  • Установите пакет: pip install openai
  • Импортируйте клиент и передайте ключ через API_KEY

JavaScript запрос

Используйте стандартный fetch или официальный JS SDK. Передайте параметры модели, голоса и текста в теле запроса. Обработайте ответ как поток данных или бинарный файл.

  • Используйте async/await для асинхронных запросов
  • Проверяйте статус ответа перед сохранением файла

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

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

  • Проверяйте длину текста перед отправкой
  • Используйте стандартные библиотеки для склейки аудио

Послушайте 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. FFmpeg documentation
  4. curl documentation
  5. TRON developer hub: TRC-20
  6. MDN: Web Speech API
  7. ISO 639 language codes
  8. openai-node on GitHub
  9. Node.js documentation
  10. LibriVox public-domain audiobooks
  11. IETF RFC 7845: Ogg Opus
  12. openai-python on GitHub

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