Документация API

📖 Введение

Voiceponce – сервис, который позволяет загружать отзывы пользователей в виде аудио или текстовых файлов, транскрибировать их и анализировать полученный текст с помощью ИИ.

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

В случае, если отзыв был передан в виде текста, этап транскрибации будет пропущен.

📑 Спецификация API

OpenAPI-спецификация в формате JSON доступна по адресу:

https://api.voiceponce.ru/api/v1/openapi.json

Также для удобства вы можете просмотреть онлайн-предзагруженную спецификацию в одном из двух просмотрщиков по следующим ссылкам:

🚀 Быстрый старт

Выполните аутентификацию, используя предоставленный вам сервисный аккаунт (пара: USERNAME и PASSWORD), чтобы получить токен:
```
curl -X POST "https://api.voiceponce.ru/api/v1/token" \
     -F "username=USERNAME" \
     -F "password=PASSWORD"
```
Токен доступен в поле token в ответе (действителен 24 часа):
```
{
  "detail": "Success",
  "token": "TOKEN",
  "token_type": "bearer"
}
```

Используя полученный токен TOKEN, загрузите аудиофайл FILE с некоторой опциональными метаданными (SUBJECT_TITLE и SUBJECT_URL):

curl -X POST "https://api.voiceponce.ru/api/v1/transcriptions" \
     -H "Authorization: Bearer TOKEN" \
     -F "input=@PATH/TO/FILE" \
     -F "subject_title=SUBJECT_TITLE" \
     -F "subject_url=SUBJECT_URL"

Идентификатор транскрипции доступен в поле id в ответе:

{
  "detail": "Transcription queued",
  "id": "ID"
}

Получите всю доступную информацию о транскрипции:
```
curl -X GET "https://api.voiceponce.ru/api/v1/transcriptions/ID" \
     -H "Authorization: Bearer TOKEN"
```
Статус транскрипции доступен в поле status (если статус не completed, попробуйте еще раз позже, например, через 10 секунд). Результаты представлены в полях ответа, названия которых начинаются с result_:

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

API Voiceponce использует токены доступа для аутентификации пользователей и обеспечения безопасности с ограниченным временем действия (24 часа).

Получение токена

Для получения токена доступа необходимо отправить POST-запрос с данными формы, содержащими username и password, на эндпоинт /api/v1/token.

Для получения токена доступа учетная запись должна быть зарегистрирована в системе и иметь соответствующие права доступа. Убедитесь, что предоставленные учетные данные верны, чтобы избежать ошибок аутентификации.

Использование токена

При обращении к эндпоинтам, требующим авторизацию, передавайте токен в заголовке Authorization в формате Bearer TOKEN, где TOKEN – ваш токен с ограниченным сроком действия.

Срок действия токена

Токен доступа действителен в течение 24 часов. По истечении этого времени необходимо запросить новый токен, чтобы продолжить использование API.

Роли

Для выполнения запросов сервисный аккаунт должен быть зарегистрирован в системе и обладать соответствующими правами доступа. Убедитесь, что предоставленные учетные данные верны, чтобы избежать ошибок аутентификации.

Возможные роли (назначаются администратором Voiceponce при создании сервисного аккаунта):

viewer (предоставляет доступ только для чтения информации)
editor (позволяет создавать и удалять транскрипции)
admin (в настоящее время эквивалентна роли editor)

ℹ️ Метаданные

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

Поддерживаемые поля:

subject_user_id – идентификатор автора отзыва
subject_title – название сущности, о которой идет речь в отзыве
subject_description – описание сущности, о которой идет речь в отзыве
subject_rating – рейтинг, который выставил автор отзыва
subject_max_rating – максимально возможный рейтинг
subject_url – ссылка на сущность
subject_article – артикул/SKU сущности

🚥 Статусы

В результате загрузки файла обработка выполняется не мгновенно. Для отслеживания статуса вы можете выполнять запросы к эндпоинту /api/v1/transcriptions/id/status (только статус и его словесное описание) или /api/v1/transcriptions/id (полная информация о транскрипции) и проверять значение поля status в ответе.

