API транскрибации аудио

Базовый URL в примерах: https://api.model-gate.com. Используйте включённый API своего профиля сервиса или собственного домена. Обычный активный API-ключ определяет допустимый контекст владельца, пользователя ключа и самого ключа. Операция принадлежит этому контексту и не становится автоматически доступной другому ключу. Каждый эндпоинт требует аутентификации и соблюдения применимых ограничений домена/IP и доступа к модели. Playground использует узкое временное разрешение, не раскрывая секрет ключа; обычные браузерные учётные данные не являются универсальными ключами фоновых задач.

Методы

Входные данные multipart

Поля file и model обязательны. Загружайте ровно один файл; ссылки на URL, массивы файлов, тела JSON/base64, пустые загрузки и повторяющиеся скалярные поля отклоняются. Сервер проверяет фактические байты и полное декодирование. Локально поддерживаются контейнеры WAV/MP3/FLAC/OGG/M4A/WebM; отдельное предложение может поддерживать меньше форматов. Максимальный размер записи — 25 MiB, длительность — 1800 секунд, один моно- или стереопоток, частота дискретизации 8000–192000 Hz; выбранное предложение может задавать меньшие пределы. Накладные данные multipart ограничиваются отдельно, а HTTP-слой перед поставщиком может иметь меньший лимит загрузки.

Необязательные поля доступны только при поддержке: response_format из json, verbose_json, text, srt, vtt; language — две строчные латинские буквы; prompt — словарь или контекст в пределах числа символов предложения; temperature — десятичное число от 0 до 1, не более шести знаков после точки; повторяющиеся timestamp_granularities[] со значением word или segment. Не повторяйте одинаковую детализацию. Временные метки требуют verbose JSON. Если формат ответа не указан, используется первый поддерживаемый формат выбранного предложения; остальные отсутствующие параметры не придумываются и не отправляются.

model_gate — локальный JSON-объект с логическим async, полем route_id для конкретного предложенного маршрута и необязательным 64-значным шестнадцатеричным quote_sha256. Неизвестные свойства, повторяющиеся JSON-ключи, неподдерживаемые форматы и параметры отклоняются. Потоковый режим, перевод, разделение по говорящим и генерация аудио не входят в этот эндпоинт. Общие Async/OpenAI Batch нельзя использовать для обхода этого Audio API.

# Explicit paid example: choose a reviewed model, your recording and retain this intent.
curl --fail-with-body 'https://api.model-gate.com/v1/audio/transcriptions' \
  -H "Authorization: Bearer $MODEL_API_KEY" \
  -H 'Idempotency-Key: my-recording-0001' \
  --form-string 'model=YOUR_ALLOWED_TRANSCRIPTION_MODEL' \
  --form-string 'response_format=json' \
  --form-string 'model_gate={"async":true}' \
  -F 'file=@recording.wav'

Не вставляйте настоящий ключ в общие примеры и не добавляйте автоматические повторы cURL. Другая граница multipart или изменённый файл меняют HTTP-тело; при повторе с браузерным разрешением используйте сохранённое точное тело. Идемпотентность обычного API основана на проверенном намерении запроса, хеше файла и настройках, а не на случайной транспортной границе multipart.

Проверка стоимости

Отправьте те же multipart-поля в POST /v1/audio/quote. Эндпоинт проверяет файл и декодирование, возвращает выбранный route_id, сведения request.file, quote, quote_sha256 и явные признаки charged:false, file_content_verified:true, provider_health_verified:false. Рабочая операция и списание с баланса не создаются. Проверка не подтверждает текущую работоспособность поставщика и не резервирует средства.

По условиям предложения стоимость может рассчитываться за успешный запрос, по локально декодированной длительности, по длительности из ответа поставщика или по использованию токенов. Тариф по длительности задаёт шаг округления; при локальном декодировании используется точное число декодированных отсчётов, а не MIME-метаданные или размер файла. Токенный тариф требует фактических непересекающихся данных о входном аудио/тексте и выходном тексте. Отсутствующее обязательное usage — неизвестное, а не нулевое. Данных должно хватать для всех применимых расчётов, даже если цена для клиента фиксирована.

