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

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

Описание

В этом разделе описаны методы асинхронного 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
  • Тип данных ответа: video/mp4
Код ответа Данные ответа Формат ответа Описание
200 mp4 файл сгенерированного видео video
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 -H cdn-auth-token:${CDN_TOKEN} \
     https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/video/${TASK_ID} -o /tmp/video.mp4

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

{"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"
}