Media API

Media API — программный интерфейс, который позволяет пользователям управлять аудиофайлами, загруженными в библиотеку приложения: загружать, удалять, скачивать и т.д. Эти аудио можно использовать для проигрывания аудиосообщений абонентам при переадресации входящего вызова, исходящем автодозвоне и callback.

Media API Exolve предлагает следующие методы для управления аудиофайлами:

  • Upload — загружает аудиофайл в Личный кабинет;

  • Synthesize — синтезирует речь согласно заданным параметрам без добавления сфомированного файла в библиотеку приложения;

  • SynthesizeAndSave — синтезирует речь согласно заданным параметрам с последующим добавлением сфомированного файла в библиотеку приложения;

  • GetList — получает информацию обо всех добавленных в библиотеку приложения аудиофайлах, соответствующих заданным параметрам;

  • GetInfo — получает информацию об аудиофайле;

  • Download — скачивает аудиофайл;

  • Update — изменяет атрибуты добавленного в библиотеку приложения аудиофайла;

  • Delete — удаляет аудиофайл из библиотеки приложения.

Решения, где используется Media API

Попробовать бесплатно

Метод Upload

Примените метод Upload для добавления аудиофайла в библиотеку приложения. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Upload

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
file bytes (Base64) аудиофайл (максимальный размер 5MB)
full_name string имя файла
file_type enum FileType тип аудиофайла
file_metadata_synthesis oneof VoiceSettings голосовые настройки синтеза
description string описание к аудиофайлу
resource_id uint64 идентификатор ресурса аудио

Примечание

Загружаемый аудиофайл не должен превышать размер в 5MB и название файла должно быть в формате MP3 или WAV.


Выходные параметры

Параметр Тип Описание
file_id uint64 идентификатор аудиофайла
resource_id uint64 идентификатор ресурса аудиофайла
size uint64 размер аудиофайла в байтах (не более 15 Мб)
duration uint32 длительность аудиофайла в секундах
name string название файла
description string описание к аудиофайлу
extension string расширение aудиофайла (WAV или MP3)
application_uuid string идентификатор приложения, в библиотеку которого добавлен аудиофайл
file_type enum FileType тип аудиофайла
date_upload string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601

FileType

Параметр Тип Описание
201 enum аудиофайл, загруженный из локального хранилища в библиотеку приложения
202 enum аудиофайл с синтезированной речью

Возможные ошибки

Код Статус Пример сообщения Описание
400 Bad Request “error”: “error Save media service: fileName is exist” аудиофайл с таким именем уже существует
400 Bad Request “error”: “proto: (line 3:18): invalid value for enum type: "254"” невалидное значение в поле file
400 Bad Request “error”: “proto: (line 3:18): invalid value for enum type: "qwe"” невалидное значение в поле file
400 Bad Request “error”: “proto: (line 3:18): invalid value for enum type: ""” не задано значение поля file
400 Bad Request “error”: “proto: syntax error (line 3:18): unexpected token ,” не задано значение поля file
400 Bad Request “error”: “proto: syntax error (line 2:13): unexpected token ,” отсутствует значение поля file
400 Bad Request “error”: “invalid UploadRequest.File: value length must be at least 1 bytes” отсутствует значение поля file
400 Bad Request “error”: “invalid UploadRequest.FullName: value length must be between 1 and 128 runes, inclusive” отсутствует значение поля full_name
400 Bad Request “error”: “proto: (line 5:1): invalid value for string type: }” отсутствует значение поля full_name
401 Unauthorized “error”: “failed to parse token” не указан / неправильно указан API-ключ приложения
404 Not Found неверный URL запроса

Примеры

Входные параметры:

{
   "file": "SUQzAwAAAAAfdlRZRVIAAAAFAAAAMjAyMVRJVDIAAABHAAAB//4TBDgEQgQwBEAEMAQgADwENQQ7BD4ENAQ4BE8EIABABD4EO",
   "file_type": 201,
   "full_name": "exolve_audio.mp3"
}

Выходные параметры:

{
   "file_id": "1931072746905665536",
   "resource_id": "152817",
   "size": "121087",
   "duration": 5,
   "name": "exolve_audio",
   "extension": "mp3",
   "description": "uploaded audio",
   "application_uuid": "178ec145-6848-4b06-a92a-75f63cb57046",
   "file_type": 201,
   "date_upload": "2023-06-14T16:53:40.459734572Z"
}

