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	3 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
Maximum lenght of video name	35 characters

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

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
202	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
422	Incorrect parameters' names	JSON	Bad request
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": "Sara",
    "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

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

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

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
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

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

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	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

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). Must be in pattern: year-month-dayThours:minutes:seconds+tz, where seconds are equal to 00. Specified in UTC. Example 2020-02-11T12:30:00+00	No
end	Date until which the calculation is made (not inclusive). Must be in pattern: year-month-dayThours:minutes:seconds+tz, where seconds are equal to 00. Specified in UTC. Example 2020-02-11T12:30:00+00	No
offset	Result bias	No
limit	Result limitation	No
sort	Field name and the order of sorting by the field. The sort parameter has the form: [+-]	No
fields	Additional fields to be returned (background, shot, script, voice_name, actor_name, model_version, video_name, emotion)	No
id	ID of the task	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 in UTC
background	Background of video
shot	Camera position on video
script	SSML document or plain text, voiced by the speaker
voice_name	Speaker's voice
actor_name	Speaker's name
model_version	Speaker's version
video_name	Name of the video
emotion	Emotion of speaker's voice

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&fields=shot,background&sort=-duration"

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

Unsuccessful response example

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

Change video properties

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

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

Description of request parameters:

Parameter Name	Description	Required
video_name	New video name, no longer than 35	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

Request example

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}

Successful response example

{"status": "ok", "message": "success"}

Unsuccessful response example

{"status": "ERROR", "message": "no such video"}

Delete video

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

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

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

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/video/${TASK_ID}

Successful response example

{"status": "ok", "message": "success"}

Unsuccessful response example

{"status": "ERROR", "message": "no such video"}

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 Alena use specification provided by Yandex 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.)
emotion	string	Emotion of speaker's voice. Optional parameter. If not specified, voice will have neutral emotion.
video_name	string	Name for generated video

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

Cancel task

Get link for generated video

List videos

Change video properties

Delete video

Model configuration

Configuration description