Методы 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, es, ar, tr, uz). |
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 |
код языка текста (ru, en, auto), содержащегося в значении ключа content. |
|
to_lang |
string |
да |
- |
код языка (ru, en), на который требуется выполнить перевод содержимого content. |
string |
да |
- |
текст, предоставленный для перевода (ru, en) |
|
Пример запроса
'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'} ]Перевод выполняется только в следующих случаях:
-
из русского в английский (если to_lang='en' и значение настройки SKIP_CHECK_EN: true или from_lang="ru")
-
из английского в русский (если to_lang='ru' и значение настройки SKIP_CHECK_RU: true или from_lang="en")
| Для настройки параметра SKIP_CHECK_RU значение всегда должно оставаться false при использовании текущей модели нейросети. В противном случае русский текст может быть ошибочно интерпретирован как английский, что приведет к получению результатов, не соответствующих ожиданиям |
Пример ответа
-
код статуса: 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 с ошибкой валидации контента запроса и сообщением с описанием причины