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

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

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

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

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

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

Какой формат ответа возвращает API?

API возвращает аудиофайл в одном из доступных форматов: mp3, wav, opus, flac или pcm. Вы выбираете нужный формат в поле response_format при отправке запроса. Это позволяет сразу получить готовый файл, который можно воспроизвести или сохранить без дополнительных конвертаций.

Как изменить base_url для OpenAI SDK?

Для работы с нашим API измените параметр base_url в конфигурации OpenAI SDK на https://api.78g.info/v1. Используйте тот же ключ доступа, что и для стандартных запросов. Структура тела запроса полностью совместима с официальным эндпоинтом speech, что упрощает интеграцию.

Что делать, если запрос упал?

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

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

Да, но с ограничениями. При issuance нового ключа старый перестает действовать мгновенно. У вас только один активный ключ на аккаунт. Если вы сгенерируете новый, предыдущий сразу станет недействительным, поэтому сохраняйте его в безопасности до момента замены.

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

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

Поддерживаются ли языковые метки?

Мы не поддерживаем SSML или специальные языковые метки внутри текста. Язык определяется автоматически или задается явно параметром language. Если текст на латинице, но не на английском, обязательно укажите код языка, чтобы синтез прошел корректно.

Как узнать баланс через API?

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

Есть ли пример на Python?

Да, вы можете использовать официальный OpenAI SDK для Python. Просто укажите base_url как https://api.78g.info/v1 и передайте ваш ключ доступа. Структура запроса идентична стандартной, поэтому примеры кода из документации OpenAI подойдут без изменений.

Можно ли генерировать аудио в фоне?

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

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

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

Какие коды ошибок бывают?

Стандартные HTTP-коды ошибок используются для указания на проблемы с запросом или аутентификацией. Список кодов ошибок соответствует стандартным HTTP-статусам. Если синтез не удался, средства возвращаются. Проверяйте статус ответа и сообщения об ошибках в теле ответа API.

Влияет ли скорость на цену?

Нет, скорость не влияет на стоимость. Цена фиксирована: $10 за миллион символов независимо от параметра speed. Вы можете менять скорость от 0.25 до 4.0, и это не изменит количество списанных символов или итоговую сумму счета.

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

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

Как часто обновляется документация?

Документация обновляется при изменении функциональности API. Мы не публикуем график обновлений. Следите за страницей /docs/ и /v1/models/, чтобы узнать о доступных моделях и голосах. Изменения в интерфейсе или ценах также отражаются в актуальной версии документации.

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

curl

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

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

Регистрация

Регистрация

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

Панель управления

Панель управления

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

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

Для отправки запросов сгенерируйте API-ключ в личном кабинете. У вас может быть только один активный ключ одновременно. Если нужно, вы можете выпустить новый ключ в любой момент — старый перестанет работать мгновенно. Ключ начинается с префикса tts- и используется в заголовке авторизации.

  • Ключи генерируются в панели управления
  • Один активный ключ на аккаунт
  • Старый ключ отзывается сразу при выпуске нового

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

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

Текст превращается в аудиофайл через один POST-запрос. Вы отправляете исходный текст и параметры синтеза, а в ответ получаете готовый аудиофайл или ссылку на него. Это стандартный REST-интерфейс, который работает без дополнительных библиотек.

Пример curl

Самый быстрый способ протестировать API — использовать curl. Замените YOUR_API_KEY на ваш ключ из панели и отправьте запрос.

  • curl -X POST "https://api.78g.info/v1/audio/speech" \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Привет, это тестовый текст для урока.", "voice": "sage"}'

JSON структура

Тело запроса содержит минимум обязательных полей. Максимальная длина текста — 4096 символов. Пространства и знаки препинания считаются за символы.

  • model: "tts-1" или "tts-1-hd"
  • input: строка с текстом до 4096 символов
  • voice: один из 8 голосов (например, "sage")
  • response_format: "mp3" (по умолчанию)

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

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

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

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

Наш API полностью совместим с официальными SDK OpenAI. Вам не нужно учить новый синтаксис или писать парсеры: достаточно изменить базовый URL, и библиотека начнёт работать с нашим сервером.

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

Изменение base_url

Укажите базовый URL нашего API при инициализации клиента. Для Python это параметр base_url, для других язысов — аналогичный настройщик endpoint.

  • Базовый URL: https://api.78g.info/v1
  • Остальные эндпоинты и форматы данных остаются прежними

Идентичность форматов

Мы поддерживаем те же поля: model, input, voice, response_format, speed и language. Ваши учебные материалы будут обработаны так же, как в стандартных решениях, но с нашей скоростью и ценами.

Пример кода

Вот простой пример на Python с использованием официальной библиотеки openai:

  • import openai
  • client = openai.OpenAI(base_url='https://api.78g.info/v1', api_key='tts-ваш_ключ')
  • response = client.audio.speech.create(
  • model='tts-1',
  • voice='aria',
  • input='Добро пожаловать на урок истории.',
  • response_format='mp3'
  • )

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

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

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

Выбор модели

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

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

Выберите один из 8 голосов, соответствующих стилю материала. Например, «atlas» подходит для нейтральных новостей, а «luna» — для мягкого повествования. Если язык не указан явно, система определяет его автоматически, но для латиницы по умолчанию берётся английский.

  • Женские: aria, nova, luna, sage
  • Мужские: felix, milo, atlas, orion

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

Параметр speed регулирует темп от 0.25 до 4.0. Для учебных материалов часто достаточно стандартной скорости, но ускорение помогает, если нужно быстро озвучить большие объёмы текста. Медленный темп улучшает разборчивость сложных терминов.

Форматы выходного аудио

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

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

MP3 и WAV

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

  • Поддержка для веб-интеграций
  • Высокое качество для монтажа

OPUS и FLAC

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

  • Оптимально для мобильных сетей
  • Архивное качество без потерь

PCM для отладки

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

  • Простая структура данных
  • Удобно для отладки
Форматы выходного аудио

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

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

API возвращает стандартные HTTP-коды состояния, чтобы вы могли точно понять причину сбоя. Например, 401 означает неверный или отсутствующий ключ, а 429 — превышение лимита в 60 запросов в минуту. При ошибках сервер не списывает средства, если синтез не завершился успешно.

Коды ответов

Основные коды: 200 (успех), 400 (неверный формат JSON или голос), 401 (авторизация), 429 (лимиты) и 500 (внутренняя ошибка сервера). В случае 429 запрос может стоять в очереди.

  • 200: Успешный синтез аудио.
  • 400: Неверные параметры запроса.
  • 429: Превышен лимит 60 запросов/мин.

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

Если синтез не удался из-за технической ошибки сервера (коды 5xx) или временного сбоя, списанные средства возвращаются на баланс автоматически. Проверьте статус запроса и баланс в панели управления после повторной попытки.

Логирование

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

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

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

API имеет понятные лимиты, которые помогают планировать нагрузку. Для новых аккаунтов лимит составляет 10 запросов в минуту, а после пополнения баланса он повышается до 60 запросов в минуту на один ключ.

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

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

Ограничение длины

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

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

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

Безопасность

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

Заголовок Authorization содержит ваш уникальный ключ, начинающийся с префикса tts-. Передавайте его в заголовке Authorization: Bearer <ключ> при каждом запросе к API.

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

Заголовок Authorization

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

Убедитесь, что ключ не дублируется в коде без необходимости. Используйте его строго в заголовке HTTP-запроса.

  • Формат: Authorization: Bearer tts-...
  • Передавайте только при запросах к https://api.78g.info/v1

Один активный ключ

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

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

Отзыв ключа

Отзыв ключа происходит автоматически при создании нового. Вам не нужно нажимать кнопку «Отозвать» вручную.

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

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

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

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

23 языка

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

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

  1. Wikipedia
  2. Creative Commons Attribution 4.0
  3. TRON developer hub: TRC-20
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. MDN: Web Speech API
  6. OpenAI API reference: create speech
  7. ISO 639 language codes
  8. openai-python on GitHub
  9. Node.js documentation
  10. LibriVox public-domain audiobooks
  11. LibriTTS-R corpus (OpenSLR 141)
  12. Python documentation

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