Документация API: как начать генерацию голоса за 5 минут

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

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

Вы узнаете, как получить ключ API, отправить первый запрос через curl или OpenAI SDK и настроить формат выходного файла под нужды iOS или Android. Документация охватывает все аспекты интеграции: от указания голоса и скорости до обработки ошибок и лимитов. Никакой воды — только рабочие примеры и технические детали для быстрой разработки.

Документация API: как начать генерацию голоса за 5 минут

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

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

API использует POST-запрос к /v1/audio/speech с JSON-телом. Требуется поле input для текста, модель (tts-1 или tts-1-hd), голос, формат ответа и скорость. Авторизация передается через заголовок Authorization: Bearer. Структура запроса полностью совместима с OpenAI Speech API, что упрощает интеграцию.

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

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

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

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

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

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

Нужно ли устанавливать библиотеки для работы с API?

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

Как обрабатывать ошибки при генерации аудио?

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

Что делать, если превышен лимит запросов в минуту?

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

Поддерживает ли API параметр speed для изменения темпа?

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

Можно ли получить аудиофайл в формате FLAC?

Да, поддерживаются форматы mp3, wav, opus, flac и pcm. Укажите желаемый формат в поле response_format. FLAC подходит для сохранения высокого качества без потерь. Выбор формата зависит от требований вашего приложения.

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

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

Возвращает ли API ссылку на файл или сам файл?

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

Есть ли ограничение на количество одновременно активных ключей?

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

Можно ли использовать API в фоновых задачах приложения?

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

Как быстро ответит сервер на запрос?

Скорость генерации примерно равна реальному времени аудио: 25 символов в секунду. Короткие фразы обрабатываются за несколько секунд. При высокой нагрузке запросы могут стоять в очереди. Это нормальная работа сервиса, обеспечивающего стабильное качество синтеза без дополнительных гарантий времени ответа.

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

curl

curl https://api.1966cup.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.1966cup.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.1966cup.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 или создав профиль по электронной почте и паролю. Учетные записи привязываются к конкретному сайту сети.

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

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

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

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

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

Просмотр ключа на панели

Просмотр ключа на панели

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

Ключ можно скопировать одним нажатием. Он используется в заголовке запроса для идентификации вашего аккаунта при отправке текста на синтез.

  • Ключ начинается с префикса tts-
  • В системе активен только один ключ
  • Панель показывает текущий баланс

Смена и генерация нового ключа

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

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

Первый запрос: пример curl

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

Для начала работы с API синтеза речи отправьте POST-запрос на конечную точку https://api.1966cup.info/v1/audio/speech. Этот эндпоинт принимает JSON-тело и возвращает сгенерированный аудиофайл в указанном формате. Запрос идентичен стандартному формату OpenAI, что позволяет использовать знакомые инструменты разработки без сложных адаптеров.

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

Базовая структура POST запроса

Отправляйте данные методом POST на URL https://api.1966cup.info/v1/audio/speech. Заголовок Authorization должен содержать ваш Bearer-токен в формате "Bearer tts-...". Тело запроса кодируется в JSON и содержит обязательные поля: model, input и voice.

Ответ сервера будет содержать бинарные данные аудиофайла или JSON с ошибкой в случае сбоев. Используйте заголовок Content-Type: application/json для отправки запроса.

Необходимые поля тела запроса

model: выберите "tts-1" или "tts-1-hd" (одинаковая цена и движок). input: строка текста до 4096 символов. voice: один из 8 доступных голосов (например, aria, nova, felix).

Опционально: response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0), language (ISO код, например 'en' или 'ru'). Если язык не указан, он определяется автоматически по скрипту.

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

Пример успешного ответа

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

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

  • Код 200: аудиофайл возвращен
  • Код 400: ошибка валидации данных
  • Код 429: превышен лимит запросов
  • Код 500: внутренняя ошибка сервера

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

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

API использует ту же структуру запросов, что и OpenAI, поэтому для интеграции достаточно изменить базовый URL. Это позволяет использовать официальные библиотеки без написания кастомного парсера JSON.

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

Изменение базового URL

