Whisper — открытая модель распознавания речи от OpenAI, для которой также существует управляемый интерфейс транскрипции. Разработчику проще не разворачивать модель самостоятельно, а получить ключ, вызвать /v1/audio/transcriptions, отправить аудиофайл и сразу получить текст.

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

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

1. Что умеет Whisper API

  • Перевод в текст записей совещаний, интервью и лекций;
  • черновые субтитры для подкастов и коротких видео;
  • контроль качества звонков поддержки и извлечение ключевых слов;
  • приведение в порядок голосовых заметок;
  • многоязычная транскрипция и перевод (перевод — отдельный интерфейс).

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

2. Получение Whisper API Key

Отдельного «ключа Whisper» не существует: используется API-ключ платформы OpenAI или шлюза. Далее под Whisper API Key понимается именно ключ, дающий доступ к интерфейсу транскрипции.

Вариант 1: официальный OpenAI

  1. Зарегистрируйте аккаунт на платформе OpenAI и настройте способ оплаты.
  2. На странице API Keys создайте ключ и назовите его по проекту.
  3. Убедитесь, что на счёте есть доступный баланс.
  4. Сохраните ключ в переменную окружения на сервере.

Вариант 2: ZSQH AI Gateway

  1. Откройте ZSQH AI Gateway, зарегистрируйтесь и войдите.
  2. Перейдите на страницу API-ключей и создайте новый ключ.
  3. На странице цены на модели или в документации уточните, доступна ли модель транскрипции.
  4. Пополните небольшую сумму и проверьте на коротком аудио.

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

3. Base URL и аутентификация

Параметр Официальный OpenAI Шлюз ZSQH
Base URL https://api.openai.com/v1 https://ai.zhongshangqihang.com/v1
Аутентификация Authorization: Bearer <key> Так же
Интерфейс /audio/transcriptions По документации на сайте
Модель whisper-1 и другие По документации или странице цен

Передаёт ли шлюз аудиоинтерфейс полностью и какие response_format поддерживает, нужно проверять по документации на сайте. Не исходите из того, что раз текстовый интерфейс работает, то и аудио тоже.

4. Вызов через curl

export WHISPER_API_KEY="sk-ваш-ключ"

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=json"

Обратите внимание: это multipart/form-data, а не JSON. Используйте -F, а не -d, иначе сервер не получит файл.

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}")

language принимает код ISO-639-1, например ru, en, zh. Если не передавать параметр, модель определит язык сама, но на коротком аудио или при смешении языков возможны ошибки; явное указание надёжнее.

6. Форматы и ограничения размера

Параметр Типичное ограничение Рекомендация
Поддерживаемые форматы flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm Приводите к mp3 или wav
Размер одного файла 25 МБ (по официальной документации) Делите при превышении
Частота дискретизации Жёстких требований нет Достаточно 16 кГц, моно
Длительность Косвенно ограничена размером файла Делите длинное аудио на отрезки по 10 минут
Многоканальное аудио Поддерживается, но качество распознавания ниже Сначала сведите каналы или выберите основной

При неподходящем формате обычно возвращается 400, при слишком большом файле — 413. Перекодирование — самый надёжный способ подготовки.

7. Метки времени и формат вывода

response_format Что возвращается Для чего подходит
json Простой текст Нужен только текст
text Простой текст, более лёгкое тело ответа Скрипты и конвейеры
srt Файл субтитров Монтаж видео
vtt Веб-субтитры Веб-плееры
verbose_json Текст, сегменты, язык, длительность Нужны метки времени

Метки на уровне сегментов задаются через timestamp_granularities=["segment"]; метки на уровне слов обычно доступны только для whisper-1 и требуют verbose_json. Точную поддержку сверяйте с официальной документацией или документацией на сайте.

8. Что делать с длинным аудио

Аудио, превышающее лимит, нарежьте через ffmpeg и распознавайте по частям:

ffmpeg -i input.mp3 -f segment -segment_time 600 \
  -ac 1 -ar 16000 -b:a 64k part_%03d.mp3

