Виртуальный диктор
Описание
В этом разделе описаны методы асинхронного HTTP API для создания видео с виртуальным диктором, озвучивающим ваш текст на основе заданной вами конфигурации.
Перед началом использования API необходимо получить авторизационный токен, используемый в заголовке CDN-AUTH-TOKEN. Подробнее о времени жизни токена и способе его получения можно найти на странице Авторизация.
Ниже приведено описание методов API с примерами запросов для управления созданием видео.
Ограничения
Характеристика | Ограничение |
---|---|
Максимальная длительность видеоролика | 2 минуты |
Максимальный объем текста | 3000 символов |
Время хранения сгенерированных видеофайлов с момента создания | 30 дней |
Максимальное количество запросов в месяц | 1500 |
Методы 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", "models": { "Natalia_01": { "1.0.0": { "style": "suitjacket", "gender": "female", "language": "ru-RU", "voices": [ "Julia_01", ], "shots": { "waist": { "size": "HD", "out_size": { "width": 512, "height": 720 } } } }, "2.0.0": { "style": "tshirt", "language": "ru-RU", "gender": "female", "voices": [ "Julia_01", ], "shots": { "waist": { "size": "HD", "out_size": { "width": 512, "height": 720 } } } } }, "backgrounds": { "background_2": { "sizes": [ "HD", ] } } }
Пример неуспешного ответа
{"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
Код ответа | Данные ответа | Формат ответа | Описание |
---|---|---|---|
200 | 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_01", "version": "1.0.0", "style": "suitjacket", "shot": "waist", "size": "HD" }, "voice": "Julia_01", "background": "green_screen" } 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 | Дополнительное сообщение о статусе задачи |
script | Скрипт(текст), озвучиваемый диктором |
Пример запроса
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", "script": "this is script" } }
Пример неуспешного ответа
{"status": "ERROR", "message": "invalid account"}
Получить ссылку на сгенерированное видео
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>/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"}
Конфигурация модели
Для постановки задачи в очередь необходимо отправить запрос с конфигурацией модели в формате JSON.
Параметры доступных моделей можно узнать, отправив запрос на /configurations
Описание конфигурации
Ниже приведено описание параметров конфигурации.
Имя параметра | Тип | Описание |
---|---|---|
script | string | Текст, который будет озвучен диктором, или текст, размеченный SSML-тегами в соответствии со спецификацией провайдера голоса. С помощью SSML разметки можно вставлять паузы, изменять произношение, ставить ударения и др. Например, для текущего голоса Julia_01 используйте разметку от компании «Центр речевых технологий»(ЦРТ), следуя официальной документации |
actor | JSON | Параметры модели диктора |
voice | string | Название голоса диктора |
background | string | Название фона. Размер фона (size) должен соответствовать размеру кадра модели (size в shot). Необязательный параметр. Для выбора фона с хромакеем используйте значение по умолчанию green_screen, при этом размер сгенерированного видео будет таким, который указан в параметре out_size выбранной конифгурации shot. |
Описание параметров секции 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_01-latest", "status": "error" }