Документация API: Транскрибация аудио в текст (Whisper-1)

1. Обзор API

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

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

2. Спецификация запроса

Базовый URL: https://api.codingplanx.ai
Путь запроса: /v1/audio/transcriptions
Метод запроса: POST
Content-Type: multipart/form-data

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

3.1 Заголовки (Headers)

Параметр	Обязательно	Тип	Пример значения	Описание
`Content-Type`	Нет	string	`multipart/form-data`	Указывает формат данных тела запроса.
`Authorization`	Да	string	`Bearer YOUR_API_KEY`	(Примечание: стандартный заголовок авторизации, укажите ваш API Key)

3.2 Тело запроса (Body - multipart/form-data)

Параметр	Обязательно	Тип	Пример значения	Описание
`file`	Да	file	`file://.../test.m4a`	Аудиофайл для транскрибации (именно объект файла, а не его имя). Поддерживаемые форматы: `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav` или `webm`.
`model`	Да	string	`whisper-1`	ID используемой модели. Доступные варианты: `whisper-1`, `gpt-4o-mini-transcribe`.
`language`	Нет	string	`ru`	Язык исходного аудио. Указание языка в формате `ISO-639-1` (например, `ru` для русского, `en` для английского) повышает точность и снижает задержку ответа.
`prompt`	Нет	string	`Это аудио на русском языке`	Необязательная текстовая подсказка для управления стилем модели или продолжения предыдущего фрагмента. Язык подсказки должен совпадать с языком аудио.
`response_format`	Нет	string	`json`	Формат вывода транскрипции. По умолчанию `json`.<br>Доступные значения: `json`, `text`, `srt`, `verbose_json` или `vtt`.
`temperature`	Нет	number	`0`	Температура выборки, от `0` до `1`. По умолчанию `0`.<br>Более высокие значения (например, 0.8) делают вывод более случайным, а низкие (например, 0.2) — более сфокусированным и детерминированным. При значении 0 модель автоматически увеличит температуру на основе логарифмической вероятности до достижения определенного порога.

4. Спецификация ответа

4.1 Структура данных ответа

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

Поле	Тип	Обязательно	Описание
`text`	string	Да	Сгенерированный текстовый контент после транскрибации аудио.

4.2 Пример ответа (HTTP 200 - Успешно)

{
  "text": "12345678910"
}

(Примечание: Если response_format установлен как text, srt или vtt, API вернет непосредственно обычный текст или формат субтитров, а не объект JSON)

5. Пример кода запроса (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=@"/C:/Users/Administrator/Desktop/test.m4a"' \
--form 'model="whisper-1"' \
--form 'language="ru"' \
--form 'response_format="json"'

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

В1: Какой максимальный размер аудиофайла поддерживает этот API?

О: Обычно API Whisper ограничивает размер одного аудиофайла до 25 МБ. Если ваш файл превышает этот лимит, рекомендуется сжать его перед отправкой (например, конвертировать в mp3 с более низким битрейтом) или разделить длинное аудио на несколько коротких фрагментов для отдельных запросов.

В2: Почему в тексте транскрипции появляются опечатки или неправильно распознаются специфические термины/имена?

О: Модели распознавания речи могут быть недостаточно чувствительны к узкоспециализированным отраслевым терминам, именам собственным или редкой лексике. Эту проблему можно решить с помощью параметра prompt (подсказка). Если вы заранее укажете эти специфические слова в prompt, модель будет учитывать их и использовать заданный вами стиль лексики при транскрибации.

В3: Могу ли я с помощью этого API напрямую создать файл субтитров для видео?

О: Да. Вам нужно лишь установить параметр response_format на srt или vtt при выполнении запроса. После успешной обработки API вернет готовое содержимое стандартного файла субтитров с таймкодами, которое вы сможете сохранить как файл .srt или .vtt для использования в видеоплеере.

В4: В чем конкретно преимущество передачи параметра language?

О: Хотя модель Whisper способна автоматически определять язык, в случаях, когда в начале аудио присутствует тишина, шум или язык не слишком очевиден, процесс автоопределения может занять дополнительное время или привести к ошибке. Явное указание правильного кода языка в формате ISO-639-1 (например, ru для русского, zh для китайского) не только значительно снижает задержку при обработке запроса, но и повышает общую точность транскрибации.

В5: В чем причина ошибки Unsupported file format?

О: Как правило, это означает, что формат загруженного файла не поддерживается системой. Убедитесь, что ваш аудиофайл имеет один из следующих форматов: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav или webm. Также обратите внимание, что простое переименование расширения файла (например, с .avi на .mp4) не сработает; файл должен иметь действительно поддерживаемый формат кодирования аудио.