Укажите https://api.1966cup.info/v1 как базовый адрес для вашего SDK. Это единственное изменение, необходимое для перенаправления запросов на наш эндпоинт синтеза речи.

Передача ключа авторизации

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

  • Формат: Bearer tts-...

Совместимость с официальными библиотеками

Поддерживаются стандартные OpenAI SDK для Python, Node.js и других языков. Структура тела запроса идентична оригинальной, поэтому код миграции минимален.

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

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

API принимает JSON-тело запроса с полями model, voice, input, response_format и speed. Минимальный набор параметров позволяет получить аудиофайл за секунды, а опциональные поля дают контроль над качеством и скоростью синтеза.

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

Параметр model принимает значения tts-1 или tts-1-hd. Оба используют один движок и стоят одинаково, различаясь только алгоритмами сжатия. Параметр voice выбирает один из 8 preset-голосов (например, nova, sage, atlas), доступных для всех языков без дополнительных настроек.

  • Доступные модели: tts-1, tts-1-hd
  • 8 голосов с разными тембрами
  • Одинаковая цена для обеих моделей

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

Поле response_format определяет выходной файл: mp3, wav, opus, flac или pcm. Параметр speed регулирует темп речи в диапазоне от 0.25 до 4.0. Увеличение скорости полезно для коротких уведомлений в приложениях, где важна лаконичность.

  • Форматы: mp3, wav, opus, flac, pcm
  • Скорость: от 0.25x до 4.0x
  • Оптимизация под размер файла

Опциональный параметр языка

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

  • Поддержка 23 языков
  • Автоопределение скрипта
  • Рекомендуется явное указание языка

Форматы выходных данных

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

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

MP3 для мобильных устройств

MP3 является оптимальным выбором для большинства мобильных сценариев благодаря сбалансированному соотношению размера файла и качества. Этот формат обеспечивает достаточную清晰度 для речи, сохраняя минимальный объем трафика, что критично для пользователей мобильных сетей.

  • Наименьший размер файла среди поддерживаемых форматов
  • Универсальная совместимость с iOS и Android
  • Идеально для кэширования и воспроизведения в фоновом режиме

WAV и FLAC для высокого качества

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

  • WAV: полный несжатый аудиофайл
  • FLAC: сжатие без потерь, меньший размер
  • Подходит для профессиональных аудиопроцессов

Opus и PCM для стриминга

Opus и PCM используются в специфических сценариях. PCM предоставляет необработанные аудиоданные, а Opus — эффективный сжатый формат. API не поддерживает потоковую передачу (streaming) или WebSocket.

  • PCM: необработанные аудиоданные
  • Opus: эффективное сжатие для потоков
  • Используются для специфических интеграций
Форматы выходных данных

Обработка ошибок и лимитов

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

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

Коды состояния HTTP

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

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

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

Ограничение длины текста

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

Генерация длинных текстов

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

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

Разбиение текста на части

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

Соединение аудиофайлов

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

Управление лимитом 4096 символов

Лимит в 4096 символов включает пробелы и знаки препинания. Точный подсчет длины строки перед отправкой предотвратит ошибки запроса.

Технические особенности

Иллюзация звуковой волны для: Технические особенности

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

Генерация коротких фраз занимает несколько секунд, а длинные тексты создаются в режиме, близком к реальному времени — около 25 символов текста в секунду.

Очередь обработки запросов

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

Время генерации аудио

Генерация коротких фраз занимает несколько секунд, а длинные тексты создаются в режиме, близком к реальному времени — около 25 символов текста в секунду.

Невидимый водяной знак

Каждый сгенерированный аудиофайл содержит невидимый цифровой водяной знак. Он маркирует контент как синтезированный речь и не влияет на качество звучания или размер файла.

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

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

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

23 языка

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

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

  1. Wikipedia
  2. MDN: Web Speech API
  3. FFmpeg documentation
  4. IETF RFC 7845: Ogg Opus
  5. curl documentation
  6. Node.js documentation
  7. LibriTTS-R corpus (OpenSLR 141)
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. Creative Commons Attribution 4.0
  10. Tether (USDT)
  11. Python documentation
  12. LibriVox public-domain audiobooks

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