Виртуальный диктор
Описание
В этом разделе описаны методы асинхронного HTTP API для создания видео с виртуальным диктором, озвучивающим ваш текст на основе заданной вами конфигурации.
Перед началом использования API необходимо получить авторизационный токен, используемый в заголовке CDN-AUTH-TOKEN. Подробнее о времени жизни токена и способе его получения можно найти на странице Авторизация.
Ниже приведено описание методов API с примерами запросов для управления созданием видео.
Ограничения
Внимание!
- Установлено ограничение на количество обращений к API:
- не больше 10 обращений в минуту для запросов генерации видео (POST).
| Характеристика | Ограничение |
|---|---|
| Максимальная длительность видеоролика | 3 минуты |
| Максимальный объем текста | 3000 символов |
| Время хранения сгенерированных видеофайлов с момента создания | 30 дней |
| Максимальное количество запросов в месяц | 1500 |
| Максимальная длина имени видео | 35 символов |
Методы API
Получить список доступных конфигураций
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/configurations
- Тип запроса: GET
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 200 | Список моделей и фоновых видео доступных аккаунту | JSON | Успешное выполнение запроса |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | None | None | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
curl -H cdn-auth-token:${CDN_TOKEN} \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/configurations
Пример успешного ответа
{
"status": "ok",
"voices": {
"Alena": {
"language": "ru-RU",
"gender": "female",
"name": "alena",
"provider": "Yandex",
"emotions": [
"neutral",
"good"
]
},
"Sara": {
"language": "en-EN",
"gender": "female",
"name": "en-US-SaraNeural",
"provider": "Microsoft"
},
"Mia": {
"language": "en-EN",
"gender": "female",
"name": "en-GB-MiaNeural",
"provider": "Microsoft"
}
},
"models": {
"Natalia": {
"1.0.0": {
"style": "suitjacket",
"gender": "female",
"voices": [
"Alena"
],
"shots": {
"waist": {
"size": "HD"
}
}
},
"4.0.0": {
"style": "dressshirt",
"gender": "female",
"voices": [
"Alena",
"Mia",
"Sara"
],
"shots": {
"waist": {
"size": "HD"
}
}
}
}
},
"backgrounds": {
"background_1": {
"sizes": [
"HD"
]
},
"globe": {
"sizes": [
"HD"
]
}
},
"quota": {
"limit": 560.0,
"left": 544.0
},
"watermark": false
}
Пример неуспешного ответа
{"status": "ERROR", "message": "invalid account"}
Создать задачу на генерацию видео
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/generate
- Тип запроса: POST
- Заголовки: CDN-AUTH-TOKEN
- Тело запроса: JSON с текстом и конфигурацией модели
- Тип данных ответа: JSON Object
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 202 | status: type string, id: type string | JSON | Задача поставлена в очередь и ей присвоен идентификатор |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | None | None | Не найдено |
| 422 | Названия некорректных параметров | JSON | Некорректные данные в запросе |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TEXT=$(cat <<-END
{
"script": "Текст для диктора.",
"actor": {
"name": "Natalia",
"version": "1.0.0",
"style": "suitjacket",
"shot": "waist",
"size": "HD"
},
"voice": "Alena",
"emotion" : "good",
"background": "green_screen",
"video_name": "Awesome Video!"
}
END
)
curl -X POST \
-H cdn-auth-token:${CDN_TOKEN} \
-H "Content-Type: application/json" \
-d "${TEXT}" \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/generate
Пример успешного ответа
{
"status": "ok",
"id": "90d70829-134f-4957-9c13-c8bf67c1678e"
}
Пример неуспешного ответа
{"status": "ERROR", "message": "invalid account"}
Узнать статус задачи
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/status/<task_id>
- Тип запроса: GET
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 200 | status: type string, task: type JSON | JSON | Успешное выполнение запроса |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | None | None | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Описание формата возвращаемого параметра task:
| Имя параметра | Описание |
|---|---|
| id | Идентификатор задачи |
| attempts | Количество использованных попыток при выполнении задачи |
| status | Статус задачи: in_queue, processing, processed, canceled |
| message | Дополнительное сообщение о статусе задачи |
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TASK_ID=427c9566-2120-4b85-b168-bz4094667b99
curl -H cdn-auth-token:${CDN_TOKEN} \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/status/${TASK_ID}
Пример успешного ответа
{
"status": "ok",
"task": {
"id": "3e10edaf-41c3-4210-b92f-5d68b269c20f",
"attempts": 1,
"status": "CANCELED",
"message": "canceled by a user request"
}
}
Пример неуспешного ответа
{"status": "ERROR", "message": "invalid account"}
Отменить задачу
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/cancel/<task_id>
- Тип запроса: DELETE
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 204 | status: type string, message, type string | JSON | Задача отменена |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | None | None | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TASK_ID=427c9566-2120-4b85-b168-bz4094667b99
curl -X DELETE \
-H cdn-auth-token:${CDN_TOKEN} \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/cancel/${TASK_ID}
Пример успешного ответа
{
"status": "ok"
}
Пример неуспешного ответа
{"status": "ERROR", "message": "wrong task status: CANCELED"}
Получить ссылку на сгенерированное видео
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/video/<task_id>
- Тип запроса: GET
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 200 | status: type string, url: type string | JSON | Успешное выполнение запроса |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | None | None | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Важно
Скачать видео по ссылке можно только с того же IP-адреса, с которого отправлялся запрос. Время действия ссылки - 6 часов.
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TASK_ID=427c9566-2120-4b85-b168-bz4094667b99
curl -H cdn-auth-token:${CDN_TOKEN} \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/video/${TASK_ID}
Пример успешного ответа
{
"status": "ok",
"url": "https://thaas-video.cdnvideo.ru/testaccount/087c70cc-2d1a-4214-9ef1-54d38f2ecbe0.mp4?md5=snYRj_m8EfMmSTTWArIBKQ&e=1637777947"
}
Пример неуспешного ответа
{"status": "ERROR", "message": "invalid account"}
Получить список сгенерированных видео
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/tasks
- Тип запроса: GET
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
Описание параметров запроса:
| Имя параметра | Описание | Обязательный |
|---|---|---|
| start | Дата от которой производится расчет (включительно). Передается в виде год-месяц-деньTчасы:минуты:секунды+часовойПояс, где секунды должны быть равны 00. Указывается в UTC. Пример, 2020-02-11T12:30:00+00 | Нет |
| end | Дата до которой производится расчет (не включительно). Передается в виде год-месяц-деньTчасы:минуты:секунды+ЧасовойПояс, где секунды должны быть равны 00. Указывается в UTC. Пример, 2020-02-11T12:30:00+00 | Нет |
| offset | Смещение результата | Нет |
| limit | Ограничение результата | Нет |
| sort | Объект и способ сортировки. Параметр sort имеет вид: [+-]{field} (например, сортировка по убыванию длительности -duration) | Нет |
| fields | Дополнительные поля, значения которых нужно вернуть (background, shot, script, voice_name, actor_name, model_version, video_name, emotion, orientation, crop, shift, scale, circle) | Нет |
| id | Идентификатор задачи | Нет |
Возможные коды ответа:
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 200 | Список сгенерированных видео, отсортированный по дате приема задачи в сервис | JSON | Успешное выполнение запроса |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | None | None | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Описание параметров ответа:
| Имя параметра | Описание |
|---|---|
| id | Идентификатор задачи |
| video_url | Ссылка на сгенерированное видео |
| resolution | Разрешение видео |
| duration | Длительность видео в секундах |
| date | Дата приема задачи в сервис в UTC |
| background | Задний фон на видео |
| shot | План камеры на видео |
| script | Текст, который диктор читает на видео |
| voice_name | Голос диктора на видео |
| actor_name | Имя диктора на видео |
| model_version | Версия модели, использованной для генерации |
| video_name | Имя видео |
| emotion | Название эмоции голоса на видео |
| orientation | Ориентация итогового видео |
| crop | Коэффициент обрезки диктора снизу |
| scale | Коэффициент уменьшения размера актера на видео ` |
| shift | Коэффициент сдвига актера относительно центра видео |
| circle | JSON объект, содержащий все поля, переданные в одноимённом параметре POST /generate (location, background_color, border_color), значения будут None, если параметр был запрошен для видео без диктора в кружке |
Важно
Скачать видео по ссылке можно только с того же IP-адреса, с которого отправлялся запрос. Время действия ссылки - 6 часов.
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
curl -H cdn-auth-token:${CDN_TOKEN} \
"https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/tasks?start=2022-06-12T01:42:16Z&end=2022-06-16T10:22:16Z&limit=2&offset=1&fields=shot,background&sort=-duration"
Пример успешного ответа
[
{
"id": "5a22c605-1495-414f-9266-fa780f9a1c3f",
"video_url": "https://thaas-video.cdnvideo.ru/testaccount/5a22c605-1495-414f-9266-fa780f9a1c3f.mp4?md5=xo5bMsGiYrjiV5apPkjUrQ&e=1655409389",
"duration": 30.844976480165343,
"resolution": "SD",
"date": "2022-06-15T21:32:53Z",
"shot": "waist",
"background": "globe"
},
{
"id": "c34d1b6c-d993-446f-8e44-e5aadfabe98e",
"video_url": "https://thaas-video.cdnvideo.ru/testaccount/c34d1b6c-d993-446f-8e44-e5aadfabe98e.mp4?md5=yves38D4RgI2rPv-7rB2uA&e=1655409389",
"duration": 29.270747503730167,
"resolution": "HD",
"date": "2022-06-13T11:17:32Z",
"shot": "waist",
"background": "globe"
}
]
Пример неуспешного ответа
{"status": "ERROR", "message": "invalid account"}
Изменить свойства видео
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/video/<task_id>
- Тип запроса: PATCH
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
Описание параметров запроса:
| Имя параметра | Описание | Обязательный |
|---|---|---|
| video_name | Новое имя видео, не длинее 35 символов | Нет |
Возможные коды ответа:
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 200 | status: type string, message, type string | JSON | Видео переименовано |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | status: type string, message, type string | JSON | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TASK_ID=427c9566-2120-4b85-b168-bz4094667b99
export TEXT=$(cat <<-END
{
"video_name": "New name"
}
END
)
curl -X PATCH \
-H cdn-auth-token:${CDN_TOKEN} \
-H "Content-Type: application/json" \
-d "${TEXT}" \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/video/${TASK_ID}
Пример успешного ответа
{"status": "ok", "message": "success"}
Пример неуспешного ответа
{"status": "ERROR", "message": "no such video"}
Удалить видео
URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/video/<task_id>
- Тип запроса: DELETE
- Заголовки: CDN-AUTH-TOKEN
- Тип данных ответа: JSON Object
| Код ответа | Данные ответа | Формат ответа | Описание |
|---|---|---|---|
| 200 | status: type string, message, type string | JSON | Видео удалено |
| 400 | status: type string, message, type string | JSON | Некорректный запрос |
| 403 | status: type string, message, type string | JSON | Запрещено |
| 404 | status: type string, message, type string | JSON | Не найдено |
| 500 | None | None | Внутренняя ошибка сервера |
| 503 | None | None | Сервис недоступен |
Пример запроса
export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TASK_ID=427c9566-2120-4b85-b168-bz4094667b99
curl -X DELETE \
-H cdn-auth-token:${CDN_TOKEN} \
https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/video/${TASK_ID}
Пример успешного ответа
{"status": "ok", "message": "success"}
Пример неуспешного ответа
{"status": "ERROR", "message": "no such video"}
Конфигурация модели
Для постановки задачи в очередь необходимо отправить запрос с конфигурацией модели в формате JSON.
Параметры доступных моделей можно узнать, отправив запрос на /configurations
Описание конфигурации
Ниже приведено описание параметров конфигурации.
| Имя параметра | Тип | Обязателен | Описание |
|---|---|---|---|
| script | string | True | Текст, который будет озвучен диктором, или текст, размеченный SSML-тегами в соответствии со спецификацией провайдера голоса. С помощью SSML разметки можно вставлять паузы, изменять произношение, ставить ударения и др. Например, для текущего голоса Alena используйте разметку от компании Yandex, следуя официальной документации |
| actor | JSON | True | Параметры модели диктора |
| voice | string | True | Название голоса диктора |
| background | string | False | Название фона. Размер фона (size) должен соответствовать размеру кадра модели (size в shot). Для выбора фона с хромакеем используйте значение по умолчанию green_screen |
| emotion | string | False | Название эмоции голоса на видео. Необязательный параметр. По-умолчанию используется нейтральная эмоциональная окраска голоса. |
| video_name | string | False | Название генерируемого видео |
| composition | JSON | False | Параметры композиции диктора на видео |
| circle | JSON | False | Параметры генерации диктора в кружке |
Описание параметров секции actor:
| Имя параметра | Тип | Обязателен | Описание |
|---|---|---|---|
| name | string | True | Имя диктора |
| version | string | True | Версия диктора (необязательный параметр, или "latest". Если не указана, используется последняя версия, соответствующая заданным параметрам) |
| style | string | False | Стиль диктора |
| shot | string | True | План диктора. Например, план waist означает, что диктор на видео будет отображен по пояс. Размер size кадра должен соответствовать размеру фона(background) |
| size | string | False | Разрешение видео (одно из значений SD, HD, FullHD, 4K), для которого подходит выбранный план диктора |
Eсли заданные параметры не согласованы друг с другом, будет получено сообщение об ошибке, например:
Пример неуспешного ответа
{
"message": "bad style for Natalia-latest",
"status": "ERROR"
}
Описание параметров секции composition:
| Имя параметра | Тип | Обязателен | Совместимые стили | Описание |
|---|---|---|---|---|
| orientation | string | True | rectangle, circle | Ориентация итогового видео. Принимает значения "vertical" или "horizontal". Вертикальная ориентация обладает инвертированным относительно горизонтального разрешением. Если видео генерировалось в 1280x720, то при вертикальной ориентации разрешение будет 720x1280 |
| frame_style | string | False | rectangle, circle | Стиль рамки вокруг актера. Принимает значение "rectangle" или "circle". "rectangle" генерирует обычное видео, с диктором, занимающим весь экран. "circle" сгенерирует видео, с уменьшенным диктором в кружке, помещенным в один из углов. В зависимости от выбранного значения, некоторые параметры секции могут оказаться недоступны. Значение по умолчанию - rectangle |
| scale | float | False | rectangle | Коэффициент уменьшения размера актёра на видео. Принимает значения из полуинтервала (0,1], значение по умолчанию - 1 |
| crop | float | False | rectangle | Коэффициент обрезки актёра снизу. Размер итогового изображения будет составлять video_width:video_height * crop Принимает значения из полуинтервала (0,1], значение по умолчанию 1 |
| shift | float | False | rectangle | Коэффициент сдвига актера относительно центра видео. Принимает значения из отрезка [-1,1]. Отрицательные значения двигают актера "влево", положительные "вправо", значение по умолчанию 0 |
| location | string | False | circle | Местоположение актера в выбранной рамке на видео. Принимает значение из комбинации "{lower,upper}{left,right}". Например, значение "upperight" поместит актера в кружке в правый верхний угол, значение по умолчанию "upperleft" |
| background_color | string | False | circle | Цвет фона внутри выбранной рамки. Задаётся в hex формате. Например, значение #FFFFFF сделает фон белым, значение по умолчанию - #FFFFFF |
| border_color | string | False | circle | Цвет выбранной рамки вокруг актера. Задаётся в hex формате. Например, значение #FFFFFF сделает рамку белой, значение по умолчанию - #000000 |