Транскрибация для проектов компании

Базовый URL в примерах: https://api.b2b-llm.com. Используйте включённый API своего профиля сервиса или собственного домена. Ключ проекта действует в расчётном контексте компании. Владелец ключа, сотрудник, работающий в Playground, права группы и членство в компании — разные сущности. Общая компания не открывает все операции каждому сотруднику или ключу. Каждый эндпоинт требует аутентификации и соответствующих разрешений домена, 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.b2b-llm.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 '[email protected]'

Не вставляйте настоящий ключ в общие примеры и не добавляйте автоматические повторы 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. Ошибки операции также отражаются в её состоянии: не полагайтесь только на транспортный статус. Безопасные коды различают неправильные файлы, истёкшую очередь, неизвестный результат отправки, неверную структуру результата и отсутствие обязательных данных о токенах/длительности. Не отправляйте вторую запись ради обхода неопределённого результата первого запроса.

Подготовленный файл и диагностика размера запроса

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

До отправки превышение размера исходного multipart вызывает audio_payload_too_large, а чрезмерное увеличение при преобразовании в WAV — audio_converted_file_too_large. Ни одна из этих ситуаций не приводит к незаметному обрезанию записи компании. Тайм-аут декодирования, ошибка декодирования, неподдерживаемый контейнер и кодек различаются. Обрабатывайте фактический HTTP-код, даже если тело — HTML или обычный текст вместо JSON. Неудачная проверка цены не является платной операцией и не разрешает повтор прежнего запроса с неоднозначным результатом.

Поля наблюдения за расчётом проекта

Детали операции и поиск того же намерения показывают settlement только в текущей области владельца списания, сотрудника/principal, ключа проекта и группы. record_found указывает, найдена ли соответствующая сохранённая входная запись; settled_at и observed_at — временные метки Unix. wallet_debited и usage_applied остаются null до подтверждения записанным событием: отсутствие подтверждения не подменяется false.

Значения status различают not_recorded, ещё не проверенные строки списка not_checked, pending, отложенный failed, not_required, settled/recovered, отсутствующий not_available и ошибку чтения unavailable. Найденная временная метка settled/recovered с положительной стоимостью подтверждает подпись о списании; нулевая стоимость и учёт только в Usage Limit показываются отдельно. Это поле не выполняет расчёт, не сообщает о последующих возвратах и не раскрывает текущий баланс компании. После истечения хранения отсутствие строки не доказывает отсутствие расходов. Откройте конкретную операцию, чтобы обновить ещё не проверенную строку истории.

Поля supplier_http_status (0, если неизвестен) и response_saved описывают сохранённый ответ поставщика, а не статус текущего чтения или подтверждения создания сервисом. Ответ 202/queued не доказывает успех поставщика. Сохраняйте правило: платный запрос с неизвестным результатом не повторяется автоматически.

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

Начиная с версии 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

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

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

# status
curl --fail-with-body --request GET \
  --url "https://api.b2b-llm.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.b2b-llm.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-обмена. Копирование и переключение вкладок команд не отправляют сетевых запросов. Открытие истории или сохранённого результата выполняет обычное разрешённое чтение, но не новую генерацию, резервирование или списание.