Документация API: Транскрибация аудио (Audio Transcription)

Данный документ содержит описание API для транскрибации аудиофайлов в текст. Этот интерфейс базируется на передовых моделях распознавания речи (таких как gpt-4o-transcribe), поддерживает множество входных аудиоформатов и позволяет настраивать формат вывода и язык распознавания.

Официальная документация: OpenAI Speech-to-Text Guides

---

1. Основная информация

• Название интерфейса: Транскрибация аудио gpt-4o-transcribe
• Метод запроса: POST
• URL запроса: https://api.codingplanx.ai/v1/audio/transcriptions

---

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

---

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

Тело запроса должно быть передано в формате multipart/form-data:

---

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

4.1 Параметры ответа (формат JSON)

Если response_format установлен в json (по умолчанию), HTTP статус-код будет 200 OK, а структура возвращаемого JSON будет следующей:

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

Пример 1: Распознавание на английском

{
  "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that."
}

Пример 2: Распознавание на китайском

{
  "text": "一二三四五六七八九十"
}

---

5. Примеры вызова (Code Snippets)

cURL

curl --location --request POST 'https://api.codingplanx.ai/v1/audio/transcriptions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"/path/to/your/audio/test.m4a"' \
--form 'model="gpt-4o-transcribe"' \
--form 'response_format="json"'

Python (Requests)

import requests

url = "https://api.codingplanx.ai/v1/audio/transcriptions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "model": "gpt-4o-transcribe",
    "response_format": "json",
    "language": "zh"
}
files = {
    "file": ("test.m4a", open("/path/to/your/audio/test.m4a", "rb"), "audio/mp4")
}

response = requests.post(url, headers=headers, data=payload, files=files)

print(response.json())

---

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

Q1: Какие форматы аудиофайлов поддерживает API? A: В настоящее время API поддерживает следующие форматы: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav и webm. Пожалуйста, убедитесь, что формат вашего файла и его расширение совпадают.

Q2: Почему иногда распознавание аудио происходит медленно, или первые несколько слов распознаются неточно? A: Обычно это связано с тем, что модель пытается автоматически определить язык аудио. Настоятельно рекомендуется передавать параметр language при запросе (используя стандарт ISO-639-1, например, ru для русского, en для английского). Это не только уменьшит задержку обработки, но и значительно повысит точность распознавания.

Q3: Как заставить модель распознавать конкретные имена собственные или отраслевые термины? A: Вы можете использовать параметр prompt (подсказка). Передайте имена собственные, имена людей или специфический стиль пунктуации, которые модель должна распознать точно, в виде текста в параметр prompt. При транскрибации модель будет учитывать контекст и стиль этой подсказки. Внимание: язык промпта должен строго совпадать с языком аудио.

Q4: В чем разница между json и text в параметре response_format? A:

• При выборе json (по умолчанию): API вернет стандартный JSON-объект {"text": "транскрибированный текст"}, который легче всего парсить в большинстве backend-приложений.
• При выборе text: API вернет просто строку чистого текста (Content-Type: text/plain) без внешней структуры JSON, что идеально подходит для простых скриптов, которым нужен только текстовый контент.

Q5: Как следует настраивать параметр temperature? A: В большинстве сценариев транскрибации рекомендуется оставить значение по умолчанию 0. При этой настройке модель будет отдавать приоритет наиболее логичному и детерминированному тексту. Если ваше аудио содержит много фонового шума или нестандартное произношение, что приводит к "галлюцинациям" или пропуску слов, вы можете попробовать немного повысить температуру (например, от 0.2 до 0.4), чтобы увеличить гибкость распознавания модели.