Shöpot API Reference

Also available in English

Введение

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

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

Мы используем API-ключи для аутентификации. Ваш API-ключ можно получить в личном кабинете по адресу app.shopot.ai/account. Пожалуйста, храните ваш ключ в безопасности и никогда не раскрывайте его в приложениях и браузерах, храните его только на бэкенде вашего сервера в переменной окружения или другом сервисе управления ключами. Все 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 должен ссылаться на публично доступный файл на вашем/удаленном сервере.
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, а также в теле ответа.

🌐 Поддержка UTF-8: Unicode символы (кириллица, китайские, арабские и др.) автоматически кодируются в base64 с префиксом utf8-b64: для корректной передачи в HTTP заголовках. ASCII символы передаются как есть.

Пример: callback_id="тест123" становится X-Callback-ID: utf8-b64:0YLQtdGB0YIxMjM=
modifier string Опционально
Используется вместе с callback_url. Базовый результат транскрибации содержит несогласованные и незавершённые предложения. Чтобы структурировать ответ на стороне API, вы можете применить модификаторы, либо при запросе вебхука, либо при обращении к эндпоинту для получения транскрибации. Подробнее о структуре модификаторов можно узнать в разделе "Результаты транскрибации". Если параметр установлен на одно из доступных значений, вебхук будет структурирован соответствующим образом.
Поддерживаемые модификаторы: paragraph_json, paragraph_text, plain_text, plain_json.
template string Опционально Шаблон обработки, используемый для определения настроенного рабочего процесса, созданного командой Шöпот для вашей организации, такие как опции постобработки через языковые модели или автоматизацию рабочих процессов. Этот параметр вы получаете от вашего менеджера в команде Шöпот.
summary string Опционально
AI-резюме: Создать краткое изложение транскрипта с помощью ИИ после завершения транскрибации. Резюме создается на обнаруженном или указанном языке.

Типы резюме:
brief - 2-3 предложения с основной идеей (требуется ≥ ~1 минута аудио)
medium - 1-3 абзаца с ключевыми точками и результатами (требуется ≥ ~3-4 минуты аудио)
long - Структурированное детальное резюме с TL;DR, Executive Summary и детализированными разделами (требуется ≥ ~10 минут аудио)

Автоматическое понижение: Если транскрипт слишком короткий для запрошенного типа резюме, система автоматически понижает уровень (long → medium → brief) или пропускает, если все еще слишком короткий.

Статусы резюме: Проверьте summary_status в ответе: PENDING, IN_PROGRESS, COMPLETED, FAILED или SKIPPED.

Возвращает

Ответ API с id и информацией о статусе задания.

Расширенное отслеживание статусов:
transcription_status - отслеживает процесс транскрибации
webhook_status - отслеживает доставку webhook (если указан callback_url)
status - устаревшее поле для обратной совместимости

Статусы транскрибации:
ACCEPTED - запрос принят API сервисом
IN_QUEUE - запрос в очереди на транскрибацию
IN_PROGRESS - запрос транскрибируется
TRANSCRIBED - транскрибация завершена, готов для callback
COMPLETED - полностью завершено (callback не нужен)
FAILED - ошибка транскрибации

Статусы webhook:
PENDING - webhook запланирован для доставки
DELIVERED - webhook успешно доставлен
FAILED - ошибка доставки webhook после повторных попыток

Статусы резюме (при запросе резюме):
summary_status - Отслеживает генерацию AI-резюме
summary - Текст сгенерированного резюме (только при статусе COMPLETED)

Значения статуса резюме:
PENDING - ожидание завершения транскрибации
IN_PROGRESS - идет генерация резюме
COMPLETED - резюме успешно создано
FAILED: {причина} - ошибка генерации резюме
SKIPPED: {причина} - транскрипт слишком короткий

Устаревшие значения статуса:
WEBHOOK_DELIVERED - обработка завершена, webhook доставлен
WEBHOOK_FAILED - ошибка доставки webhook
Пример запроса
Ответ

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

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

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

Возвращает

Ответ API с id и информацией о статусе задачи во время её обработки, а также результаты транскрипции, если обработка завершена.

Статусы транскрибации:
ACCEPTED - запрос принят API сервисом
IN_QUEUE - запрос в очереди на транскрибацию
IN_PROGRESS - запрос транскрибируется
TRANSCRIBED - транскрибация завершена, готов для callback
COMPLETED - полностью завершено (callback не нужен)
FAILED - ошибка транскрибации

Статусы webhook:
PENDING - webhook запланирован для доставки
DELIVERED - webhook успешно доставлен
FAILED - ошибка доставки webhook после повторных попыток

Статусы резюме (когда запрошено резюме):
summary_status - Отслеживает генерацию AI-резюме
summary - Текст сгенерированного резюме (только когда статус COMPLETED)

Значения статуса резюме:
PENDING - ожидание завершения транскрибации
IN_PROGRESS - генерация резюме в процессе
COMPLETED - резюме успешно сгенерировано
FAILED: {причина} - ошибка генерации резюме
SKIPPED: {причина} - транскрипт слишком короткий для резюме

Обратная совместимость:
WEBHOOK_DELIVERED - обработка завершена, webhook доставлен
WEBHOOK_FAILED - ошибка доставки webhook
Пример запроса
Статус обработки

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

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

Поля

id string
ID задачи
status string
Статус обработки.
balance_minutes string
Оставшийся баланс минут или кредитов на вашем аккаунте.
summary string Опционально
AI-резюме: Сгенерированное резюме транскрипта. Появляется только когда параметр summary был указан в запросе и summary_status имеет значение COMPLETED.
output string
Результаты транскрибации, включающие:
duration string
Продолжительность файла в секундах.
language string
Язык файла, либо отправленный с запросом, либо автоматически определенный.
list array
Тайминг транскрибации, говорящие, текст
start string
Таймкод начала текстового сегмента в секундах от начала файла.
end string
Таймкод конца текстового сегмента в секундах от начала файла.
speaker string
ID говорящего, определенный моделью.
text string
Текст сегмента.
Эндпоинт с модификатором Опционально
GET https://api.shopot.ai/v1/status/{id}/paragraph_json
paragraph_json - Агрегированные предложения и абзацы (где возможно) из расшифрованного текста, разделённого по спикерам, с указанием начального таймкода абзаца в секундах от начала файла в поле list. Параметры запроса передаются в формате JSON.
paragraph_text - Агрегированные предложения и абзацы (где возможно) из расшифрованного текста, разделённого по спикерам, с указанием начального таймкода абзаца в формате, читаемом человеком (Часы:Минуты:Секунды), в формате plain text. Параметры запроса отсутствуют, возвращается только транскрипт.
plain_json - Без спикеров, без таймкодов, расшифрованный текст в одной части в поле list. Параметры запроса передаются в формате JSON.
plain_text - Без спикеров, без таймкодов, расшифрованный текст в одной части в формате plain text. Параметры запроса отсутствуют, возвращается только транскрипт.
Ответ
Модификатор: 

Ошибки

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 У пользователя недостаточно средств для продолжения транскрибирования. Пожалуйста, пополните баланс. Примечание: Пользователи SaaS API должны иметь минимальный остаток баланса 60 минут для API-вызовов.
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, .oga, .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, что может свидетельствовать о проблемах с доступностью файла.