Text-to-Video Talking Head

Description

This section describes the asynchronous API methods for generating video based on the text and the configuration you specify.

Before you start using it obtain an authorazation token which will be specified in the header CDN-AUTH-TOKEN. On the page Authorization you can find the details about token lifetime and the method of obtaining it.

Below are descriptions of API methods with examples of queries to manage video creation.

Limitations

Characteristic	Limit
Maximum video duration	2 minutes
Maximum text size	3000 characters
Period of time for storing a video file since its creation	30 days
Maximum number of requests per month	1500

API methods

Get a list of available configurations

URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/configurations

Request type: GET
Headers: CDN-AUTH-TOKEN
Response data type: JSON Object

Response code	Response data	Response format	Description
200	List of models and backgrounds available for the account	JSON	Successful request
403	status: type string, message, type string	JSON	Forbidden
404	None	None	Not found
500	None	None	Internal Server Error
503	None	None	Service unavailable

Request example

export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
curl -H cdn-auth-token:${CDN_TOKEN} \
     https://api.cdnvideo.ru/app/th-api/v1/accounts/testaccount/configurations

Successful response example

{
    "status": "ok",
    "voices": {
       "Julia_01": {
          "language": "ru-RU",
          "gender": "female",
          "provider": "STC",
          "name": "Julia_n"
       },
      "Alena_01": {
          "language": "ru-RU",
          "gender": "female",
          "name": "alena",
          "provider": "Yandex"
       },
      "en-US-SaraNeural": {
           "language": "en-US",
           "gender": "female",
           "name": "en-US-SaraNeural",
           "provider": "Microsoft"
       },
       "en-GB-MiaNeural": {
          "language": "en-US",
          "gender": "female",
          "name": "en-GB-MiaNeural",
          "provider": "Microsoft"
       }
    },
    "models": {
        "Natalia": {
            "1.0.0": {
                "style": "suitjacket",
                "gender": "female",
                "voices": [
                    "Julia_01"
                ],
                "shots": {
                    "waist": {
                        "size": "HD",
                        "out_size": {
                            "width": 512,
                            "height": 720
                        }
                    }
                }
            },
            "4.0.0": {
                "style": "dressshirt",
                "gender": "female",
                "voices": [
                    "Alena_01",
                    "en-GB-MiaNeural",
                    "en-US-SaraNeural"
                ],
                "shots": {
                    "waist": {
                        "size": "HD",
                        "out_size": {
                            "width": 512,
                            "height": 720
                        }
                    }
                }
            }
       }
    },
    "backgrounds": {
        "background_2": {
            "sizes": [
                "HD"
            ]
        }
    }
}

Unsuccessful response example

{"status": "ERROR", "message": "invalid account"}

Create a task for video generation

URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/generate

Request type: POST
Headers: CDN-AUTH-TOKEN
Request body: JSON with task parameters
Response data type: JSON Object

Response code	Response data	Response format	Description
200	status: type string, id: type string	JSON	The task was successfully enqueued and assigned its ID
400	status: type string, message, type string	JSON	Invalid request
403	status: type string, message, type string	JSON	Forbidden
404	None	None	Not found
500	None	None	Internal Server Error
503	None	None	Service unavailable

Request example

export CDN_TOKEN=cdn2_2YXPIWIYRT15SZGQ2Q0JN362PUDXIE
export TEXT=$(cat <<-END
{
    "script": "Hello! This is the text I am speaking.",
    "actor": {
        "name": "Natalia",
        "version": "4.0.0",
        "style": "dressshirt",
        "shot": "waist",
        "size": "HD"
    },
    "voice": "en-US-SaraNeural",
    "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

Successful response example

{
  "status": "ok",
  "id": "90d70829-134f-4957-9c13-c8bf67c1678e"
}

Unsuccessful response example

{"status": "ERROR", "message": "invalid account"}

Check task status

URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/status/<task_id>

Request type: GET
Headers: CDN-AUTH-TOKEN
Response data type: JSON Object

Response code	Response data	Response format	Description
200	status: type string, task: type JSON	JSON	Successful request
400	status: type string, message, type string	JSON	Invalid request
403	status: type string, message, type string	JSON	Forbidden
404	None	None	Not found
500	None	None	Internal Server Error
503	None	None	Service unavailable

Description of the returned parameter task:

Parameter name	Description
id	ID of the task
attempts	Number of attempts used during task processing
status	Task status: in_queue, processing, processed, canceled
message	Additional message about the task status
script	SSML document or plain text, voiced by the speaker

Request example

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}

Successful response example

{
"status": "ok",
"task": {
    "id": "3e10edaf-41c3-4210-b92f-5d68b269c20f",
    "attempts": 1,
    "status": "CANCELED",
    "message": "canceled by user request",
    "script": "this is script"
    }
}

Unsuccessful response example

{"status": "ERROR", "message": "invalid account"}

Get link for generated video

URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/video/<task_id>

Request type: GET
Headers: CDN-AUTH-TOKEN
Response data type: JSON Object

Response code	Response data	Response format	Description
200	status: type string, url: type string	JSON	Successful request
400	status: type string, message, type string	JSON	Invalid request
403	status: type string, message, type string	JSON	Forbidden
404	None	None	Not found
500	None	None	Internal Server Error
503	None	None	Service unavailable

Important!

You can download video only from the same IP address from which the request was sent. The link is valid for 6 hours.

Request example

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}