Метод GetList

Примените метод GetList для получения информации об аудиофайлах, добавленных в библиотеку приложения. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/GetList

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате.

Параметр Тип Описание
resource_id uint64 идентификатор ресурса аудиофайла
name string имя файла
application_uuid string идентификатор приложения, в библиотеку которого загружен аудиофайл
date_from string дата добавления аудиофайла в формате RFC-3339 / ISO-8601, от которой начинать выборку
date_to string дата добавления аудиофайла в формате RFC-3339 / ISO-8601, до которой продолжать выборку
order_list OrderList параметры сортировки выходных данных
limit uint32 лимит выводимых строк
offset uint64 номер строки, с которой начинать выборку (начинается с 0)
file_type enum FileType тип аудиофайла

OrderList

Параметр Тип Описание
order_field enum OrderField тип сортировки выходных данных
order_direction enum OrderDirection порядок сортировки выходных данных

OrderField

Значение Тип Описание
1 enum сортировка по дате добавления аудиофайла
2 enum сортировка по размеру аудиофайла
3 enum сортировка по продолжительности аудиофайла

OrderDirection

Значение Тип Описание
1 enum сортировка в порядке возрастания
2 enum сортировка в порядке убывания

Выходные параметры

Параметр Тип Описание
media_records array GetInfo список с информацией об аудиофайлах

GetInfo

Значение Тип Описание
file_id uint64 идентификатор аудиофайла
resource_id uint64 идентификатор ресурса аудиофайла
size uint64 размер аудиофайла в байтах
duration uint32 длительность аудиофайла в секундах
name string название файла
extension string расширение aудиофайла
description string описание аудиофайла
application_uuid string идентификатор приложения, в библиотеку которого добавлен аудиофайлл
file_type enum FileType тип аудиофайла
date_upload string дата добавления аудиофайла в формате RFC-3339 / ISO-8601
file_type enum FileMetadata метаданные аудиофайла (только для синтезированной речи)

FileType

Параметр Тип Описание
201 enum аудиофайл, загруженный из локального хранилища в библиотеку приложения
202 enum аудиофайл с синтезированной речью

FileMetadata

Параметр Тип Описание
synthesis array VoiceSettings голосовые настройки аудиофайла
text string текст синтезированной речи
VoiceSettings
Параметр Тип Описание
lang array Lang язык синтезируемой речи
voice array Voice голос для озвучивания текста
emotion array Emotion эмоция для озвучивания текста
speed float скорость синтезируемой речи (от 0.1 до 3.0, где 0.1 — самая медленная, 3.0 — самая быстрая, по умолчанию 1.0)
loudness_normalization int32 нормализация громкости (от -145 до 0, где -145 — наименьшее усиление, 0 — наибольшее усиление громкости, по умолчанию -19)

Нормализация применяется, чтобы выровнять громкость синтезированной речи по сравнению с «живой» речью собеседников. LUFS - это единицы измерения громкости. Этот способ измерения объединяет воспринимаемую человеческим слухом громкость и истинную интенсивность аудиосигнала


