Виртуальный диктор

Описание

В этом разделе описаны методы асинхронного 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",
                        "out_size": {
                            "width": 512,
                            "height": 720
                        }
                    }
                }
            },
            "4.0.0": {
                "style": "dressshirt",
                "gender": "female",
                "voices": [
                    "Alena",
                    "Mia",
                    "Sara"
                ],
                "shots": {
                    "waist": {
                        "size": "HD",
                        "out_size": {
                            "width": 512,
                            "height": 720
                        }
                    }
                }
            }
        }
    },
    "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)	Нет
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	Название эмоции голоса на видео

Важно

Скачать видео по ссылке можно только с того же 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	Текст, который будет озвучен диктором, или текст, размеченный SSML-тегами в соответствии со спецификацией провайдера голоса. С помощью SSML разметки можно вставлять паузы, изменять произношение, ставить ударения и др. Например, для текущего голоса Alena используйте разметку от компании Yandex, следуя официальной документации
actor	JSON	Параметры модели диктора
voice	string	Название голоса диктора
background	string	Название фона. Размер фона (size) должен соответствовать размеру кадра модели (size в shot). Необязательный параметр. Для выбора фона с хромакеем используйте значение по умолчанию green_screen, при этом размер сгенерированного видео будет таким, который указан в параметре out_size выбранной конифгурации shot.
emotion	string	Название эмоции голоса на видео. Необязательный параметр. По-умолчанию используется нейтральная эмоциональная окраска голоса.
video_name	string	Название генерируемого видео

Описание параметров секции actor:

Имя параметра	Тип	Описание
name	string	Имя диктора
version	string	Версия диктора (необязательный параметр, или "latest". Если не указана, используется последняя версия, соответствующая заданным параметрам)
style	string	Стиль диктора (необязательный параметр)
shot	string	План диктора. Например, план waist означает, что диктор на видео будет отображен по пояс. Размер size кадра должен соответствовать размеру фона(background)
size	string	Разрешение видео (одно из значений SD, HD, FullHD, 4K), для которого подходит выбранный план диктора (необязательный параметр)

Eсли заданные параметры не согласованы друг с другом, будет получено сообщение об ошибке, например:

Пример неуспешного ответа

{
    "message": "bad style for Natalia-latest",
    "status": "ERROR"
}