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

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

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

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

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

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

Какой формат запроса поддерживает API?

API принимает POST-запросы в формате JSON к эндпоинту /v1/audio/speech. Структура тела запроса полностью совместима с OpenAI Speech API. Вы отправляете текст, выбираете модель и голос, а в ответ получаете аудиофайл в выбранном формате (mp3, wav, opus, flac или pcm).

Можно ли использовать SDK OpenAI?

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

Какие параметры обязательны при запросе?

Обязательные параметры: model (tts-1 или tts-1-hd), input (текст до 4096 символов) и voice (один из 8 доступных голосов). Параметр response_format также требуется для указания формата выходного файла. Язык можно указать явно, но если он не задан, он определяется автоматически.

Сколько символов можно отправить в одном запросе?

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

Поддерживается ли потоковая передача аудио?

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

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

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

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

Ошибка 429 означает превышение лимита запросов (60 в минуту). Вам нужно подождать, пока лимит восстановится. Для длинных текстов рекомендуется разбивать их на части и отправлять последовательно, соблюдая интервалы, чтобы избежать очередей и ограничений скорости.

Как сменить API-ключ?

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

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

curl

curl https://api.118o8.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.118o8.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.118o8.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 синтеза речи за несколько минут. Зарегистрируйтесь на странице /get-api-key/, получив бесплатный ключ через Google или создав аккаунт по электронной почте. Это даст вам доступ к начальному балансу (только при входе через Google) и инструментам для генерации аудио.

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

Получение ключа

Получение ключа

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

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

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

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

Отправьте POST-запрос на endpoint /v1/audio/speech, указав текст, голос и желаемый формат аудио. В ответ вы получите готовый аудиофайл, который можно сразу использовать в ваших материалах.

  • Отправьте текст до 4096 символов
  • Выберите один из 8 голосов
  • Получите MP3, WAV или другой формат

Базовая настройка

Используйте официальный OpenAI SDK, изменив base_url на https://api.118o8.info/v1. Передавайте ключ через заголовок Authorization: Bearer, чтобы гарантировать безопасный доступ к сервису.

  • Используйте base_url api.118o8.info/v1
  • Передавайте ключ в заголовке Authorization
  • Поддерживаются стандартные библиотеки HTTP

Эндпоинты API

Иллюзация звуковой волны для: Эндпоинты API

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

Все запросы отправляются на базовый URL https://api.118o8.info/v1. Структура данных совместима с официальными SDK, что упрощает интеграцию в ваши проекты без написания сложного клиентского кода с нуля.

POST /v1/audio/speech

Эндпоинт принимает JSON-тело с текстом до 4096 символов, выбранным голосом и форматом вывода. Возвращает аудиофайл или код ошибки при сбое.

  • Модели: tts-1 или tts-1-hd
  • Поддерживаемые форматы: mp3, wav, opus, flac, pcm
  • Параметр speed от 0.25 до 4.0

GET /v1/voices

Возвращает список из 8 доступных голосов с описанием их тембра и языка. Используйте этот эндпоинт для динамического выбора голоса в интерфейсе вашего приложения.

  • Включает имена: aria, nova, luna, sage, felix, milo, atlas, orion

GET /v1/models

Возвращает метаданные доступных моделей синтеза. Полезно для отладки и проверки доступности конкретных движков генерации аудио.

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

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

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

Модель TTS

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

Выбор голоса

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

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

Формат аудио

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

Примеры кода

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

Для быстрого тестирования используйте cURL, отправляя текст и параметры в формате JSON на эндпоинт синтеза. Этот метод универсален и не требует дополнительных библиотек.

SDK OpenAI упрощает интеграцию: достаточно изменить base_url на адрес нашего API и передать ваш API-ключ. Код становится чище, а обработка ответов — стандартной.

Запрос через cURL

Отправьте POST-запрос на https://api.118o8.info/v1/audio/speech. В теле укажите модель, голос, формат и текст до 4096 символов. Заголовок Authorization должен содержать ваш ключ Bearer.

  • POST https://api.118o8.info/v1/audio/speech
  • Заголовок: Authorization: Bearer tts-...

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

