Документация API для синтеза речи (Text-to-Speech)

1. Обзор интерфейса

Данный API предоставляет функцию преобразования текста в речь (TTS), позволяя конвертировать введенный текст в реалистичную синтезированную речь. Интерфейс полностью совместим со стандартами спецификации OpenAI.

Название эндпоинта: Создание аудио gpt-4o-mini-tts
Официальная документация (справочник): OpenAI Text-to-Speech Guides
Текущий статус: Опубликован (Released)

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

Протокол: HTTP / HTTPS
Метод запроса: POST
URL эндпоинта: https://api.codingplanx.ai/v1/audio/speech
Формат данных: application/json

2.1 Заголовки запроса (Request Headers)

Параметр	Обязательно	Пример значения	Описание
Content-Type	Да	`application/json`	Указывает формат данных тела запроса
Authorization	Да	`Bearer {YOUR_API_KEY}`	Токен авторизации для аутентификации API

2.2 Параметры тела запроса (Request Body)

Параметр	Тип	Обязательно	По умолчанию	Описание
`model`	string	Да	-	Одна из доступных TTS-моделей, например: `gpt-4o-mini-tts`, `tts-1` или `tts-1-hd`.
`input`	string	Да	-	Текст для генерации аудио. Максимальная длина ограничена 4096 символами.
`voice`	string	Да	-	Голос, используемый для генерации аудио. Поддерживаемые голоса: `alloy`, `echo`, `fable`, `onyx`, `nova` и `shimmer`.
`response_format`	string	Нет	`mp3`	Формат выходного аудиофайла. Поддерживаемые форматы: `mp3`, `opus`, `aac` и `flac`.
`speed`	number	Нет	`1.0`	Скорость воспроизведения сгенерированного аудио. Поддерживаются значения от `0.25` до `4.0`.

3. Примеры запросов

Пример запроса cURL

curl --request POST \
  --url https://api.codingplanx.ai/v1/audio/speech \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o-mini-tts",
    "input": "The quick brown fox jumped over the lazy dog.",
    "voice": "alloy",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output output.mp3

Примечание: Поскольку данный API возвращает бинарный поток аудиоданных, рекомендуется использовать параметр --output в команде cURL для сохранения ответа напрямую в аудиофайл.

4. Описание ответа

HTTP статус-код: 200 OK
Content-Type: Возвращает соответствующий медиа-тип в зависимости от response_format (например, audio/mpeg).

4.1 Успешный ответ

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

4.2 Пример ответа с ошибкой

Если запрос не выполнен, будет возвращено сообщение об ошибке в формате JSON:

{
  "error": {
    "message": "Invalid authorization key.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

5. Часто задаваемые вопросы (FAQ)

Q1: Каково ограничение по длине текста для параметра input? Что делать, если лимит превышен? A1: Максимальная длина параметра input составляет 4096 символов. Если вам нужно конвертировать более длинный текст, рекомендуется на стороне клиента разбить его на фрагменты (по абзацам или знакам препинания) длиной менее 4096 символов, отправить отдельные запросы, а затем склеить полученные аудиофайлы воедино.

Q2: В чем разница между форматами response_format и какой из них выбрать? A2:

mp3 (по умолчанию): Лучшая совместимость, идеально подходит для большинства веб-сайтов и мобильных устройств.
opus: Минимальная задержка и высокая степень сжатия, отлично подходит для потокового интернет-вещания в реальном времени.
aac: Высокое качество звука, оптимально работает на устройствах iOS, в экосистеме Apple и на таких платформах, как YouTube.
flac: Формат без потери качества (lossless), предлагает наилучшее звучание, но имеет самый большой размер файла; подходит для архивации аудио или постобработки.

Q3: Как контролировать интонацию, эмоции или паузы в речи? A3: В настоящее время модель не поддерживает прямое управление эмоциями или длительностью пауз через параметры (например, теги SSML). Модель автоматически подбирает подходящие паузы и интонацию на основе контекста и знаков препинания в тексте (таких как запятые, точки, восклицательные и вопросительные знаки). Вы можете улучшить итоговое звучание, оптимизировав пунктуацию в вашем тексте.

Q4: Могу ли я изменить скорость воспроизведения аудио? A4: Да. Вы можете использовать параметр speed, установив любое значение от 0.25 до 4.0. Значение 1.0 — это нормальная скорость, меньше 1.0 — замедление, больше 1.0 — ускорение.

Q5: Почему мой запрос возвращает ошибку 401 Unauthorized? A5: Пожалуйста, проверьте, правильно ли передан заголовок Authorization: Bearer {YOUR_API_KEY} в вашем запросе, а также убедитесь, что срок действия вашего API-ключа не истек и статус вашего аккаунта активен.