Skip to content

AG_audio-archive-back_REST_API_ru.md

Latest commit

 

History

History
475 lines (380 loc) · 23 KB

AG_audio-archive-back_REST_API_ru.md

File metadata and controls

475 lines (380 loc) · 23 KB

Справочник REST API компонента audio-archive-back

   

Общая информация

Аudio-archive-back — это REST API сервис для чтения данных распознавания из медиа-архива. Федеральный Audiogram использует S3 хранилище для хранения данных, включая:

  • Информацию о запросах на асинхронное распознавание речи из аудиофайла, сделанных ранее.
  • Результаты асинхронного распознавания речи.
  • Исходное аудио, которое использовалось для распознавания речи.
  • VAD-метки, которые были определены в исходном аудио.
  • Антиспуфинг метки, которые были определены в исходном аудио.

Результат асинхронного распознавания речи сохраняется в S3 хранилище и затем извлекается из него для последующего использования. Остальные данные, хранящиеся в S3, могут использоваться при отладке, если распознавание речи не дало ожидаемых результатов. Для получения данных из S3 хранилища используется REST API, описываемый в настоящем документе.

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

REST API для доступа в аудиоархив полностью открыт и не требует аутентификации.

Базовый URL-адрес

Текущая версия REST API (v2) располагается по следующему пути:

https://{api_address}/archive/api/v2/

Для обратной совместимости с предыдущей версией указывайте только адрес сервера:

https://{api_address}

Запросы получения данных из аудиоархива

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

Каждый запрос на распознавание речи сохраняется в S3 хранилище, включая сам запрос и его конфигурацию. Прежде чем работать с конкретным запросом необходимо получить список запросов, указав интересующий промежуток дат. Ответ будет содержать ID каждого запроса, которое затем будет использоваться в качестве параметра в остальных REST API запросах. Ответ так же содержит ID трассировки и ID сессии, которые могут быть использованы в соответствующих API-запросах в качестве входных параметров.

Метод и конечная точка

GET {base-URL}/clients/{client_id}/requests

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.

Параметры тела запроса

Параметр Тип данных Обязательность Описание
dateFrom string($date-time) Нет Дата с которой начать поиск запросов.
dateTo string($date-time) Нет Дата, которой закончить поиск.

Ответы

Код 200. Успешный ответ. Содержит список запросов.

Параметр Тип данных Описание
id string ID записи в S3 хранилище.
created_at string($date-time) Дата и время выполнения запроса.
trace_id string ID трассировки.
session_id string ID сессии.
request_id string ID запроса.

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

{
  "data": [
    {
      "id": "string",
      "created_at": "2025-07-09T21:57:28.177Z",
      "trace_id": "string",
      "session_id": "string",
      "request_id": "string"
    }
  ]
}

Код 422. Ошибка валидации. Возникает, если один из входных параметров не прошёл валидацию.

Параметр Тип данных Описание
detail [
{
loc[ ] string Содержит информацию о входном параметре, который явился причиной ошибки.
msg string Описание ошибки.
type string Тип ошибки. Возможные типы ошибок перечислены в конце этой главы в секции Типы ошибок.
}
]

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

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

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

Данный ресурс позволяет получать список запросов по ID сессии, которая была создана в процессе выполнения запроса.

Метод и конечная точка

GET {base-URL}/clients/{client_id}/sessions/{session_id}/requests

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
session_id string Да ID сессии.

Ответы

Код 200. Успешный ответ. Содержит список запросов.

Параметр Тип данных Описание
id string ID записи в S3 хранилище.
created_at string($date-time) Дата и время выполнения запроса.
trace_id string ID трассировки.
session_id string ID сессии.
request_id string ID запроса.

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

{
  "data": [
    {
      "id": "string",
      "created_at": "2025-07-09T21:57:28.177Z",
      "trace_id": "string",
      "session_id": "string",
      "request_id": "string"
    }
  ]
}

Код 422. Ошибка валидации. Возникает, если один из входных параметров не прошёл валидацию. Все ответы об ошибке валидации имеют одинаковую структуру. Смотрите описание первого запроса в этом документе.

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

Метод и конечная точка

GET {base-URL}/clients/{client_id}/traces/{trace_id}/requests

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
trace_id string Да ID трассировки.

Ответы

Код 200. Успешный ответ. Содержит список запросов.

Параметр Тип данных Описание
id string ID записи в S3 хранилище.
created_at string($date-time) Дата и время выполнения запроса.
trace_id string ID трассировки.
session_id string ID сессии.
request_id string ID запроса.

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

{
  "data": [
    {
      "id": "string",
      "created_at": "2025-07-09T21:57:28.177Z",
      "trace_id": "string",
      "session_id": "string",
      "request_id": "string"
    }
  ]
}

Код 422. Ошибка валидации. Возникает, если один из входных параметров не прошёл валидацию.

Загрузить аудио из которого происходило распознавание речи

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

Метод и конечная точка

GET {base-URL}/clients/{client_id}/requests/{request_id}/audio

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
request_id string Да ID запроса.

Ответы

Код 200. Успешный ответ. Возвращает аудио в формате “audio/wav” (media type).

Код 422. Ошибка валидации. Возникает, если один из входных параметров не прошёл валидацию.

Загрузить аудио вместе с конфигурацией запроса

Вместе с исходным аудио в S3 хранилище сохраняется конфигурация, которая использовалась при построении запроса. Данный ресурс позволяет получить аудио вместе с конфигурационными параметрами в формате (media type) “multipart/related”.

Метод и конечная точка

GET {base-URL}/clients/{client_id}/requests/{request_id}/full_request

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
request_id string Да ID запроса.

Ответы

Код 200. Успешный ответ. Возвращает аудио и параметры конфигурации запроса в формате (media type) “multipart/related”.

Параметр Тип данных Описание
audio string($binary) Аудио
audio_headers {} Аудио хедеры.
request_config {} Параметры конфигурации, которые использовались при выполнении запроса.

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

{
  "audio": "string",
  "audio_headers": {},
  "request_config": {}
}

Код 422. Ошибка валидации. Возникает, если один из входных параметров не прошёл валидацию.

Загрузить текст, полученный в результате распознавания речи

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

Метод и конечная точка

GET {base-URL}/clients/{client_id}/requests/{request_id}/transcript

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
request_id string Да ID запроса.

Ответы

Код 200. Успешный ответ. Содержит текст и сопутствующую информацию.

Параметр Тип данных Описание
transcript string Полученный текст.
confidence number Коэффициент достоверности (степень уверенности) распознанных фраз.
words [ Результат распознавания речи с разбивкой по словам.
{
word string Слово.
confidence number Коэффициент достоверности.
start_time { Временная метка конца распознанного слова относительно начала аудиопотока.
nanos integer Наносекунды.
seconds integer Полные секунды.
}
end_time { Временная метка конца распознанного слова относительно начала аудиопотока.
nanons integer Наносекунды.
seconds integer Полные секунды.
}
}
]
start_time { Временная метка начала распознанной фразы относительно начала аудиопотока.
nanons integer Наносекунды.
seconds integer Полные секунды.
}
end_time { Временная метка конца распознанной фразы относительно начала аудиопотока.
nanons integer Наносекунды.
seconds integer Полные секунды.
}

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

{
  "data": [
    {
      "transcript": "string",
      "confidence": 0,
      "words": [
        {
          "word": "string",
          "confidence": 0,
          "start_time": {
            "nanos": 0,
            "seconds": 0
          },
          "end_time": {
            "nanos": 0,
            "seconds": 0
          }
        }
      ],
      "start_time": {
        "nanos": 0,
        "seconds": 0
      },
      "end_time": {
        "nanos": 0,
        "seconds": 0
      }
    }
  ]
}

Код 422. Ошибка валидации. Возникает если один из входных параметров не прошёл валидацию.

Загрузить отметки голосовой активности (VAD)

Во время распознавания речи выполняется и сохраняется в S3 хранилище разметка голосовой активности (VAD). При необходимости разметку можно получить из хранилища.

Метод и конечная точка

GET {base-URL}/clients/{client_id}/requests/{request_id}/voice_activity_marks

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
request_id string Да ID запроса.

Ответы

Код 200. Успешный ответ. Содержит список голосовых отметок.

Параметр Тип данных Описание
[
{
mark_type Enum: VA_MARK_NONE, VA_MARK_BEGIN, VA_MARK_END Тип отметки.
offset_ms integer($int64) Смещение от начала аудиофайла в миллисекундах.
}
]

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

{
  "data": [
    {
      "mark_type": "string",
      "offset_ms": 0
    }
  ]
}

Код 422. Ошибка валидации. Возникает если один из входных параметров не прошёл валидацию.

Загрузить отметки антиспуфинга

Во время распознавания речи выполняется и сохраняется в S3 хранилище разметка антиспуфинга. При необходимости разметку можно получить из хранилища.

Метод и конечная точка

GET {base-URL}/clients/{client_id}/requests/{request_id}/anti_spoofing_marks

Параметры

Параметры строки запроса

Параметр Тип данных Обязательность Описание
client_id string Да Client ID из Keycloak под которым выполнялся запрос.
request_id string Да ID запроса.

Ответы

Код 200. Успешный ответ. Содержит список отметок антиспуфинга.

Параметр Тип данных Описание
[
{
attack_type Enum: LOGICAL, PHYSICAL, ALL_TYPES Тип спуфинг-атаки.
attack_result Enum: ATTACK_DETECTED, GENUINE ATTACK_DETECTED: Зафиксирована спуфинг-атака (бот пытается выдать себя за человека). GENUINE: Голос принадлежит человеку.
confidence number Коэффициент достоверности (степень уверенности) в том, что это спуфинг-атака.
start_time_ms integer Начальная метка временного отрезка, который анализировался на предмет спуфинг-атаки.
end_time_ms integer Конечная метка временного отрезка, который анализировался на предмет спуфинг-атаки.
}
]

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

{
  "data": [
    {
      "attack_type": "string",
      "attack_result": "string",
      "confidence": 0,
      "start_time_ms": 0,
      "end_time_ms": 0
    }
  ]
}

Код: 422. Ошибка валидации. Возникает если один из входных параметров не прошёл валидацию.

Типы ошибок

Один из перечисленных типов ошибок возвращается в параметре type в ответе на каждый из запросов в аудиоархив.

Тип ошибки Описание
type_error.integer Значение не является целым числом.
type_error.string Значение не является строкой.
type_error.float Значение не является числом с плавающей точкой.
type_error.bool Значение не является булевым.
type_error.list Значение не является списком.
type_error.dict Значение не является словарём.
value_error.missing Отсутствует обязательное поле.
value_error.any_str.min_length Строка короче минимально допустимой длины.
value_error.any_str.max_length Строка длиннее максимально допустимой длины.
value_error.number.not_ge Число меньше минимально допустимого (greater or equal).
value_error.number.not_le Число больше максимально допустимого (less or equal).
value_error.enum Значение не входит в перечисление (enum).
value_error.const Значение не совпадает с константой.
value_error.date Неверный формат даты.
value_error.datetime Неверный формат даты и времени.
value_error.url.scheme Неверная схема URL.
value_error.url.host Неверный хост в URL.
value_error.regex Строка не соответствует регулярному выражению.
value_error.list.min_items Список содержит меньше элементов, чем требуется.
value_error.list.max_items Список содержит больше элементов, чем разрешено.
value_error.dict.min_properties Словарь содержит меньше ключей, чем требуется.
value_error.dict.max_properties Словарь содержит больше ключей, чем разрешено.
type_error.none.allowed Значение не может быть None.
type_error.union Значение не подходит ни под один из вариантов union.

Пробы (probes)

Liveness и readiness пробы используются для определения работоспособности и готовности Kubernetes контейнера (сервиса), который предоставляет доступ в S3 хранилище.

Liveness проб

Определяет работоспособность контейнера.

Метод и конечная точка

GET {base-URL}/probes/liveness

Параметры

Параметры отсутствуют.

Ответы

Код 200. Успешный ответ.

Параметр Тип данных Описание
status string Статус, показывающий работоспособен ли контейнер или его надо перезапустить.

Readiness проб

Определяет готовность контейнера.

Метод и конечная точка

GET {base-URL}/probes/readiness

Параметры

Параметры отсутствуют.

Ответы

Код: 200. Успешный ответ.

Параметр Тип данных Описание
status string Статус, показывающий готов ли контейнер принимать трафик или его надо перезапустить.