Lang
Параметр Тип Язык
1 enum русский (по умолчанию)
2 enum английский
3 enum немецкий
4 enum итальянский
5 enum казахский
6 enum узбекский
Voice
Параметр Тип Голос Пол Эмоция Язык
1 enum Алёна (по умолчанию) Ж 1 — нейтральная (по умолчанию), 2 — добрая 1 — русский
2 enum Ермил М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
3 enum Джейн Ж 1 — нейтральная (по умолчанию), 2 — радостная, 3 — раздраженная 1 — русский
4 enum Омаж Ж 1 — нейтральная (по умолчанию), 3 — раздраженная 1 — русский
5 enum Захар М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
6 enum Филипп М 1 — русский
7 enum Мадирус М 1 — русский
8 enum Даша Ж 1 — нейтральная (по умолчанию), 2 — радостная, 4 — дружелюбная 1 — русский
9 enum Юлия Ж 1 — нейтральная (по умолчанию), 5 — строгая 1 — русский
10 enum Лера Ж 1 — нейтральная (по умолчанию), 4 — дружелюбная 1 — русский
11 enum Марина Ж 1 — нейтральная (по умолчанию), 4 — дружелюбная, 6 — шёпот 1 — русский
12 enum Александр М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
13 enum Кирилл М 1 — нейтральная (по умолчанию), 2 — радостная, 5 — строгая 1 — русский
14 enum Антон М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
15 enum Маша Ж 2 — радостная (по умолчанию), 4 — дружелюбная, 5 — строгая 1 — русский
16 enum Лея Ж 3 — немецкий
17 enum Джон М 2 — английский
18 enum Наоми Ж 7 — современный, 8 — классический 4 — итальянский
19 enum Амира Ж 5 — казахский
20 enum Мади Ж 5 — казахский
21 enum Нигора Ж 6 — узбекский
Emotion
Параметр Тип Эмоция
1 enum нейтральная
2 enum радостная
3 enum раздражённая
4 enum дружелюбная
5 enum строгая
6 enum шёпот
7 enum современная
8 enum классическая

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized “error”: “failed to parse token” не указан / неправильно указан API-ключ приложения
404 Not Found некорректно введён URL запроса

Примеры

Входные параметры:

{
    "resource_id": "440009",
    "name": "exolve_audio",
    "application_uuid": "1fd4b297-0a04-4ca7-9ea1-6afde5da074b",
    "date_from": "2023-07-12T01:30:15.01Z",
    "date_to": "2024-12-30T01:30:15.477425Z",
    "order_list": {
        "order_direction": 2,
        "order_field": 1
    },
    "limit": 10,
    "offset": 0
}

Выходные параметры:

{
    "media_records": [
        {
            "file_id": "1992224928825622528",
            "resource_id": "445009",
            "size": "875767",
            "duration": 22,
            "name": "exolve_audio",
            "extension": "mp3",
            "description": "",
            "application_uuid": "1fd4b297-0a04-4ca7-9ea1-6afde5da074b",
            "application_name": "exolve_application",
            "file_type": 201,
            "date_upload": "2024-11-30T10:34:43.107440Z"
             "file_metadata": {
                "synthesis": {
                   "lang": 1,
                   "voice": 1,
                   "emotion": 1,
                   "speed": 1,
                   "loudness_normalization": -19
              },
                 "text": "МТС Exolve — конструктор омниканальных диалогов для бизнеса"
        }
    ]
}

Метод GetInfo

Примените метод GetInfo для получения информации об аудиофайле, добавленном в библиотеку приложения. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/GetInfo

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

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

Параметр Тип Описание
resource_ids Array of uint64 уникальные идентификаторы загруженных аудиофайлов

Выходные параметры

Параметр Тип Описание
media_records array список с информацией об аудиофайлах
file_id uint64 внутренний ID аудиофайла
resource_id uint64 уникальный идентификатор загруженного аудиофайла
size uint64 размер аудиофайла в байтах
duration uint32 длительность аудиофайла в секундах
name string имя файла
extension string расширение aудиофайла
description string описание к аудиофайлу
application_uuid string уникальный идентификатор приложения, к которому загружен аудиофайл
file_type enum FileType тип аудиофайла
date_upload string дата загрузки аудиофайла в формате RFC-3339 / ISO-8601
file_metadata enum FileMetadata метаданные аудиофайла (только для синтезированной речи)

FileType

Параметр Тип Описание
201 enum аудиофайл, загруженный из локального хранилища в библиотеку приложения
202 enum аудиофайл с синтезированной речью

FileMetadata

Параметр Тип Описание
synthesis array VoiceSettings голосовые настройки аудиофайла
text string текст синтезированной речи
VoiceSettings
Параметр Тип Описание
lang array Lang язык синтезируемой речи
voice array Voice голос для озвучивания текста
emotion array Emotion эмоция для озвучивания текста
speed float скорость синтезируемой речи (от 0.1 до 3.0, где 0.1 — самая медленная, 3.0 — самая быстрая, по умолчанию 1.0)
loudness_normalization int32 нормализация громкости (от -145 до 0, где -145 — наименьшее усиление, 0 — наибольшее усиление громкости, по умолчанию -19)

Нормализация применяется, чтобы выровнять громкость синтезированной речи по сравнению с «живой» речью собеседников. LUFS - это единицы измерения громкости. Этот способ измерения объединяет воспринимаемую человеческим слухом громкость и истинную интенсивность аудиосигнала


Lang
Параметр Тип Язык
1 enum русский (по умолчанию)
2 enum английский
3 enum немецкий
4 enum итальянский
5 enum казахский
6 enum узбекский
Voice
Параметр Тип Голос Пол Эмоция Язык
1 enum Алёна (по умолчанию) Ж 1 — нейтральная (по умолчанию), 2 — добрая 1 — русский
2 enum Ермил М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
3 enum Джейн Ж 1 — нейтральная (по умолчанию), 2 — радостная, 3 — раздраженная 1 — русский
4 enum Омаж Ж 1 — нейтральная (по умолчанию), 3 — раздраженная 1 — русский
5 enum Захар М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
6 enum Филипп М 1 — русский
7 enum Мадирус М 1 — русский
8 enum Даша Ж 1 — нейтральная (по умолчанию), 2 — радостная, 4 — дружелюбная 1 — русский
9 enum Юлия Ж 1 — нейтральная (по умолчанию), 5 — строгая 1 — русский
10 enum Лера Ж 1 — нейтральная (по умолчанию), 4 — дружелюбная 1 — русский
11 enum Марина Ж 1 — нейтральная (по умолчанию), 4 — дружелюбная, 6 — шёпот 1 — русский
12 enum Александр М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
13 enum Кирилл М 1 — нейтральная (по умолчанию), 2 — радостная, 5 — строгая 1 — русский
14 enum Антон М 1 — нейтральная (по умолчанию), 2 — радостная 1 — русский
15 enum Маша Ж 2 — радостная (по умолчанию), 4 — дружелюбная, 5 — строгая 1 — русский
16 enum Лея Ж 3 — немецкий
17 enum Джон М 2 — английский
18 enum Наоми Ж 7 — современный, 8 — классический 4 — итальянский
19 enum Амира Ж 5 — казахский
20 enum Мади Ж 5 — казахский
21 enum Нигора Ж 6 — узбекский
Emotion
Параметр Тип Эмоция
1 enum нейтральная
2 enum радостная
3 enum раздражённая
4 enum дружелюбная
5 enum строгая
6 enum шёпот
7 enum современная
8 enum классическая

Возможные ошибки

Код Статус Пример сообщения Описание
400 Bad Request “error”: “proto: (line 3:7): invalid value for uint64 type: ""” не задано значение поля resource_ids
400 Bad Request “error”: “invalid GetInfoRequest.ResourceIds[0]: value must be greater than 0” значение поля resource_ids должно быть больше 0
400 Bad Request “error”: “invalid GetInfoRequest.ResourceIds: value must contain at least 1 item(s)” поле resource_ids должно содержать хотя бы 1 символ
400 Bad Request “error”: “proto: (line 3:7): invalid value for uint64 type: "qwe"” невалидное значение поля resource_ids
401 Unauthorized “error”: “failed to parse token” не указан / неправильно указан API-ключ приложения
404 Not Found некорректно введён URL запроса

Примеры

Входные параметры:

{
   "mediaRecords": [
       {
           "fileId": "1862848703375831040",
           "resourceId": "6266",
           "size": "25747",
           "duration": 1,
           "name": "exolve_audio.mp3",
           "extension": "mp3",
           "description": "uploaded audio",
           "applicationUuid": "0356dc59-deeb-4546-b314-fbc31bd778fc",
           "applicationName": "exolve_application",
           "fileType": 201,
           "dateUpload": "2024-12-08T10:07:52.010849Z"
           "file_metadata": {
               "synthesis": {
                  "lang": 1,
                  "voice": 1,
                  "emotion": 1,
                  "speed": 1,
                  "loudness_normalization": -19
             },
                "text": "МТС Exolve — конструктор омниканальных диалогов для бизнеса"
   }
       }
   ]
}

Выходные параметры:

{
   "media_records": [
       {
           "file_id": "1885716233567862784",
           "resource_id": "138517",
           "size": "26375",
           "duration": 3,
           "name": "Test audio",
           "extension": "mp3",
           "description": "Тестовый аудиофайл",
           "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
           "application_name": "Test",
           "file_type": 201,
           "date_upload": "2023-02-09T13:03:04.996514Z"
       },
       {
           "file_id": "1931072746905665536",
           "resource_id": "152817",
           "size": "121087",
           "duration": 5,
           "name": "test5",
           "extension": "mp3",
           "description": "",
           "application_uuid": "178ec145-6898-4b06-a92a-75f63cb57046",
           "application_name": "Test",
           "file_type": 201,
           "date_upload": "2023-06-14T16:53:40.459735Z"
       }
   ]
}

Метод Download

Примените метод Download для скачивания аудиофайла, добавленного в библиотеку приложения. Для этого выполните POST-запрос с идентификатор ресурса к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Download

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_id uint64 идентификатор ресурса аудиофайла

Выходные параметры

Параметр Тип Описание
file bytes аудиофайл в формате Base64
full_name string название аудиофайла
resource_id uint64 идентификатор ресурса аудиофайла
file_type enum FileType тип аудиофайла

FileType

Параметр Тип Эмоция
201 enum аудиофайл, загруженный из локального хранилища в библиотеку приложения

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized malformed token не указан / неправильно указан API-ключ приложения
500 Internal Server Error Application [ID] does not own resource [661352] файл принадлежит другому приложению

Примеры

Входные параметры:

{
    "resource_id": "6088"
}

Выходные параметры:


{
    "file": "SUQzAwAAAAAfdlRZRVIAAAAFAAAAMjAyMVRJVDIAAABHAAAB//4TB",
    "full_name": "19999tgb.mp3",
    "resource_id": "6088",
    "file_type": 201
}

Метод Update

Примените метод Update для изменения атрибутов аудиофайла, добавленного в библиотеку приложения. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Update

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_id uint64 уникальный идентификатор загруженного аудиофайла
name string новое наименование аудиофайла
description string новое описание к аудиофайлу

Выходные параметры

Пустой JSON с 200 OK статусом

Возможные ошибки

Код Статус Пример сообщения Описание
400 Bad Request “error”: “proto: (line 5:1): invalid value for uint64 type: }” значение поля resource_id пустое (без “”)
400 Bad Request “error”: “invalid UpdateRequest.ResourceId: value must be greater than 0” значение поля resource_id должно быть больше 0
400 Bad Request “error”: “proto: (line 4:20): invalid value for uint64 type: ""” не задано значение поля resource_ids
400 Bad Request “error”: “proto: (line 4:20): invalid value for uint64 type: "qwe"” невалидное значение поля resource_ids
400 Bad Request “error”: “proto: syntax error (line 3:13): unexpected token ,” значение поля name пустое (без “”)
400 Bad Request “proto: syntax error (line 2:19): unexpected token ,” значение поля description пустое (без “”)
401 Unauthorized malformed token не указан / неправильно указан API-ключ приложения
404 Not Found некорректно введён URL запроса