При нарезке учитывайте:

  1. По возможности режьте в местах тишины, чтобы не разрывать слово.
  2. Записывайте смещение начала каждого фрагмента и прибавляйте его при объединении.
  3. Оставляйте перекрытие 0,5–1 секунды, чтобы не терять слова на границах.
  4. После объединения удалите дубли и приведите пунктуацию.

9. Частые ошибки

Ошибка Причина Что делать
401 Неверный ключ или отсутствует Bearer Проверьте ключ и заголовки
404 Неверный Base URL или путь Убедитесь, что используется /v1/audio/transcriptions
400 unsupported file Формат не поддерживается Перекодируйте в mp3 или wav
413 Файл слишком большой Сожмите или нарежьте
429 Превышена частота или квота Снизьте параллелизм, повторите с задержкой
Пустой текст Тишина, низкая громкость, неверный язык Проверьте аудио и укажите language
Тайм-аут Большой файл или медленная сеть Нарежьте, увеличьте тайм-аут

10. Контроль расходов

  1. Перед транскрипцией выполняйте обнаружение тишины и удаляйте пустые участки.
  2. Приводите аудио к 16 кГц моно, чтобы уменьшить размер.
  3. Длинные файлы обрабатывайте частями параллельно, но ограничивайте параллелизм, чтобы избежать 429.
  4. Сначала проверяйте язык и качество на коротком образце, затем отправляйте пакет.
  5. Записывайте длительность каждого вызова и сверяйте расходы по проектам.
  6. Ограничивайте число повторов, чтобы не платить дважды.

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

11. Как повысить точность

  1. Подготовка аудио: 16 кГц, моно, лёгкое шумоподавление, удаление щелчков и длинной тишины.
  2. Явный язык: для русского указывайте language=ru; при смешении языков оцените, не стоит ли обрабатывать части раздельно.
  3. Подсказка: передавайте в prompt имена, названия продуктов и термины, чтобы модель использовала правильные слова.
  4. Разумная нарезка: по тишине, отрезками 5–10 минут, без потери слов на стыках.
  5. Постобработка: проверяйте числа, даты, суммы и имена правилами, ключевые места просматривайте вручную.
  6. Словарь замен: собирайте частые ошибки в таблицу замен и обновляйте её от версии к версии.

Единой цифры точности не существует: она сильно зависит от качества записи, акцента и предметной лексики. Перед запуском проведите выборку на реальных аудио своего бизнеса — это полезнее рекламных параметров.

12. Приватность и соответствие требованиям

  • В аудио могут быть имена, телефоны, адреса и медицинские сведения; перед загрузкой сообщите об обработке и получите согласие.
  • Чувствительные материалы сначала обезличивайте или используйте решение с приватным развёртыванием.
  • Уточните политику хранения, ведения журналов и удаления у поставщика.
  • Не размещайте аудио с данными клиентов по общедоступному URL.
  • При трансграничной передаче оцените местные нормы и требования комплаенса компании.

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

Поддерживает ли Whisper API русский язык?

Да. Для русского рекомендуется явно передавать language=ru, а имена и термины добавлять в подсказку или обрабатывать при постобработке.

Можно ли одним ключом вызывать текстовые модели?

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

Можно ли получить метки времени на уровне слов?

Часть моделей и форматов это поддерживает, обычно через verbose_json и timestamp_granularities. Ориентируйтесь на документацию.

Что делать, если аудио больше 25 МБ?

Сожмите через ffmpeg или нарежьте по 10 минут, распознайте по частям и объедините. Точки разреза выбирайте в местах тишины.

Можно ли использовать результат в коммерческих целях?

Зависит от прав на аудио, условий платформы и местного законодательства. Если запись содержит чужие голоса, музыку или материалы курса, сначала подтвердите разрешение.

Что дальше

Зарегистрируйтесь в ZSQH AI Gateway, создайте тестовый ключ, проверьте /v1/audio/transcriptions на минутной записи и только затем подключайте пакетную обработку. Модели и цены смотрите на странице цены на модели.

Похожие материалы: