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

Возвращает

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

🔄 Расширенное отслеживание статусов (v2.1.1+):
• 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 после повторных попыток

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

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

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

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

Возвращает

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

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

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

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

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

По умолчанию API возвращает сегменты транскрибированного файла с подробными временными метками в формате 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
Текст сегмента.
Эндпоинт с модификатором Опционально
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 У пользователя недостаточно средств для продолжения транскрибирования. Пожалуйста, пополните баланс.
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, что может свидетельствовать о проблемах с доступностью файла.

📲 Улучшенные возможности Webhook (v2.1.1)

🌐 Поддержка UTF-8 для Callback ID

Webhook обратные вызовы теперь полностью поддерживают международные символы в callback ID и JSON данных:

🔤 ASCII символы: Отправляются напрямую в HTTP заголовках
🌐 Unicode символы: Автоматически кодируются в base64 с префиксом utf8-b64:
📄 JSON данные: Явное UTF-8 кодирование обеспечивает правильную передачу символов

Декодирование Callback ID в вашем обработчике Webhook

При получении webhook с Unicode callback ID, используйте эту логику декодирования:
Пример на Python
import base64

def decode_callback_id(header_value):
    """Декодировать callback ID из заголовка webhook"""
    if header_value.startswith('utf8-b64:'):
        # Убрать префикс и декодировать base64
        encoded_part = header_value[9:]
        decoded_bytes = base64.b64decode(encoded_part)
        return decoded_bytes.decode('utf-8')
    else:
        # ASCII символы, декодирование не нужно
        return header_value

# Использование в вашем обработчике webhook
callback_id = request.headers.get('X-Callback-ID')
if callback_id:
    original_id = decode_callback_id(callback_id)
    print(f"Исходный callback ID: {original_id}")

Улучшенный формат ответа

Данные webhook теперь включают расширенное отслеживание статусов с отдельными полями для статуса транскрибации и доставки webhook.
Улучшенные данные Webhook
{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "transcription_status": "TRANSCRIBED",
    "webhook_status": "DELIVERED",
    "status": "WEBHOOK_DELIVERED",
    "balance_minutes": 150,
    "callback_url": "https://your-webhook-url.com",
    "callback_id": "исходный-unicode-id",
    "output": {
        "duration": 120.5,
        "language": "ru",
        "list": [
            {
                "text": "Привет мир",
                "start": 0.0,
                "end": 2.1
            }
        ]
    }
}

🔄 Примечания к миграции

✅ Обратная совместимость: Все существующие интеграции продолжают работать без изменений.
📈 Расширенные возможности: Новые поля статуса обеспечивают более детальное отслеживание.
🌐 Готовность к UTF-8: Международные callback ID теперь поддерживаются автоматически.
📋 Рекомендация: Обновите ваши обработчики webhook для использования новых полей transcription_status и webhook_status для лучшего мониторинга.