Playground не отправляет max_cost_usd. Необязательная старая форма этого параметра API сохраняется для существующих интеграций, но только при доказуемой фиксированной цене. Передавайте полученный quote_sha256 при запуске, чтобы отклонять изменение ценового контекста. Это не обещание зарезервированных ресурсов. Обновление расчёта цены само по себе не создаёт новый платный запрос.

Идемпотентность и выполнение

Для создания требуется Idempotency-Key: от 1 до 128 символов ASCII без пробелов. Тот же ключ с неизменным намерением возвращает существующую операцию; другая модель, содержимое, нормализованные настройки, маршрут или ценовые условия с этим ключом вызывают конфликт. async меняет ожидание, а не саму задачу. Записи сохраняются после очистки результатов: изменение или удаление локального указателя не разрешает повторную платную отправку.

async=true возвращает HTTP202 и Location. Иначе соединение ожидает до 55 секунд: завершённая работа возвращает сохранённый ответ; незавершённая принятая работа возвращает 202 и может продолжиться после разрыва соединения. Всегда проверяйте состояние операции; HTTP200 при GET статуса не доказывает успешную транскрибацию.

Состояния: queued → preparing → dispatching → received → completed. Безопасная подготовка может ждать свободных ресурсов; срок очереди — пять минут. После начала платной отправки тайм-аут, перенаправление или неоднозначная ошибка поставщика не разрешают автоматический повтор POST или смену поставщика. Неизвестный результат обозначается outcome_unknown; несовместимый сохранённый ответ или отсутствие необходимых ценовых данных — review_required. Явный отказ может перейти в failed. Прочитайте безопасный код ошибки и обратитесь в поддержку, не создавая дубликат.

История и результаты

GET /v1/audio/operations?before=... возвращает 50 последних операций в разрешённой области доступа и курсор. ?idempotency_key=... ищет то же существующее намерение без записи; временное «не найдено» не разрешает автоматический повтор. Обычные ответы статуса компактны. Явный режим деталей добавляет расчёт цены, нормализованное usage и accounting_recorded.

/result возвращает исходный сохранённый ответ в выбранном формате без нового обращения к поставщику. До завершения возвращается конфликт; недоступные или просроченные результаты не генерируются заново. JSON содержит текст поставщика и другие принятые поля ответа; текст, SRT и VTT не оборачиваются в выдуманный JSON. Ответ поставщика ограничен 4 MiB, текст расшифровки — 2 MiB. Обычно результаты доступны 24 часа с момента создания; права доступа должны оставаться действительными.

В явном режиме деталей accounting_recorded означает, что в финансовый расчёт передана ровно одна входная запись, а не что баланс или Usage Limit уже обновлён. Последующее чтение результата не меняет записанное время и тарифы. Неизвестный или требующий проверки результат нельзя считать бесплатным только потому, что этот флаг равен false.

Обработка ошибок

Неправильные запросы получают HTTP400; неподдерживаемый тип медиа/содержимого может получить 415, превышение размера тела — 413, неподдерживаемые параметры или изменение расчёта цены — 422, конфликт намерений — 409, ошибки прав — 401/403, отказ допуска — 429, недоступный каталог или сервис декодирования — 503. Ошибки операции также отражаются в её состоянии: не полагайтесь только на транспортный статус. Безопасные коды различают неправильные файлы, истёкшую очередь, неизвестный результат отправки, неверную структуру результата и отсутствие обязательных данных о токенах/длительности. Не отправляйте вторую запись ради обхода неопределённого результата первого запроса.

Подготовка файла и ошибки расчёта цены

Предложение может задавать исходящий профиль WAV и при этом принимать форматы, перечисленные в каталоге. Клиент всё равно загружает исходный файл. Успешный расчёт цены добавляет transport_file: converted, format, mime, bytes, а при преобразовании — sample_rate, channels, codec. Это прогноз размера результата по числу полностью декодированных аудиосэмплов, а не хеш загруженного файла или проверка здоровья поставщика. Исходный request.file хранится отдельно. max_request_bytes в каталоге — ограничение тела запроса на уровне приложения, а не гарантия такого же лимита на предыдущих HTTP-узлах.

audio_payload_too_large и audio_converted_file_too_large различают слишком большой исходный multipart и слишком большой подготовленный WAV; оба отклоняются до POST поставщику. Локальное декодирование также различает audio_decode_timeout, audio_decode_failed, audio_format_unsupported и audio_codec_unsupported. Ошибка предыдущего HTTP-узла может прийти не в JSON, поэтому сохраняйте фактические статус и тип содержимого. Идентификаторы существующих операций, зафиксированное намерение и запрет автоматического повтора платного запроса не меняются.

Финансовый расчёт и сохранённые ответы поставщика

GET конкретной операции и поиск по идемпотентности с ?view=details включают объект только для чтения settlement, ограниченный теми же владельцем, пользователем, ключом и группой. Он содержит status, record_found, Unix-время settled_at, wallet_debited, usage_applied и Unix-время observed_at. Неизвестные наблюдения имеют значение JSON null. pending/failed не подтверждают завершённое списание; settled/recovered с временной отметкой и положительной сохранённой стоимостью подтверждают зарегистрированный расчёт. not_required отличается от ошибки поиска. not_available означает отсутствие соответствующей записи учёта, возможно после окончания хранения; unavailable означает ошибку наблюдения. Ни одно из них не означает бесплатную работу. Непроверенные строки истории могут сообщать not_checked; прочитайте конкретную операцию для свежего наблюдения. Чтение не создаёт платёж, возврат или резервирование.

supplier_http_status — сохранённый статус поставщика (0 до его появления), а response_saved указывает на зарегистрированное время ответа. Это не HTTP-статус данного API GET или исходного ответа 202 о постановке в очередь. Сохранённый 5xx не доказывает отсутствие расходов у поставщика. Не отправляйте повторно автоматически платный запрос с неизвестным исходом.

Краткий статус и детали расчёта

Начиная с версии 11.0.0, ответы операций по умолчанию компактны: object, id, model, status, created, status_url, result_url. Значимый error_code или сообщённый прогресс включается только при наличии. Завершённые результаты содержат доступность, срок действия и необходимые описания файлов. Пустые поля, расчёт цены, нормализованное usage, settlement и диагностика поставщика опускаются. Отсутствие поля не означает нулевую стоимость или завершённое списание.

Для прежнего полного разрешённого представления расчёта используйте GET /v1/audio/operations/{id}?view=details. Списки и перечни результатов также поддерживают явный режим деталей там, где он применим. Чтение деталей не создаёт медиа и не расширяет права. Эндпоинт quote остаётся отдельным способом просмотра расчёта цены без списания.

Чтение результата: Raw и cURL

Используйте тот же активный API-ключ и контекст пользователя, с которыми создана операция. Другой ключ того же аккаунта не наследует результат автоматически. Текущие права и ограничения домена/IP проверяются снова. Возьмите OPERATION_ID из ответа принятой операции или разрешённой истории, а MODEL_API_KEY задайте локально, не публикуя секрет. Временное разрешение Playground не является многократно используемым CLI-ключом; копирование команды не экспортирует и не расширяет это разрешение.

GET https://api.model-gate.com/v1/audio/operations/{id}/result
Authorization: Bearer <YOUR_API_KEY>

# status
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/audio/operations/${OPERATION_ID:?Set OPERATION_ID}" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output audio-status.json

# result
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/audio/operations/${OPERATION_ID:?Set OPERATION_ID}/result" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output transcript.json

/result — сохранённая транскрибация в формате, выбранном при создании. Имя файла в примере предполагает JSON; для других форматов используйте .txt, .srt или .vtt. Не пытайтесь разобрать текст или субтитры как JSON и не меняйте формат простым изменением имени файла. Исходная запись не является скачиваемым результатом.

Это GET-запросы без тела: не нужны Content-Type, Idempotency-Key, расчёт цены, route_id или max_cost_usd. Читайте статус до завершения, затем результат/файл. Ответы ожидания, ошибки, истёкшего срока и отказа в доступе — не выходные файлы; --fail-with-body возвращает ненулевой код при HTTP-ошибке, но может записать её тело под выбранным именем. Проверяйте статус и тип содержимого, прежде чем считать загруженное тело медиафайлом. Не повторяйте платный POST из-за ошибки GET.

Блок Playground Get the result · Raw / cURL формирует эти команды для выбранной операции и её исходного ключа. Это примеры нового чтения, а не запись прежнего HTTP-обмена. Копирование и переключение вкладок команд не отправляют сетевых запросов. Открытие истории или сохранённого результата выполняет обычное разрешённое чтение, но не новую генерацию, резервирование или списание.