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