Статусы:

В результате загрузки файла создаётся новая транскрипция со статусом new.
Новые запросы ставятся в очередь на обработку. Как только сервис Voiceponce начинает выполнение транскрибации и анализа, статус меняется на processing.
Для получения результатов транскрибации и анализа следует дождаться смены статуса на completed.
Если в процессе транскрибации возникла ошибка, статус меняется на failed. Строго говоря, статус failed не является терминальным. В ряде случаев сервис может попытаться автоматически исправить возникшую ошибку и обработать транскрипцию заново. При этом максимальный срок, в течение которого сервис совершает попытки повторной обработки, ограничен 24 часами. Транскрипции, которые находятся в статусе failed более 48 часов, повторно не обрабатываются.

Рекомендованный интервал проверки статуса:

Если текущий статус new или processing, то рекомендованный интервал проверки составляет 10 секунд.
Если текущий статус failed, то рекомендованный интервал проверки составляет 10 минут.

📦 Результат

По завершении обработки статус транскрипции приобретает значение completed. Для получения результата вы можете выполнять запросы к эндпоинту /api/v1/transcriptions/id/result (только результат и его словесное описание) или /api/v1/transcriptions/id (полная информация о транскрипции) и обращаться к полям ответа, названия которых начинаются с result_.

result_text (строка) – Полный текст переданного отзыва.
result_revised_text (строка) – Отредактированный текст результата транскрипции, пригодный для публикации.
result_tldr (строка) – Краткое резюме отзыва в 1-2 предложениях.
result_name (строка) – Название объекта отзыва (например, "доставка" или "Кофе Lavazza 1кг").
result_category (строка) – Категория объекта, например, "продукт", "услуга", "приложение".
result_type_of_feedback (строка) – Тип отзыва (например, жалоба, похвала, предложение).
result_problem (строка) – Основная проблема, упомянутая в отзыве, если таковая имеется.
result_evidence_level (строка, список значений ограничен) – Уровень доказательности отзыва:
- low (низкий)
- medium (средний)
- high (высокий)
result_temporal_aspect (строка) – Указанный временной аспект или продолжительность использования.
result_keywords (массив строк) – Список ключевых слов или фраз, отражающих основные темы отзыва.
result_tone (строка, список значений ограничен) – Общий эмоциональный тон отзыва:
- positive (положительный)
- neutral (нейтральный)
- negative (негативный)
result_emotions (массив строк, список значений ограничен) – Список конкретных эмоций, таких как:
- delight (восторг)
- joy (радость)
- trust (доверие)
- gratitude (благодарность)
- satisfaction (удовлетворение)
- indifference (безразличие)
- surprise (удивление)
- uncertainty (неопределённость)
- concern (беспокойство)
- disappointment (разочарование)
- irritation (раздражение)
- anger (злость)
result_call_to_action (строка) – Явный запрос пользователя или предполагаемое ожидаемое действие от компании.

⚙️ Эндпоинты

Получение токена доступа

Эндпоинт: /api/v1/token
Метод: POST
Параметры формы:
- username - имя сервисного аккаунта
- password - пароль/секрет сервисного аккаунта
Ответ: JSON с токеном

В случае успешного выполнения сервис возвращает JSON со статусом 200. Запрашиваемый токен доступен по ключу token.

Пример запроса:

curl -X POST "https://api.voiceponce.ru/api/v1/token" -F "username=USERNAME" -F "password=PASSWORD"

Пример ответа:

{
  "detail": "Success",
  "token": "TOKEN",
  "token_type": "bearer"
}

Версия

Эндпоинт: /api/v1/version
Метод: GET
Ответ: Текстовая строка с версией

Этот запрос не требует авторизации и может быть использован, например, для проверки доступности сервиса Voiceponce. В случае успешного выполнения сервис возвращает строку с версией со статусом 200.

Пример запроса:

curl "https://api.voiceponce.ru/api/v1/version"

Пример ответа:

v0.0.1

Загрузка отзыва

Эндпоинт: /api/v1/transcriptions
Метод: POST
Аутентификация: Заголовок Authorization со значением Bearer TOKEN
Требуемая роль: editor
Тип контента: multipart/form-data или application/json
Параметры формы (в случае контента типа multipart/form-data):
- Обязательные:
  - input – аудио или текстовый файл
- Опциональные:
  - language – язык отзыва, например, ru или en (если язык не указан, сервис будет считать, что язык отзыва – русский)
  - subject_user_id – идентификатор автора отзыва
  - subject_title – название сущности, о которой идет речь в отзыве
  - subject_description – описание сущности, о которой идет речь в отзыве
  - subject_rating – рейтинг, который выставил автор отзыва
  - subject_max_rating – максимально возможный рейтинг
  - subject_url – ссылка на сущность
  - subject_article – артикул/SKU сущности
Поля JSON (в случае контента типа application/json):
- Обязательные:
  - input – текст отзыва или файл, закодированный в base64-строку (аудио или текстовый файл)
  - input_extension – расширение файла (имеет смысл и является обязательным только в случае передачи аудиофайла в поле input), например: mp3, m4a и др.
- Опциональные:
  - language – язык отзыва, например, ru или en (если язык не указан, сервис будет считать, что язык отзыва – русский)
  - subject_user_id – идентификатор автора отзыва
  - subject_title – название сущности, о которой идет речь в отзыве
  - subject_description – описание сущности, о которой идет речь в отзыве
  - subject_rating – рейтинг, который выставил автор отзыва
  - subject_max_rating – максимально возможный рейтинг
  - subject_url – ссылка на сущность
  - subject_article – артикул/SKU сущности
Ответ: JSON с ID транскрипции

Выполнение данного запроса инициирует асинхронный процесс транскрибирования и анализа отзыва. Для выполнения этого запроса сервисный аккаунт, от имени которого выполняется запрос, должен иметь назначенную роль не ниже уровня editor.

Существует два альтернативных способа передачи данных:

В виде формы (multipart/form-data). В этом случае единственным обязательным параметром формы является input (аудио или текстовый файл).
В виде JSON (application/json). В этом случае обязательным полем является input (текст отзыва в виде строки или файл, закодированный в base64-строку; при этом закодированный файл может быть как текстовым, так и аудио). Также, если в качестве input был передан аудиофайл, необходимо передать еще одно поле input_extension с расширением аудиофайла, содержимое которого было передано в поле input.

Если был передан аудиофайл, он будет транскрибирован перед анализом. Если же отзыв передан в виде текста в том или ином виде, его содержимое будет использовано как текст отзыва.

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

В случае успешного выполнения сервис возвращает JSON со статусом 200. Идентификатор транскрипции доступен по ключу id. Запомните идентификатор, чтобы иметь возможность получить информацию о транскрипции в будущем.

Пример запроса с передачей файла через форму (multipart/form-data):

curl -X POST "https://api.voiceponce.ru/api/v1/transcriptions" \
     -H "Authorization: Bearer TOKEN" \
     -F "input=@PATH/TO/FILE" \
     -F "subject_user_id=SUBJECT_USER_ID" \
     -F "subject_title=SUBJECT_TITLE" \
     -F "subject_description=SUBJECT_DESCRIPTION" \
     -F "subject_rating=SUBJECT_RATING" \
     -F "subject_max_rating=SUBJECT_MAX_RATING" \
     -F "subject_url=SUBJECT_URL" \
     -F "subject_article=SUBJECT_ARTICLE"

Пример запроса с передачей отзыва в виде текста через JSON (application/json):

curl -s -X POST "https://api.voiceponce.ru/api/v1/transcriptions" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"input": "Отличный товар!"}'

Пример запроса с передачей текстового файла через JSON (application/json):

curl -s -X POST "https://api.voiceponce.ru/api/v1/transcriptions" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"input": "0J7RgtC70LjRh9C90YvQuSDRgtC+0LLQsNGAIQ=="}'

Пример запроса с передачей аудио файла через JSON (application/json):

filepath="PATH/TO/FILE"
extension="${filepath##*.}"
content=$(base64 -i ${filepath} | tr -d '\n')

data=$(cat <<eof
{
    "input": "${content}",
    "input_extension": "${extension}"
}
eof)

echo ${data} | curl -s -X POST "https://api.voiceponce.ru/api/v1/transcriptions" \
     -H "Authorization: Bearer TOKEN" \
     -H "Content-Type: application/json" \
     -d @-

Пример ответа:

{
  "detail": "Transcription queued",
  "id": "ID"
}

Получение статуса транскрипции

Эндпоинт: /api/v1/transcriptions/{id}/status
Метод: GET
Аутентификация: Заголовок Authorization со значением Bearer TOKEN
Параметры пути: id (идентификатор транскрипции)
Ответ: JSON со статусом транскрипции (new, processing, completed, failed)

В результате загрузки файла создаётся новая трансрипция со статусом new. Новые запросы ставятся в очередь на обработку. Как только сервис Voiceponce начинает выполнения транскрибации и анализа, статус меняется на processing. Для получения результатов транскрибации и анализа следует дождаться смены статуса на completed. Если в процессе транскрибации возникла ошибка, то статус меняется на failed.

Рекомендованный интервал проверки статуса – 10 секунд.

Пример запроса:

curl -X GET "https://api.voiceponce.ru/api/v1/transcriptions/ID/status" \
     -H "Authorization: Bearer TOKEN"

Пример ответа:

{
  "detail": "Transcription completed successfully",
  "status": "completed"
}

Получение результата

Эндпоинт: /api/v1/transcriptions/{id}/result
Метод: GET
Аутентификация: Заголовок Authorization со значением Bearer TOKEN
Параметры пути: id (идентификатор транскрипции)
Ответ: JSON с результатом транскрипции

Пример запроса:

curl -X GET "https://api.voiceponce.ru/api/v1/transcriptions/ID/result" \
     -H "Authorization: Bearer TOKEN"

Пример ответа:

{
  "detail": "Transcription result provided",
  "result_text": "Вещь классная. У меня около дома настольная лампа, а оценя такой апгрейд за небольшие деньги. Полностью доволен, светит достаточно ярко.",
  "result_revised_text": "Вещь классная. У меня около дома настольная лампа, а оценя такой апгрейд за небольшие деньги. Полностью доволен, светит достаточно ярко.",
  "result_tldr": "Этот отзыв положительный: пользователь испытывает удовлетворение из-за удачного апгрейда настольной лампы за небольшие деньги.",
  "result_name": "настольная лампа",
  "result_category": "product",
  "result_type_of_feedback": "похвала за апгрейд",
  "result_problem": "",
  "result_evidence_level": "medium",
  "result_temporal_aspect": "",
  "result_keywords": [
    "настольная лампа",
    "апгрейд",
    "небольшие деньги",
    "доволен",
    "яркий свет"
  ],
  "result_tone": "positive",
  "result_emotions": [
    "delight",
    "joy"
  ],
  "result_call_to_action": ""
}

Получение детальной информации о транскрипции

Эндпоинт: /api/v1/transcriptions/{id}
Метод: GET
Аутентификация: Заголовок Authorization со значением Bearer TOKEN
Параметры пути: id (идентификатор транскрипции)
Ответ: JSON с полной информацией о транскрипции

Пример запроса:

curl -X GET "https://api.voiceponce.ru/api/v1/transcriptions/ID" \
     -H "Authorization: Bearer TOKEN"

Пример ответа:

{
  "detail": "Transcription completed successfully",
  "id": "ID",
  "status": "completed",
  "result_text": "Вещь классная. У меня около дома настольная лампа, а оценя такой апгрейд за небольшие деньги. Полностью доволен, светит достаточно ярко.",
  "result_revised_text": "Вещь классная. У меня около дома настольная лампа, а оценя такой апгрейд за небольшие деньги. Полностью доволен, светит достаточно ярко.",
  "result_tldr": "Этот отзыв положительный: пользователь испытывает удовлетворение из-за удачного апгрейда настольной лампы за небольшие деньги.",
  "result_name": "настольная лампа",
  "result_category": "product",
  "result_type_of_feedback": "похвала за апгрейд",
  "result_problem": "",
  "result_evidence_level": "medium",
  "result_temporal_aspect": "",
  "result_keywords": [
    "настольная лампа",
    "апгрейд",
    "небольшие деньги",
    "доволен",
    "яркий свет"
  ],
  "result_tone": "positive",
  "result_emotions": [
    "satisfaction",
    "joy"
  ],
  "result_call_to_action": "",
  "project_id": "b6825c55-ff76-43f4-bba1-62ccc2963186",
  "language": null,
  "subject_user_id": "12345",
  "subject_title": "Лампа настольная Light Fox Pro",
  "subject_description": null,
  "subject_rating": 4.0,
  "subject_max_rating": 5.0,
  "subject_url": null,
  "subject_article": "12345678",
  "note": null
}

Удаление транскрипции

Эндпоинт: /api/v1/transcriptions/{id}
Метод: DELETE
Аутентификация: Заголовок Authorization со значением Bearer TOKEN
Требуемая роль: editor
Параметры пути: id (идентификатор транскрипции)
Ответ: JSON с сообщением об успешном удалении

Для выполнения этого запроса сервисный аккаунт, от имени которого выполняется запрос, должен иметь назначенную роль как минимум уровня editor.

Пример запроса:

curl -X DELETE "https://api.voiceponce.ru/api/v1/transcriptions/ID" \
     -H "Authorization: Bearer TOKEN"

Пример ответа:

{
  "detail": "Transcription deleted."
}

🚫 Ошибки

Ошибка аутентификации `401`

Ошибка аутентификации 401 (Unauthorized) означает, что учетные данные или токен неверны.

Примеры ответов:

{
  "detail": "Invalid authentication credentials"
}

{
  "detail": "Authentication token has expired"
}

Ошибка доступа `403`

Ошибка 403 (Forbidden) означает, что у аккаунта, от имени которого была выполнена аутентификация, нет подходящих прав.

Примеры ответов:

{
  "detail": "Only service accounts can get transcriptions"
}

{
  "detail": "Account has no permission to edit the project"
}

Ошибка ресурса `404`

Ошибка 404 (Not found) означает, что запрашиваемый ресурс не найден.

Пример ответа:

{
  "detail": "Transcription not found"
}

Ошибка валидации `422`

Ошибка валидации запроса 422 (Unprocessable entity) возникает, например, если вы не передали все необходимые параметры.

Пример ответа:

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Ошибка `400`

Прочие ошибки имеют статус 400 (Bad request).

Пример ответа:

{
  "detail": "No projects found for the account"
}

Ошибки `5xx`

Ошибки с кодом 5xx (например, 500, 502, 503, 504) означают, что на стороне сервера произошла внутренняя ошибка или временная недоступность сервиса. Такие ошибки, как правило, не связаны с некорректностью запроса клиента, а указывают на проблемы в инфраструктуре или обработке на сервере.

Рекомендации: - При получении ошибки 5xx рекомендуется повторить запрос через некоторое время. - Для минимизации нагрузки на сервер и повышения вероятности успешного выполнения запроса используйте стратегию экспоненциального увеличения интервала между попытками (exponential backoff). Например, увеличивайте задержку между повторными запросами по формуле: 1 секунда, 2 секунды, 4 секунды, 8 секунд и т.д., до достижения разумного лимита попыток.

Документация API

📖 Введение

📑 Спецификация API

🚀 Быстрый старт

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

Получение токена

Использование токена

Срок действия токена

Роли

ℹ️ Метаданные

🚥 Статусы

📦 Результат

⚙️ Эндпоинты

Получение токена доступа

Версия

Загрузка отзыва

Получение статуса транскрипции

Получение результата

Получение детальной информации о транскрипции

Удаление транскрипции

🚫 Ошибки

Ошибка аутентификации 401

Ошибка доступа 403

Ошибка ресурса 404

Ошибка валидации 422

Ошибка 400

Ошибки 5xx

Ошибка аутентификации `401`

Ошибка доступа `403`

Ошибка ресурса `404`

Ошибка валидации `422`

Ошибка `400`

Ошибки `5xx`