Перейти к содержанию

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

Описание

В этом разделе описаны методы асинхронного HTTP API для создания видео с виртуальным диктором, озвучивающим ваш текст на основе заданной вами конфигурации.

Перед началом использования API необходимо получить авторизационный токен, используемый в заголовке CDN-AUTH-TOKEN. Подробнее о времени жизни токена и способе его получения можно найти на странице Авторизация.

Ниже приведено описание методов API с примерами запросов для управления созданием видео.

Ограничения

Внимание!

  1. Установлено ограничение на количество обращений к 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 имеет вид: [+-] Нет
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