Документация API GPT-4o-audio

1. Обзор API

Данный API используется для вызова модели GPT-4o с возможностью генерации аудио. Он поддерживает одновременное взаимодействие и генерацию текста и аудио в рамках одного запроса.

Статус: Опубликовано (Released)
Официальная документация: OpenAI API Reference

2. Описание запроса

Протокол: HTTP / HTTPS
Метод запроса: POST
URL-адрес (Endpoint):

POST https://api.codingplanx.ai/v1/chat/completions

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

Параметр	Тип	Обязательно	Пример значения	Описание
Content-Type	`string`	Да	`application/json`	Определяет формат данных тела запроса.
Authorization	`string`	Да	`Bearer $OPENAI_API_KEY`	Учетные данные для аутентификации. Пожалуйста, замените на ваш актуальный API Key.

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

Тело запроса должно быть передано в формате application/json.

Параметр	Тип	Обязательно	Описание
model	`string`	Да	ID используемой модели. Например: `gpt-4o-audio-preview`.
modalities	`array[string]`	Нет	Тип генерируемого вывода модели. По умолчанию: `["text"]`.<br>Если необходимо, чтобы модель сгенерировала как текстовый, так и аудио ответ, используйте: `["text", "audio"]`.
audio	`object`	Нет	Параметры вывода аудио. Настройка обязательна, если `modalities` включает `"audio"`.
? audio.voice	`string`	Да (условно)	Голос, используемый моделью для ответа. Доступные значения: `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`.
? audio.format	`string`	Да (условно)	Определяет формат выходного аудио. Должен быть: `wav`, `mp3`, `flac`, `opus` или `pcm16`.
messages	`array[object]`	Да	Список сообщений, составляющих текущий диалог.
? messages[].role	`string`	Да	Роль автора сообщения (например, `system`, `user`, `assistant`).
? messages[].content	`string`	Да	Конкретное содержимое сообщения.

5. Пример запроса (cURL)

curl -X POST "https://api.codingplanx.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
      "model": "gpt-4o-audio-preview",
      "modalities": ["text", "audio"],
      "audio": { "voice": "alloy", "format": "wav" },
      "messages": [
        {
          "role": "user",
          "content": "Is a golden retriever a good family dog?"
        }
      ]
    }'

6. Описание ответа (Response)

HTTP Статус-код: 200 OK (Успешно)
Content-Type: application/json

(Примечание: Структура ответа соответствует стандартной спецификации OpenAI Chat Completions. Если запрос содержит конфигурацию audio, возвращаемый JSON в choices[0].message будет содержать объект audio, включающий аудиоданные в кодировке Base64 и связанные ID.)

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

Q1: Почему мой запрос возвращает только текст без аудио? A1: Убедитесь, что параметр modalities в теле запроса явно включает "audio" (т.е. ["text", "audio"]). Если этот параметр не задан, система по умолчанию выведет только "text". Также проверьте правильность настройки полей voice и format в объекте audio.

Q2: Как выбрать формат аудио (format)? A2:

mp3: Наиболее универсальный формат, отлично подходит для веб-сайтов и стандартных приложений, имеет небольшой размер файла.
wav: Формат без потерь и сжатия, лучшее качество звука, но самый большой размер файла. Подходит для профессиональной обработки звука, требующей высочайшего качества.
flac: Формат сжатия без потерь, размер файла меньше, чем у wav, при сохранении того же качества звука.
opus: Разработан специально для потоковой передачи в сети (стриминг). Обеспечивает сверхнизкую задержку и высокую степень сжатия, идеален для голосовых звонков в реальном времени или при низкой пропускной способности сети.
pcm16: Исходный формат несжатого аудиопотока. Подходит для передачи данных на низком уровне или вторичной аппаратной разработки.

Q3: Как правильно заполнить заголовок Authorization? A3: Необходимо использовать механизм аутентификации Bearer. Ваш API Key должен быть указан после слова Bearer (обратите внимание на пробел после слова), например в таком виде: Authorization: Bearer sk-xxxxxxxxx.

Q4: Какие голоса (Voice) поддерживает этот API? A4: В настоящее время поддерживается 10 встроенных голосов: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage и shimmer. Рекомендуется протестировать эти голоса в ваших рабочих сценариях, чтобы выбрать тембр, наиболее подходящий для стиля вашего приложения.

Q5: Что делать, если запрос возвращает ошибку 401 Unauthorized? A5: Обычно это связано с тем, что API Key недействителен, истек срок его действия, либо в заголовке Authorization допущена опечатка. Пожалуйста, перейдите в панель управления, чтобы убедиться в активности вашего API Key, а также проверьте ваш код на наличие лишних пробелов или отсутствие правильного префикса.