Установите пакет openai. Инициализируйте клиент с base_url="https://api.118o8.info/v1" и тем же API-ключом. Вызовите audio.speech.create() с параметрами model, voice и input.

  • base_url: https://api.118o8.info/v1
  • Использование стандартных параметров SDK

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

При превышении лимита (429) или неверном ключе (401) API возвращает код ошибки и описание. Ошибки синтеза (400) могут возникнуть при некорректных параметрах. Проверяйте статус ответа перед сохранением аудиофайла.

Ограничения

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

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

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

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

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

Превышение лимита вернет ошибку 429 Too Many Requests. Убедитесь, что ваш код корректно обрабатывает такие случаи.

Максимальная длина текста

Один запрос поддерживает текст длиной до 4096 символов. Для более длинных сценариев медитации или тренировок разбейте текст на части.

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

Скорость генерации

Средняя скорость синтеза составляет около 25 символов текста в секунду аудио для длинных текстов. Короткие фразы могут генерироваться дольше — несколько секунд.

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

Ограничения

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

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

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

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

Выбор формата зависит от того, где будет воспроизводиться аудио: в веб-интерфейсе, мобильном приложении или через прямой URL.

MP3

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

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

  • Сжатие с потерями для минимального размера файла
  • Поддержка 99% браузеров и медиаплееров
  • Идеален для воспроизведения в плеерах

WAV

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

Требует больше места на диске, но гарантирует точность при наложении звуковых эффектов.

  • Полное отсутствие сжатия
  • Высокое качество звука
  • Удобно для последующего редактирования

OPUS, FLAC, PCM

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

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

  • OPUS: отличное соотношение качества и размера
  • FLAC: сжатие без потерь для архивов
  • PCM: сырые аудиоданные для точного анализа

Аутентификация

Иллюзация звуковой волны для: Аутентификация

Для доступа к API используется ключ, который отображается в личном кабинете на странице получения ключа. Аутентификация осуществляется через заголовок HTTP-запроса, содержащий токен в формате Bearer.

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

Заголовок Authorization

Укажите заголовок Authorization: Bearer <ВАШ_КЛЮЧ> в каждом запросе к API. Ключ начинается с префикса tts- и находится в разделе «Ключ API» вашего кабинета на сайте 118o8.info.

  • Формат: Authorization: Bearer tts-xxxxxxxxxxxxxxxxxxxx
  • Ключ один на аккаунт

Валидация ключа

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

Ключ не привязан к конкретному IP-адресу, поэтому вы можете использовать его с разных устройств или серверов, где размещается ваш фитнес-контент.

Смена ключа

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

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

  • Нажмите «Выпустить новый ключ» в кабинете
  • Старый ключ инвалидируется мгновенно

Примеры ошибок

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

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

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

400 Bad Request

Запрос отклонен из-за неверных данных. Это может произойти, если текст превышает 4096 символов, указан несуществующий голос или формат аудио не поддерживается.

Проверьте структуру JSON и значения полей input, voice и response_format перед повторной отправкой.

  • Текст длиннее 4096 символов
  • Неверный код голоса
  • Неподдерживаемый формат аудио

401 Unauthorized

Ключ авторизации отсутствует, истек или неверен. Убедитесь, что заголовок Authorization содержит корректный токен вида Bearer tts-... .

Если ключ был сменен на сайте, старые токены перестают действовать немедленно.

429 Too Many Requests

Превышен лимит запросов (60 в минуту). Ожидание или увеличение таймаута помогут справиться с нагрузкой.

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

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

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

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

23 языка

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

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

  1. Wikipedia
  2. curl documentation
  3. ISO 639 language codes
  4. openai-python on GitHub
  5. Node.js documentation
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. openai-node on GitHub
  8. Tether (USDT)
  9. LibriVox public-domain audiobooks
  10. Python documentation
  11. OpenAI API reference: create speech
  12. LibriTTS-R corpus (OpenSLR 141)

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