Примеры

Входные параметры:

{
    "resource_id": "152817",
    "name": "Update Test",
    "description": "Тест обновления аудиофайла"  
}

Выходные параметры:

{}

Метод Delete

Примените метод Delete для удаления аудиофайлов, загруженных в библиотеку приложения. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/media/v1/Delete

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
resource_ids Array of uint64 уникальные идентификаторы загруженных аудиофайлов

Выходные параметры

Пустой JSON с 200 OK статусом.

Возможные ошибки

Код Статус Пример сообщения Описание
401 Unauthorized “error”: “failed to parse token” не указан / неправильно указан API-ключ приложения
400 Bad Request “error”: “proto: (line 3:7): invalid value for uint64 type: "qwe"” невалидное значение поля resource_ids
400 Bad Request “error”: “invalid DeleteRequest.ResourceIds[0]: value must be greater than 0” значение поля resource_ids должно быть больше 0
400 Bad Request “error”: “proto: (line 3:7): invalid value for uint64 type: ""” не задано значение в поле resource_ids
400 Bad Request “error”: “invalid GetInfoRequest.ResourceIds: value must contain at least 1 item(s)” значение поля resource_ids должно содержать хотя бы 1 символ
404 Not Found некорректно введен URL запроса

Примеры

Входные параметры:

{
    "resource_ids": [
        "138231"
    ]
}

Выходные параметры:

{}