Базовый вызов Whisper API несложен: POST-запрос, аудиофайл и ключ — на выходе текст транскрипции. Время уходит на детали: файл больше 25 МБ, формат не принимается, таймкоды не приходят, а после нарезки длинного аудио временная шкала смещается.

Ниже по порядку подключения: endpoint и авторизация, форматы и ограничение размера, разница между транскрипцией и переводом, параметры таймкодов, вызовы через curl и Python, нарезка длинного аудио, частые ошибки и чек-лист миграции.

Примечание: OpenAI и Whisper являются товарными знаками их правообладателей; автор не связан с OpenAI. Возможности интерфейса, ограничения файлов и правила биллинга могут меняться; ориентируйтесь на официальную документацию и документацию сайта, а цены — на страницу тарифов. Полную поддержку аудиоинтерфейса конкретным шлюзом уточняйте в документации сайта.

1. Сначала проверьте endpoint и авторизацию

Аудиоинтерфейс и чат-интерфейс находятся по разным путям. Транскрипция — /v1/audio/transcriptions, перевод — /v1/audio/translations; оба используют POST, тело запроса — multipart/form-data, а не JSON. Авторизация — Bearer Token в стиле OpenAI.

Параметр Описание
Endpoint транскрипции POST /v1/audio/transcriptions
Endpoint перевода POST /v1/audio/translations
Заголовок авторизации Authorization: Bearer <API_KEY>
Тип запроса multipart/form-data
Официальный Base URL https://api.openai.com/v1
Base URL шлюза https://ai.zhongshangqihang.com/v1; поддержку аудио уточняйте в документации сайта

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

2. Поддерживаемые форматы и лимит 25 МБ

Официально указаны входные форматы mp3, mp4, mpeg, mpga, m4a, wav и webm; максимальный размер одного файла — 25 МБ. Для flac, ogg и подобных форматов не стоит рассчитывать на приём — сначала перекодируйте.

25 МБ — это ограничение размера файла, а не длительности. Чем выше битрейт, тем короче аудио помещается в тот же объём: моно mp3 с частотой 16 кГц может занимать много времени, а стерео wav 48 кГц превысит лимит уже через десяток минут. Надёжная предварительная обработка — единое приведение к 16 кГц, моно, mp3 или wav.

3. Транскрипция и перевод — не одно и то же

/audio/transcriptions преобразует аудио в текст на исходном языке: китайское аудио даёт китайский текст. /audio/translations переводит аудио в английский; официальная документация прямо указывает, что поддерживается только перевод на английский и используется whisper-1. Для субтитров на китайском нужна транскрипция, а не интерфейс перевода.

Язык задаётся кодом ISO-639-1, например zh, en, ja, ru. Если не передавать его, модель определит язык автоматически, но на коротком аудио, смешанной речи и сильном акценте возможны ошибки. Когда язык бизнеса известен, надёжнее указать его явно.

4. Минимальный пример curl

curl "https://ai.zhongshangqihang.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "language=ru" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=segment"

Обратите внимание на три вещи: файл передаётся через -F; у timestamp_granularities[] есть квадратные скобки; структуру сегментов возвращает только verbose_json. Если шлюз не поддерживает параметр, сначала уберите его и протестируйте, постепенно локализуя проблему.

