Shöpot API Reference

Also available in English

Введение

API транскрибации Shopot.ai позволяет конвертировать аудио-видео файлы в текст. Вы можете взаимодействовать с API через HTTP-запросы из любого языка программирования.

Аутентификация

Мы используем API-ключи для аутентификации. Ваш ключ можно получить у команды поддержки по адресу hi@shopot.ai. Пожалуйста, храните ваш ключ в безопасности и никогда не раскрывайте его в приложениях и браузерах, храните его только на бэкенде вашего сервера в переменной окружения или другом сервисе управления ключами. Все API-запросы требуют включения API-ключа в заголовок Authorization:

Authorization: Bearer $SHOPOT_API_KEY

Доступные методы

API Shopot поддерживает два основных метода отправки аудиофайлов для транскрибации:

Создать транскрибацию

POST https://api.shopot.ai/v1/transcribe

Транскрибирует аудиофайл и обрабатывает транскрипт через LLM. Возвращает уникальный id запроса и status.

Тело запроса

url или file string Обязательно
В зависимости от выбранного источника файла, вы будете использовать параметры URL или File. URL должен ссылаться на публично доступный файл на вашем/удаленном сервере. Размер файла ограничен 200 Мб. Свяжитесь с поддержкой здесь, если вам нужны большие загрузки.
language string Необязательно По умолчанию автоопределение
Язык аудио. Укажите входной язык в формате ISO-639-1. Если ничего не указано, произойдет автоопределение по первым секундам аудио. Поддерживаемые коды языков: af, ar, az, be, bg, bs, ca, cs, cy, da, de, el, en, es, et, fa, fi, fr, gl, he, hi, hr, hu, hy, id, is, it, ja, kk, ko, lt, lv, mi, mk, ms, ne, nl, no, pl, pt, ro, ru, sk, sl, sr, sv, sw, th, tr, uk, vi, zh
initial_prompt string Необязательно
Необязательная подсказка для определения специальной лексики или направления модели для правильной транскрибации имен и терминологии. Должна соответствовать входному языку.
vad_filter boolean или null Необязательно По умолчанию True
Фильтр обнаружения голосовой активности, используемый для вырезания тишины и ускорения процесса транскрибации. Для файлов низкого уровня громкости или низкого качества рекомендуется выполнять запрос с опцией false.
Варианты: true или false.
disable_diarization boolean Необязательно По умолчанию False
По умолчанию модель будет диаризировать файл и возвращать транскрипт с текстом, распределенным по обнаруженным говорящим.
Варианты: true или false.

callback_url string Необязательно
URL Webhook, который будет вызван методом POST для возврата результатов после завершения обработки или в случае ошибки. Сервис осуществляет 3 попытки доставки сообщения с задержкой в 60 секунд между попытками. При доставке результатов обработки status задачи изменяется на WEBHOOK_DELIVERED или WEBHOOK_FAILED, при доставке ошибок обработки статус не меняется.

callback_id string Необязательно
Любое значение ID, необзодимое для идентификации вашего исходного запроса, которое будет отправлено в Webhook при возврате результата. Параметр передается в заголовках запроса в параметре x-callback-id, а так же в теле ответа.
template string Необязательно Шаблон обработки, используемый для определения настроенного рабочего процесса, созданного командой Шöпот для вашей организации, такие как опции постобработки через языковые модели или автоматизацию рабочих процессов. Этот параметр вы получаете от вашего менеджера в команде Шöпот.

Возвращает

Ответ API с id и status задания.
Возможные статусы:
ACCEPTED - запрос принят API сервисом
IN_QUEUE - запрос в очереди на транскрибацию
IN_PROGRESS - запрос транскрибируется
COMPLETED - обработка завершена, если не задан callback_url
WEBHOOK_DELIVERED - завершена обработка, Webhook доставлен успешно по заданному callback_url
WEBHOOK_FAILED - ошибка доставки Webhook по заданному callback_url
FAILED - ошибка обработки с указанием текста ошибки
Пример запроса
Ответ

Получение результатов или статуса транскрибации

Чтобы получить статус задачи транскрибации, вам всегда нужно пройти аутентификацию, предоставив заголовок Authorization с Bearer $SHOPOT_API_KEY, используя следующую конечную точку:

GET https://api.shopot.ai/v1/transcribe/{id}

Возвращает

Ответ API с id и status задания.
Возможные статусы:
ACCEPTED - запрос принят API сервисом
IN_QUEUE - запрос в очереди на транскрибацию
IN_PROGRESS - запрос транскрибируется
COMPLETED - обработка завершена, если не задан callback_url
WEBHOOK_DELIVERED - завершена обработка, Webhook доставлен успешно по заданному callback_url
WEBHOOK_FAILED - ошибка доставки Webhook по заданному callback_url
FAILED - ошибка обработки с указанием текста ошибки
Пример запроса
Статус обработки

JSON результат транскрибации

id string
ID задачи
status string
Статус обработки.
balance_minutes string
Оставшийся баланс минут или кредитов на вашем аккаунте.
output string
Результаты транскрибации, включающие:
duration string
Продолжительность файла в секундах.
language string
Язык файла, либо отправленный с запросом, либо автоматически определенный.
list array
Тайминг транскрибации, говорящие, текст
start string
Таймкод начала текстового сегмента в секундах от начала файла.
end string
Таймкод конца текстового сегмента в секундах от начала файла.
speaker string
ID говорящего, определенный моделью.
text string
Текст сегмента.
JSON ответ

Ошибки

API использует стандартные HTTP коды ответов для указания успеха или неудачи запросов. Ответы с ошибками будут включать JSON объект с более подробной информацией об ошибке.

HTTP код Детали Описание
400 Invalid URL or file not accessible Указанный URL либо неправильно сформирован, либо сервер не может получить доступ к файлу. Пользователям следует проверить правильность URL и доступность ресурса.
400 Failed to resolve URL: [details] Указанный URL не может быть разрешен. Это может произойти из-за проблем с сетью или если URL указывает на несуществующий ресурс. Проверьте URL на наличие опечаток или попробуйте позже.
400 The 'URL' field must be a string Поле url, переданное в теле запроса, должно быть строкой. Убедитесь, что это не список или другой тип данных.
400 Invalid 'URL' format. Must start with http or https URL, предоставленный для файла, должен начинаться с http:// или https://.
400 File or URL required Должен быть предоставлен хотя бы один из file или url. Убедитесь, что вы прикрепили либо файл, либо указали URL для транскрибирования.
400 The 'callback_url' field must be a string Поле callback_url должно быть корректной строкой. Убедитесь, что оно правильно отформатировано и является допустимым URL.
400 Invalid 'callback_url' format. Must start with http or https Обратный URL должен быть допустимым и начинаться с http:// или https://.
400 Invalid language format. Must be a string Параметр language должен быть строкой. Убедитесь, что это один из допустимых языковых кодов.
400 Invalid language code: [language_code] Указанный language не поддерживается. Обратитесь к документации для получения списка поддерживаемых кодов языков.
403 Forbidden: Invalid API key Указанный API-ключ некорректен или не авторизован. Убедитесь, что вы используете правильный ключ.
403 Forbidden: Invalid API key format API-ключ должен начинаться с префикса Bearer. Убедитесь, что он правильно отформатирован.
403 Insufficient balance У пользователя недостаточно средств для продолжения транскрибирования. Пожалуйста, пополните баланс.
404 Request not found Указанный request_id не соответствует ни одному существующему запросу. Проверьте правильность request_id.
413 File size exceeds [max_size]MB limit Размер предоставленного файла превышает допустимый лимит [max_size] МБ. Пожалуйста, загрузите меньший файл или свяжитесь с поддержкой для обсуждения увеличения лимита.
415 Unsupported file extension: [file_extension] Предоставленное расширение файла не поддерживается. Допустимые расширения включают .mp3, .wav, .flac, .ogg, .aac, .m4a, .wma, .mp4, .mov, .avi, .mkv, .webm, .wmv, .m4v, .flv.
500 Transcription result not found Процесс транскрибирования не смог получить результат. Возможно, произошли проблемы с сервером. Попробуйте еще раз позже или свяжитесь с поддержкой.
500 Failed to access the file or invalid URL Система не смогла получить доступ к указанному URL, что может свидетельствовать о проблемах с доступностью файла.