Successful response example

{
    "status": "ok",
    "url": "https://thaas-video.cdnvideo.ru/testaccount/087c70cc-2d1a-4214-9ef1-54d38f2ecbe0.mp4?md5=snYRj_m8EfMmSTTWArIBKQ&e=1637777947"
}

Unsuccessful response example

{"status": "ERROR", "message": "invalid account"}

URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/tasks

Request type: GET
Headers: CDN-AUTH-TOKEN
Response data type: JSON Object

Description of request parameters:

Parameter name	Description	Required
start	Date from which the calculation is made (inclusive)	No
end	Date until which the calculation is made (not inclusive)	No
offset	Result bias	No
limit	Result limitation	No

Possible response codes:

Response code	Response data	Response format	Description
200	List of the generated video sorted by the date of receiving the task	JSON	Successful request
400	status: type string, message, type string	JSON	Invalid request
403	status: type string, message, type string	JSON	Forbidden
404	None	None	Not found
500	None	None	Internal Server Error
503	None	None	Service unavailable

Description of response parameters:

Parameter name	Description
id	ID of the task
video_url	URL for the generated video
resolution	Resolution of the video
duration	Duration of the video (in seconds)
date	Date the task was received in the service

Important!

You can download video only from the same IP address from which the request was sent. The link is valid for 6 hours.

Request example

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"

Successful response example

[
    {
        "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"
    },
    {
        "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"
    }
]

Unsuccessful response example

{"status": "ERROR", "message": "invalid account"}

Cancel task

URL: https://api.cdnvideo.ru/app/th-api/v1/accounts/<your_account_name>/cancel/<task_id>

Request type: DELETE
Headers: CDN-AUTH-TOKEN
Response data type: JSON Object

Response code	Response data	Response format	Description
204	status: type string, message, type string	JSON	task canceled
400	status: type string, message, type string	JSON	Invalid Request
403	status: type string, message, type string	JSON	Forbidden
404	None	None	Not found
500	None	None	Internal Server Error
503	None	None	Service unavailable

Request example

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}

Successful response example

{"status": "ok"}

Unsuccessful response example

{"status": "error", "message": "wrong task status: CANCELED"}

Model configuration

To enqueue a task, you need to send a request with the configuration of the model in a JSON format.

Parameters of available models can be found by sending a request to /configurations

Configuration description

Parameter name	Type	Description
script	string	Contains either text or ssml to be synthesized. In case of ssml use follow specification of corresponding TTS provider. By using SSML tags you can add pauses, change pronounciation, place stress markers etc. For example, for the current voice Julia_01 use specification provided by Speech Technology Center (STC) on their website.
actor	JSON	Speaker parameters
voice	string	Name of the speaker's voice
background	string	Background name (background size must match the size of the model's shot. Optional parameter. If not specified, green_screen.)

Parameters for actor section:

Parameter name	Type	Description
name	string	Speaker's name
version	string	Speaker version (optional parameter, or "latest". If not specified, the latest version corresponding to the specified parameters is used)
style	string	Speaker style (optional)
shot	string	Shot type of a speaker (the size of shot must match the size of background)
size	string	Video resolution (SD, HD, FullHD or 4K), for which the specified speaker's shot fits (optional)

If the specified parameters are not consistent with each other, an error message will be received, for example:

Unsuccessful response example

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

Text-to-Video Talking Head

Description

Limitations

API methods

Get a list of available configurations

Create a task for video generation

Check task status

Get link for generated video

List videos

Cancel task

Model configuration

Configuration description