5. Вызов из Python и таймкоды

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["WHISPER_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        language="ru",
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

for seg in result.segments:
    print(f"{seg.start:.1f}-{seg.end:.1f}  {seg.text}")

Таймкоды бывают двух уровней: segment — уровень фразы, подходит для субтитров и протоколов встреч; word — уровень слова, подходит для пословного выравнивания. Официальная документация указывает, что timestamp_granularities[] сейчас работает только с whisper-1 и требует verbose_json. Более новые модели транскрипции могут быть точнее, но поддержка таймкодов и форматов субтитров у них различается; перед выбором смотрите документацию.

При большом числе имён собственных можно передать в prompt имена людей, продуктов и термины. Документация указывает, что лимит подсказки для whisper-1 — 224 токена; при превышении она может обрезаться, поэтому оставляйте только ключевые слова.

Если нужен только текст, используйте response_format со значением json или text; для файлов субтитров можно сразу запросить srt или vtt. Чем богаче формат, тем больше тело ответа; в пакетных сценариях учитывайте трафик и стоимость разбора.

6. Длинное аудио сначала нарезают, потом транскрибируют

Аудио больше 25 МБ необходимо нарезать. Рекомендуемый процесс:

  1. Приведите файл через ffmpeg к 16 кГц и моно, чтобы уменьшить объём.
  2. Режьте по обнаружению тишины или фиксированными десятиминутными отрезками, избегая разреза посреди фразы.
  3. Записывайте начальное смещение каждого фрагмента: например, part_000 соответствует 0 секунд, part_001 — 600 секунд.
  4. Вызывайте транскрипцию по фрагментам и сохраняйте исходные ответы.
  5. При объединении текста прибавляйте смещение к каждому таймкоду.
  6. Выборочно сверяйте текст около точек разреза, обрабатывая повторы и пропуски.

Между фрагментами можно оставлять перекрытие 0,5–1 секунды, чтобы не терять слова на границе, но эти участки будут транскрибированы повторно, и при объединении их нужно дедуплицировать. Скрипт нарезки должен сохранять список смещений; не угадывайте время по имени файла — несоответствие имён, порядка и смещений является самой частой аварией на этапе объединения. Параллелизм сокращает общее время, но не превышайте лимит аккаунта, иначе повторы 429 только замедлят процесс.

7. Как разбирать частые ошибки

  • 401: неверный или просроченный ключ либо отсутствует Bearer.
  • 404: ошибка в Base URL или пути; проверьте /v1/audio/transcriptions.
  • 400: неподдерживаемый формат, опечатка в параметре или модель не поддерживает параметр.
  • 413: файл превышает лимит размера; сожмите или нарежьте.
  • 429: превышен параллелизм или квота; снизьте параллелизм и повторите с экспоненциальной задержкой.
  • 5xx или таймаут: проблема сервера или сети; ограничьте число повторов, чтобы избежать повторного списания.
  • Пустой текст: аудио без звука, слишком тихое или неверно определён язык; проверьте файл и укажите language.
  • Нет таймкодов: response_format не verbose_json или модель не whisper-1.

8. Чек-лист миграции с официального доступа на шлюз

  1. Уточните Base URL целевого шлюза и путь аудиоинтерфейса.
  2. Проверьте, что нужная модель доступна на сайте и называется так же, как официальная.
  3. Переведите тело запроса с JSON на multipart/form-data.
  4. Согласуйте response_format и проверьте, не зависит ли код от поля segments.
  5. Убедитесь, что параметры таймкодов поддерживаются; если нет — вернитесь к уровню сегментов или локальному выравниванию.
  6. Задайте разумные таймауты и максимальное число повторов.
  7. Не пишите в журналы полный адрес аудио и ключ; текстовые результаты считайте чувствительными данными.
  8. Прогоните регрессию на наборе реальных бизнес-аудио, сравните долю ошибок и временную шкалу.
  9. Подготовьте путь деградации: смена модели, региона или возврат к официальному интерфейсу.

Частые вопросы

Чем Whisper API отличается от открытой модели Whisper?

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

25 МБ — это ограничение длительности аудио?

Нет, это ограничение размера файла. Снижение битрейта и переход в моно заметно увеличивают допустимую длительность; при превышении лимита файл нужно нарезать.

Почему не приходят таймкоды уровня слова?

Для этого одновременно нужны whisper-1, verbose_json и timestamp_granularities=["word"]. Смена модели или формата может привести к отсутствию поля.

Может ли интерфейс перевода перевести английский на китайский?

Нет. Официальный интерфейс перевода выдаёт только английский. Для китайского сценария используйте транскрипцию и затем переводите текст текстовой моделью.

Можно ли просто заменить официальный Base URL на адрес шлюза?

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

Что дальше

Сначала зарегистрируйтесь в ZSQH AI Gateway, создайте тестовый ключ, прогоните минутное аудио через транскрипцию, затем проверьте таймкоды и нарезку длинного файла. Модели и цены смотрите на странице тарифов.

Читайте также: