Методы API в IVA Terra
API для транскрибации мероприятий в режиме онлайн и офлайн
Метод API: POST
URL-адрес для API-запросов:
https://<TERRA_IP>:<API_PORT>/process
где:
<TERRA_IP> — IP-адрес или доменное имя сервера IVA Terra
<API_PORT> — порт для доступа к API (по умолчанию 9001)
Параметры запросов
| Имя | Тип | Обязательность | Значение по умолчанию | Описание |
|---|---|---|---|---|
audiofile |
file |
да |
− |
бинарный контент аудиофрагмента. |
conference_id |
UUID |
да |
− |
идентификатор мероприятия (сессии транскрибации) |
lang1 |
string |
нет |
ru |
код языка (ru, en, de, es, fr, pt, ch, zh, ar, fa, id, in, af, xh, ur, th, te, gu, hi, ne, bn, ml, mr, ta, vi, km). Используется как подсказка для транcкрибации |
offline |
boolean |
нет |
true |
сохранение файла для возможности дальнейшей обработки в офлайн-режиме |
online |
boolean |
нет |
false |
если значение true, то в результате выполнения запроса будет возвращен результат транскрибации |
participant_id |
UUID |
да |
− |
UUID спикера |
participant_name |
string |
да |
− |
имя спикера (отображаемое имя участника). Если не указано, может быть установлено значение UNKNOWN |
post_id |
string |
нет |
− |
идентификатор запроса. В ответе при онлайн-транскрибации будет возвращен список идентификаторов, из которых был собран текст |
timestamp_float |
float |
да |
текущее системное время отправителя в формате с.мкс |
метка системного времени создания аудиофрагмента. |
token |
string |
да |
- |
ключ подключения |
Пример запроса
POST https://10.12.2.199:9001/process?conference_id=trash6bb3f34f-b29a-4d62-ba73-8489777a18de&participant_id=58c277ff-9af4-48c7-8d5f-f13e7304a7e9&participant_name=UNKNOWN&lang1=ru&online=true&offline=true&post_id=e474c68b-e96b-4465-af38-fec989a892d7
-----------------------------217261477111538
Content-Disposition: name="token"
ivcs
-----------------------------217261477111538
Content-Disposition: name="audiofile"; filename="trash6bb3f34f-b29a-4d62-ba73-8489777a18de:a-58c277ff-9af4-48c7-8d5f-f13e7304a7e9_20240628_14_20_15_123456.wav"
Content-Type: application/octet-stream
.....Параметры ответов
Если значение параметра запроса online=false, то система не обрабатывает файл, а только сохраняет для дальнейшей обработки. В этом режиме ответ будет пустой.
Если значение параметра запроса online=true, то в результате выполнения запроса будет возвращен результат транскрибации в формате JSON, представляющий собой массив ArrayOfTextElem, который содержит объекты TextElem.
| Имя атрибута | Значение |
|---|---|
conference_id |
UUID сессии |
duration |
длительность объединенного аудиофрагмента в мс (формат: целое число) |
id |
UUID — уникальный идентификатор ответа, назначается первому аудиофрагменту, входящему в состав объединенного аудиофрагмента |
participant_id |
UUID спикера |
post_ids |
список текстовых идентификаторов запросов (id аудиофрагментов), если они были указаны во входящем запросе |
status |
final — текст окончательный, далее изменяться не будет progress — текст временный, может полностью измениться по мере накопления объединенного аудиофрагмента новыми фрагментами |
text |
текст, распознанный из объединенного аудиофрагмента |
timestamp |
текстовый вид метки времени, которая содержалась в имени отправленного файла |
timestamp_float |
метка времени первого аудиофрагмента из всего объединенного объема аудио, по которому распознан текст (формат: с.мкс) |
Пример ответа
[
{
"timestamp":"2024-06-27T21:21:07.782414", − текстовый вид метки времени, которая содержалась в имени отправленного файла
"timestamp_float":1719512467.782414, − та же метка времени, сконвертированная в дробное число (с.мкс)
"duration":2000, − длительность аудиофрагмента в миллисекундах (целое число)
"conference_id":"trash143dc12d-9fa0-45fe-a449-5df04140ed27", − UUID конференции
"participant_id":"659d1a02-1ba2-4e2f-88aa-48bac9481a0a", − UUID спикера
"text":" Всем привет.", − транскрибированный текст
"id":"0310a61b-f7f2-4337-806f-5421b5b69ed1", − сгенерированный уникальный идентификатор, принадлежащий аудиофрагменту, с которого начинается весь распознанный текст
"post_ids":["7bab8ff2-4f31-4f65-b3ca-0ddd1d17284a"], − список идентификаторов посылок аудиофрагментов, если они были не пустые
"status":"progress" − флаг статуса обработки, «progress» -- не конечный результат, будет дополнен и может быть полностью изменен
}
]В случае завершения одной накопительной комбинации и начала следующей комбинации, список содержит два TextElem:
[
{
"timestamp":"2024-06-27T21:21:07.782414",
"timestamp_float":1719512467.782414,
"duration":30000,
"conference_id":"trash143dc12d-9fa0-45fe-a449-5df04140ed27",
"participant_id":"659d1a02-1ba2-4e2f-88aa-48bac9481a0a",
"text":" Всем привет. Давайте все камеры включим.",
"id":"0310a61b-f7f2-4337-806f-5421b5b69ed1",
"post_ids":
[ # − идентификаторы посылок, из которых был собран аудиофрагмент, транскрибированный в текст
"7bab8ff2-4f31-4f65-b3ca-0ddd1d17284a",
"f8cedb98-200f-4076-8d53-85275e1e935b",
"3a9d9d90-4104-4d80-911f-49dfcfebda2b",
"45836bc1-ce03-465f-885f-9840a76306e6",
"6f22ae04-eed3-4ef6-94c2-a0a4e03f7490",
"6b58f7ac-e776-48d9-b06f-260a025480ce",
"9b94bfc5-2db5-433e-9380-20056852c0ff",
"3834b8cc-2031-4376-a981-c4317842b641",
"d715dd6b-2fab-43c2-9136-7ea2b238315f",
"baa4e4ad-9cfe-48d9-ab01-c4b6f60a7c61",
"4aae99fd-7162-49db-8946-78429232c790",
"a485f89f-cc19-4bb4-be90-ed348dc378a1",
"44aa372c-52a3-4eb9-9249-ce2b77b115c7",
"d1c42456-a694-4b0b-8a53-50aefa205aae",
"55b6d943-c4ac-4008-a6f4-39df4b4e2300"
],
"status":"final"
},
{
"timestamp":"2024-06-27T21:21:37.782414",
"timestamp_float":1719512497.782414,
"duration":2000,
"conference_id":"trash143dc12d-9fa0-45fe-a449-5df04140ed27",
"participant_id":"659d1a02-1ba2-4e2f-88aa-48bac9481a0a",
"text":" Мы подготовили презентацию",
"id":"ffc98483-6cef-4820-9fd3-f1a46e9b6480",
"post_ids":["a2ef5a04-da0f-4382-8c32-2584a4cb629b"],
"status":"progress"
}
]API для транскрибации ранее загруженных аудиофрагментов
API IVA Terra предоставляет функциональность для офлайн-подготовки протоколов по загруженным материалам одного мероприятия:
-
для запуска транскрибации нужно вызвать соответствующие методы API с параметром offline, который должен отсутствовать или быть установлен в true. Это инициирует обработку загруженных материалов конференции в офлайн-режиме
-
после завершения транскрибации выполнить запрос:
-
метод API: GET
-
URL-адрес для API-запросов:
https://<TERRA_IP>:<API_PORT>/minutes/{conference_id}?token=<auth_token>где:
<TERRA_IP> — IP-адрес или доменное имя сервера IVA Terra
<API_PORT> — порт для доступа к API (по умолчанию 9001)
{conference_id} — идентификатор мероприятия
token — токен аутентификации для доступа к API
-
Возможные ответы API:
-
если файлы конференции не загружены предварительно:
-
код статуса: 404
-
ответ в формате JSON:
{"detail":"Conference minutes status file not found"}
-
-
если окончательная транскрибация еще не запущена:
-
запрос ставится в очередь на обработку
-
ответ в формате JSON:
{ "status": "queueplacing", "message_en": "Compiling task of minutes has been placed to the Queue", "message_ru": "Задача формирования протокола поставлена в очередь" }
-
-
если транскрибация находится в процессе выполнения, то ответ в формате JSON:
{ "status": "running", "message_en": "Task of compiling of minutes is still under way", "message_ru": "Идет процесс формирования протокола", "timestamp" : float_метка_времени_постановки_в_очередь_на_транскрибацию } -
если транскрибация завершена, возвращается XML-контент, содержащий протокол конференции. В протоколе представлены временные метки, указывающие на момент произнесения фраз, а также указаны спикеры, произносившие каждую фразу
API для перевода текста
Метод API: POST
URL-адрес для API-запросов:
https://<TERRA_IP>:<API_PORT>/translate_to_any
где:
<TERRA_IP> — IP-адрес или доменное имя сервера IVA Terra
<API_PORT> — порт для доступа к API (по умолчанию 9001)
Параметры запросов
| Имя | Тип | Обязательность | Значение по умолчанию | Описание |
|---|---|---|---|---|
token |
string |
да |
ivcs |
ключ доступа для подключения |
payload |
list |
да |
− |
список словарей, представляющих посылки для перевода. |
Разметка ключей словаря |
||||
string |
да |
auto |
код языка текста, содержащегося в значении ключа content. |
|
to_lang |
string |
да |
- |
код языка, на который требуется выполнить перевод содержимого content. |
string |
да |
- |
текст, предоставленный для перевода |
|
Пример запроса
'payload': [ {'from_lang': 'auto', 'to_lang': 'en', 'content': 'первое предложение'}, {'from_lang': 'auto', 'to_lang': 'ru', 'content': 'last sentence'}, {'from_lang': 'auto', 'to_lang': 'unknown', 'content': 'last sentence'} ]Пример ответа
-
код статуса: 200
-
ответ в формате JSON:
'payload': [ {'from_lang': 'ru', 'to_lang': 'en', 'content': 'первое предложение', 'status': 'processed'}, {'from_lang': 'en', 'to_lang': 'ru', 'content': 'last sentence', 'status': 'processed'}, {'from_lang': 'en', 'to_lang': 'unknown', 'content': 'last sentence', 'status': 'not_processed'} ]где:
-
processed — индикатор успешного перевода текста, готового к использованию
-
not_processed — индикатор возврата исходного текста без перевода из-за невозможности обработки
-
Возможные ответы API
-
если в настройках переменных окружения отключено использование переводчика (USE_TRANSLATOR: false) или указан пустой адрес размещения сервиса переводов (TRANSLATOR_URL):
-
код статуса: 404
-
ответ в формате JSON:
"TRANSLATOR DISABLED OR URL IS NOT CONFIGURED"
-
-
если структура запроса не соответствует ожидаемому формату, включая отсутствие обязательных параметров в запросе payload (from_lang, to_lang, content), то клиенту возвращается статус код 400 с ошибкой валидации контента запроса и сообщением с описанием причины