Skip to content

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

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": "Текст для диктора.",
    "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

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:

Имя параметра Описание
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"}

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

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_01-latest",
    "status": "error"
}