Виртуальный диктор
Описание
В этом разделе описаны методы асинхронного HTTP API для создания видео с виртуальным диктором, озвучивающим ваш текст на основе заданной вами конфигурации.
Перед началом использования API необходимо получить авторизационный токен, используемый в заголовке CDN-AUTH-TOKEN. Подробнее о времени жизни токена и способе его получения можно найти на странице Авторизация.
Ниже приведено описание методов API с примерами запросов для управления созданием видео.
Ограничения
| Характеристика | Ограничение |
|---|---|
| Максимальная длительность видеоролика | 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 имеет вид: [+-] | Нет |
| 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 | Ориентация итогового видео. Принимает значения "vertical" или "horizontal". Вертикальная ориентация обладает инвертированным относительно горизонтального разрешением. Если видео генерировалось в 1280x720, то при вертикальной ориентации разрешение будет 720x1280 |
| scale | float | False | Коэффициент уменьшения размера актёра на видео. Принимает значения из полуинтервала (0,1] |
| crop | float | False | Коэффициент обрезки актёра снизу. Размер итогового изображения будет составлять video_width:video_height * crop Принимает значения из полуинтервала (0,1] |
| shift | float | False | Коэффициент сдвига актера относительно центра видео. Принимает значения из отрезка [-1,1]. Отрицательные значения двигают актера "влево", положительные "вправо" |
Описание параметров секции circle:
| Имя параметра | Тип | Обязателен | Описание |
|---|---|---|---|
| location | string | True | Местоположение актера на видео. Принимает значение из комбинации " |
| background_color | string | False | Цвет фона внутри кружка. Задаётся в hex формате. Например, значение #FFFFFF сделает фон белым |
| border_color | string | False | Цвет рамки кружка. Задаётся в hex формате. Например, значение #FFFFFF сделает рамку белой |
Важно
При одновременном использовании секций circle и composition все параметры composition, кроме orientation, будут проигнорированы