# KreadoAI—API V3.0

## 1. Quick Start Guide

Welcome to the KreadoAI API Documentation! 🙌KreadoAI's API empowers you to programmatically create digital avatar videos and seamlessly integrate KreadoAI's advanced AI capabilities into your applications. Unlock the full potential of KreadoAI to bring creativity and efficiency to your projects.This guide will help you get started quickly, covering everything from authentication methods and API structures to detailed interface descriptions and usage examples. Let’s explore the possibilities together! 🚀

### 1.1 Create an Account

Sign up for a [KreadoAI account](https://www.kreadoai.com/). Once your account is created, upgrade to the [Pro membership](https://www.kreadoai.com/price) to unlock the powerful AI features that allow you to create professional-grade digital avatar videos.<br>

### 1.2 Access your API key

After logging into your KreadoAI account, navigate to **Account Overview -> API Settings** to retrieve your API key.<br>

### 1.3 Additional Notes

* Our services are hosted in a Singapore-based data center. Users in China may experience slower network speeds.
* During service upgrades, requests may fail. Please implement retry strategies to handle such cases effectively.
* Manage concurrent requests carefully. If rate-limiting is triggered, avoid continuous retries, as this will only prolong the cooldown period.

## 2. Authentication

To access KreadoAI's API and perform operations, you must authenticate and authorize your requests using HTTP headers. Here's an example:

```bash
curl --request GET \
  --url "https://api.kreadoai.com/apis/open/user/v3/getInfo" \
  --header "apiToken: 61FDB6A8A14FE77EE2DF893058572EE3" \
  --header "Content-Type: application/json"
```

<br>

## 3. Digital Avatars

### 3.1 Retrieve Digital Avatar List

#### Use Case

> This endpoint allows you to fetch a list of digital avatars, including realistic avatars, talking photo avatars, and cloned avatars.

#### Important Notes

> This is a paginated endpoint. Please fetch the required avatars accordingly.**Request Rate Limit:** Supports up to 30 concurrent queries per second. Exceeding this limit will trigger rate-limiting policies.**Usage Restrictions:** Requests will fail if the membership expires.

#### Request Details

<table data-header-hidden><thead><tr><th width="283"></th><th></th></tr></thead><tbody><tr><td><strong>Request URL</strong></td><td>https://api.kreadoai.com/apis/open/avatar/v3/list</td></tr><tr><td><strong>Request Method</strong></td><td>post</td></tr></tbody></table>

#### Request Parameters

**Header**

<table data-header-hidden><thead><tr><th width="219"></th><th width="146"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter Name</strong></td><td><strong>Required</strong></td><td><strong>Example Value</strong></td></tr><tr><td>Content-Type</td><td>YES</td><td>application/json</td></tr><tr><td>apiToken</td><td>YES</td><td>61FDB6A8A14FE77EE2DF893058572EE3</td></tr></tbody></table>

**Body**

<table data-header-hidden><thead><tr><th width="199"></th><th width="157"></th><th width="121"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter Name</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Description</strong></td></tr><tr><td>cloneDigitalHuman</td><td>Integer</td><td>YES</td><td>Query Digital Human Clone List: 0 - Do not query, 1 - Query</td></tr><tr><td>supportTypeId</td><td>Integer</td><td>YES</td><td>Digital Human Type: 100 - Photo, 101 - Video</td></tr><tr><td>digitalHumanId</td><td>Integer</td><td>NO</td><td>Digital Human ID</td></tr><tr><td>tagIds</td><td>List&#x3C;Integer></td><td>NO</td><td><p>Gender Tags：</p><ul><li>211: Female</li><li>210: Male </li></ul><p>Style Tags：</p><ul><li>137: Realistic</li><li>138: Featured</li><li>139: Premium</li></ul></td></tr><tr><td>areaTypeIds</td><td>List&#x3C;Integer></td><td>NO</td><td><p></p><p>Digital Human Region Tag:</p><ul><li>141: Western</li><li>140: Asian</li><li>142: Japanese/Korean</li><li>143: Southeast Asian</li><li>145: Indian</li><li>144: Middle Eastern</li><li>146: African</li></ul></td></tr><tr><td>pageIndex</td><td>Integer</td><td>YES</td><td>Page Number</td></tr><tr><td>pageSize</td><td>Integer</td><td>YES</td><td>Data Per Page</td></tr></tbody></table>

#### Response Parameters

| **Parameter Name**          | **Type** | **Description**                              |
| --------------------------- | -------- | -------------------------------------------- |
| digitalHumanId              | Integer  | Digital Human ID                             |
| supportTypeId               | Integer  | Digital Human Type: 100 - Photo, 101 - Video |
| digitalHumanThumbnailUrl    | String   | Thumbnail Avatar                             |
| digitalHumanPhotoUrl        | String   | Full-Body Image                              |
| digitalHumanPreviewVideoUrl | String   | Preview Video                                |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/avatar/v3/list' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "cloneDigitalHuman": 0,
    "supportTypeId": 100,
    "digitalHumanId": null,
    "tagIds": null,
    "areaTypeIds": null,
    "pageIndex": 1,
    "pageSize": 1
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "pageIndex": 1,
        "pageSize": 1,
        "totalCount": 68,
        "totalPages": 68,
        "data": [
            {
                "digitalHumanId": 4192,
                "supportTypeId": 100,
                "digitalHumanThumbnailUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/talking_photo/results/face_detection/2024/11/19/3f4dd450a63e11efa60f0242ac110005_cover.jpg",
                "digitalHumanPhotoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/11/eace2a4536ab41bd85a7fb728211862e.png",
                "digitalHumanPreviewVideoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/11/eace2a4536ab41bd85a7fb728211862e.png"
            }
        ]
    },
    "requestId": "1862015410570563585"
}

```

### 3.2 Upload Custom Photo

#### Use Case

> Allows users to upload any photo that meets the requirements. Once the photo passes facial verification, it can be used for digital avatar video generation.

#### Notes

> * Usage Restrictions
>   * Suggested front view of the character, as shown on the left
>   * Clear character avatar, does not support multiple people
>   * The face is unobstructed and the mouth is closed
>   * It is recommended to use a half-length figure
>   * The image must be no larger than 10MB, with dimensions between 360px and 4000px on both width and height.
>   * I have agreed to the ["User Terms of Service"](https://www.kreadoai.com/terms-of-service)
> * Request Frequency: Supports a maximum of 30 concurrent uploads per second. Exceeding this limit will trigger rate-limiting policies.

#### Request Details

<table data-header-hidden><thead><tr><th width="230"></th><th></th></tr></thead><tbody><tr><td><strong>Request URL</strong></td><td>https://api.kreadoai.com/apis/open/avatar/v3/uploadAvatar</td></tr><tr><td><strong>Request Method</strong></td><td>post</td></tr></tbody></table>

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required**   | **Description**                                                                                                                                                                                                                                               |
| ------------------ | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fileUrl            | String   | <p>YES<br></p> | <p>Any publicly accessible image URL that meets the following requirements:</p><ul><li>Supported Formats: jpg, jpeg, png, webp</li><li>Restrictions: Special characters, such as Chinese or other non-standard symbols, are not allowed in the URL.</li></ul> |

#### Response Parameters

| **Parameter Name** | **Type** | **Description**      |
| ------------------ | -------- | -------------------- |
| jobId              | Long     | Upload photo task ID |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/avatar/v3/uploadAvatar' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "fileUrl": "https://cdn.pixabay.com/video/2021/06/24/78732-567321517_medium.jpg"
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "jobId": 1862021310686838786
    },
    "requestId": "1862021310636507138"
}
```

<br>

### 3.3 Query Photo Upload Results

#### Use Case

> This is used to check whether the uploaded photo passes the facial verification and, if successful, returns the digital avatar image information.

#### Notes

> * Request Frequency: A maximum of 60 concurrent queries per second are supported. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/avatar/v3/getUploadCustomAvatar> |
| ------------------ | -------------------------------------------------------------------- |
| **Request Method** | post                                                                 |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description**                            |
| ------------------ | -------- | ------------ | ------------------------------------------ |
| jobId              | Long     | YES          | Task ID returned after uploading the photo |

#### Response Parameters

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th width="105"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter Name</strong></td><td><strong>Type</strong></td><td><strong>Nested Key</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>status</td><td>Integer</td><td><br></td><td><br></td><td><p>Status:</p><ul><li>1 - Waiting for execution</li><li>2 - In progress</li><li>3 - Success</li><li>4 - Failure</li><li>5 - Timeout</li></ul></td></tr><tr><td>digitalHuman<br></td><td>Object<br></td><td>digitalHumanId</td><td>Integer</td><td>Digital Human Image ID</td></tr><tr><td></td><td></td><td>supportTypeId</td><td>Integer</td><td><p>Digital Human Type:</p><ul><li>100 - Photo</li><li>101 - Video</li></ul></td></tr><tr><td></td><td></td><td>digitalHumanThumbnailUrl</td><td>String</td><td>Thumbnail Avatar</td></tr><tr><td></td><td></td><td>digitalHumanPhotoUrl</td><td>String</td><td>Full-body Image of Digital Human</td></tr><tr><td></td><td></td><td>digitalHumanPreviewVideoUrl</td><td>String</td><td>Digital Human Preview Video</td></tr></tbody></table>

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/avatar/v3/getUploadCustomAvatar' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "jobId": "1862021310686838786"
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "status": 2,
        "digitalHuman": {
            "digitalHumanId": 4194,
            "supportTypeId": 100,
            "digitalHumanThumbnailUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/talking_photo/results/face_detection/2024/11/28/531a2d1aad5211ef90a682df5622d5f4_cover.jpg",
            "digitalHumanPhotoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/11/bfbc98da93404b2e8e07d7ed3ed8239e.jpg",
            "digitalHumanPreviewVideoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/11/bfbc98da93404b2e8e07d7ed3ed8239e.jpg"
        }
    },
    "requestId": "1862022547222183937"
}
```

<br>

## 4. Digital Avatar Video Generation

### 4.1 Submit General Video Generation Task

#### Use Case

> This is used for generating any video that meets the required criteria.

#### Notes

> * Usage Restrictions
>   * The video must be in **MP4 or MOV format**, encoded with **H.264**, and have a **duration longer than 5 seconds**.
>   * Videos cannot exceed 300MB in size.
>   * Audio is supported, with durations ranging from 1 to 600 seconds, in mp3, wav, or m4a format.
>   * Requests will fail after the membership expires.
> * Request Frequency
>   * A maximum of one concurrent video task submission is allowed per second. Exceeding this will trigger rate-limiting policies.
>   * The server allows a maximum of 8 queued tasks. Submissions exceeding this limit will fail.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/submitLipTask> |
| ------------------ | ----------------------------------------------------------- |
| **Request Method** | post                                                        |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description**                                                                                    |
| ------------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------- |
| taskName           | String   | YES          | Task Name                                                                                          |
| videoUrl           | String   | YES          | Video file URL (Special characters like Chinese or other non-standard characters are not allowed). |
| audioUrl           | String   | YES          | Audio file URL (Special characters like Chinese or other non-standard characters are not allowed). |
| audioId            | Integer  | NO           | Audio File ID: Required if using system voices.                                                    |

#### Response Parameters

| **Parameter Name** | **Type** | **Description** |
| ------------------ | -------- | --------------- |
| jobId              | Long     | Task ID         |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/submitLipTask' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "taskName": "test",
    "videoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/upload_simple_clone_video/2024/11/ea634216760c4d87a0709a7d00eddc9e.mp4",
    "audioUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/audio/2024/11/2b150387595c4efba35db553740cb47a.mp3"
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "jobId": 1861664658419253250
    },
    "requestId": "1861664651620286466"
}
```

<br>

### 4.2 Submit Digital Human Video Generation Task

#### Use Case

> This is applicable for video synthesis of real digital avatars, photo avatars, and cloned avatars within the KreadoAI system.

#### Notes

> * **Usage Restrictions**
>   * Audio is supported, with durations ranging from 1 to 600 seconds, in mp3, wav, or m4a format.
>   * Requests will fail after the membership expires.
> * **Request Frequency**
>   * A maximum of one concurrent video task submission is allowed per second. Exceeding this will trigger rate-limiting policies.
>   * The server allows a maximum of 8 queued tasks. Submissions exceeding this limit will fail.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/submitSystemLipTask> |
| ------------------ | ----------------------------------------------------------------- |
| **Request Method** | post                                                              |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

<table data-header-hidden><thead><tr><th></th><th></th><th width="113"></th><th width="105"></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Parameter Name</strong></td><td><strong>Type</strong></td><td><strong>Nested Key</strong></td><td><strong>Type</strong></td><td><strong>Nested Key</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Description</strong></td></tr><tr><td>taskName</td><td>String<br></td><td><br></td><td><br></td><td></td><td></td><td>YES</td><td><p><strong>Status:</strong> </p><ul><li>1 - Waiting for execution </li><li>2 - In progress </li><li>3 - Success </li><li>4 - Failure </li><li>5 - Timeout</li></ul></td></tr><tr><td>videoRatio</td><td>Integer</td><td><br></td><td><br></td><td></td><td></td><td>YES</td><td><p><strong>Video Aspect Ratio:</strong> </p><ul><li>1 - Represents 16:9 aspect ratio </li><li>2 - Represents 9:16 aspect ratio</li></ul></td></tr><tr><td>audio</td><td>Object</td><td>audioUrl</td><td>String</td><td></td><td></td><td>YES</td><td><strong>Audio File URL</strong> (Special characters like Chinese or other non-standard characters are not allowed)</td></tr><tr><td></td><td></td><td>audioId</td><td>Integer</td><td></td><td></td><td>NO</td><td>Audio File ID: Required if using system voices.</td></tr><tr><td>digitalHuman</td><td>Object</td><td>digitalHumanId</td><td>Integer</td><td></td><td></td><td>YES</td><td>Digital Human Image ID</td></tr><tr><td></td><td></td><td>mask</td><td>Integer</td><td></td><td></td><td>NO</td><td><p></p><p><strong>Mask Type:</strong> </p><ul><li>0 - No mask </li><li>1 - Circular mask </li><li>2 - Rectangular mask (This field currently only applies to photo digital humans)</li></ul></td></tr><tr><td></td><td></td><td>x</td><td>Integer</td><td></td><td></td><td>NO</td><td>Digital Human Position X-axis Coordinate</td></tr><tr><td></td><td></td><td>y</td><td>Integer</td><td></td><td></td><td>NO</td><td>Digital Human Position Y-axis Coordinate</td></tr><tr><td></td><td></td><td>resize</td><td>String</td><td></td><td></td><td>NO</td><td><strong>Avatar Scale Ratio</strong> – Controls the zoom level of the digital human. Supports up to two decimal places, with a default value of <strong>1.00</strong>.</td></tr><tr><td></td><td></td><td>templateId</td><td>Integer</td><td></td><td></td><td>NO</td><td><p>The <strong>Photo Avatar Expression Template ID</strong> parameter is only applicable to photo-based digital humans. It is used to control lip-sync stability. For available IDs, please refer to section 4.6.</p><p>4o</p></td></tr><tr><td>background</td><td>Object</td><td>type</td><td>Integer</td><td></td><td></td><td>NO</td><td>Background Type:302 - Color background; 303 - User-defined background</td></tr><tr><td></td><td></td><td>color</td><td>String</td><td></td><td></td><td>NO</td><td>Background Color:When type=302, this field is required. For example, green screen: rgb (0, 255, 0)</td></tr><tr><td></td><td></td><td>backgroundElements</td><td>Array</td><td>elementType</td><td>Integer</td><td>NO</td><td>Type: 330 - Image; <strong>type=303 is required</strong></td></tr><tr><td></td><td></td><td></td><td></td><td>fileUrl</td><td>String</td><td>NO</td><td>Background image URL (supports PNG, JPEG, JPG, WEBM); <strong>type=303 is required</strong></td></tr><tr><td></td><td></td><td></td><td></td><td>resize</td><td>String</td><td>NO</td><td>Image scaling ratio (up to two decimal places), default: <strong>1.00</strong></td></tr></tbody></table>

#### Response Parameters

| **Parameter Name** | **Type** | **Description** |
| ------------------ | -------- | --------------- |
| jobId              | Long     | Task ID         |

#### 示例

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/submitSystemLipTask' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "taskName": "1-API测试-9",
    "videoRatio":2,
    "digitalHuman":{
        "digitalHumanId":9
    },
    "audio":{
        "audioUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/audio/2024/11/2b150387595c4efba35db553740cb47a.mp3"
    }
    
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "jobId": 1863824392856674305
    },
    "requestId": "1863824382987476993"
}
```

<br>

### 4.3 Query Video Task Generation Results

#### Use Case

> This is used to query the results of video generation tasks.

#### Notes

> * Usage Restrictions: Requests will fail after the membership expires.
> * Request Frequency: A maximum of 60 concurrent queries per second are supported. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/getLipVideoResult> |
| ------------------ | --------------------------------------------------------------- |
| **Request Method** | post                                                            |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description** |
| ------------------ | -------- | ------------ | --------------- |
| jobId              | String   | YES          | Task ID         |

#### Response Parameters

| **Parameter Name** | **Type** | **Nested Key** | **Type**    | **Description**                                                                                                                                                     |
| ------------------ | -------- | -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status             | Integer  | <p><br></p>    | <p><br></p> | <p><strong>Status:</strong> </p><ul><li>1 - Waiting for execution </li><li>2 - In progress </li><li>3 - Success </li><li>4 - Failure </li><li>5 - Timeout</li></ul> |
| videoTask          | Object   | taskId         | Integer     | Video ID                                                                                                                                                            |
| videoUrl           | String   | Video File URL |             |                                                                                                                                                                     |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/getLipVideoResult' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "jobId": 1861664658419253250
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "status": 3,
        "videoTask": {
            "taskId": 122164,
            "videoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/video/2024/11/e2e4a41b0fac4f0d99468d582ee3f850.mp4"
        }
    },
    "requestId": "1862378739852275713"
}
```

<br>

### 4.4 Get Video List

#### Use Case

> This is used for paginated querying of the video list.

#### Notes

> * Usage Restrictions: Requests will fail after the membership expires.
> * Request Frequency: A maximum of 60 concurrent queries per second are supported. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/list> |
| ------------------ | -------------------------------------------------- |
| **Request Method** | post                                               |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description**                                                                                                                                                           |
| ------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status             | Integer  | NO           | <p><strong>Video Status:</strong> </p><ul><li>1 - Waiting for execution </li><li>2 - In progress </li><li>3 - Success </li><li>4 - Failure </li><li>5 - Timeout</li></ul> |
| pageIndex          | Integer  | YES          | Page Number                                                                                                                                                               |
| pageSize           | Integer  | YES          | Data per Page                                                                                                                                                             |

#### Response Parameters

| **Parameter Name** | **Type** | **Description**                                                                                                                               |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| taskId             | Integer  | Video ID                                                                                                                                      |
| taskName           | String   | Video Name                                                                                                                                    |
| status             | Integer  | <p>Status:</p><ul><li>1 - Waiting for execution</li><li>2 - In progress</li><li>3 - Success</li><li>4 - Failure</li><li>5 - Timeout</li></ul> |
| supportTypeId      | Integer  | Digital Human Image Type for Video:100 - Photo101 - Video                                                                                     |
| videoUrl           | String   | Video File URL                                                                                                                                |
| videoThumbnailUrl  | String   | Video Thumbnail URL                                                                                                                           |
| audioUrl           | String   | Audio File URL                                                                                                                                |
| audioDuration      | String   | Audio File Duration                                                                                                                           |
| createTime         | String   | Video Creation Time                                                                                                                           |
| successTime        | String   | Video Completion Time                                                                                                                         |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/list' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "pageIndex": 1,
    "pageSize": 1
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "pageIndex": 1,
        "pageSize": 1,
        "totalCount": 58,
        "totalPages": 58,
        "data": [
            {
                "taskName": "test",
                "taskId": 122164,
                "status": 3,
                "supportTypeId": 101,
                "videoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/video/2024/11/e2e4a41b0fac4f0d99468d582ee3f850.mp4",
                "videoThumbnailUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/11/181efa21c6e94860a964e78b352039bb.png",
                "audioUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/audio/2024/11/c02750852051447e8bd7c105ff42c6dd.mp3",
                "audioDuration": "00:00:16",
                "createTime": "2024-11-27 14:53:50",
                "successTime": "2024-11-27 16:12:20"
            }
        ]
    },
    "requestId": "1862404294312996865"
}
```

<br>

### 4.5 Get Video Details

#### Use Case

> This is used to retrieve detailed information about the video.

#### Notes

> * Usage Restrictions: Requests will fail after the membership expires.
> * Request Frequency: A maximum of 60 concurrent queries per second are supported. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/detail> |
| ------------------ | ---------------------------------------------------- |
| **Request Method** | post                                                 |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description** |
| ------------------ | -------- | ------------ | --------------- |
| taskId             | Integer  | YES          | Video ID        |

#### Response Parameters

| **Parameter Name** | **Type** | **Description**                                                                                                                               |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| taskId             | Integer  | Video ID                                                                                                                                      |
| taskName           | String   | Video Name                                                                                                                                    |
| status             | Integer  | <p>Status:</p><ul><li>1 - Waiting for execution</li><li>2 - In progress</li><li>3 - Success</li><li>4 - Failure</li><li>5 - Timeout</li></ul> |
| supportTypeId      | Integer  | Digital Human Image Type for Video:100 - Photo101 - Video                                                                                     |
| videoUrl           | String   | Video File URL                                                                                                                                |
| videoThumbnailUrl  | String   | Video Thumbnail URL                                                                                                                           |
| audioUrl           | String   | Audio File URL                                                                                                                                |
| audioDuration      | String   | Audio File Duration                                                                                                                           |
| createTime         | String   | Video Creation Time                                                                                                                           |
| successTime        | String   | Video Completion Time                                                                                                                         |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/detail' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "taskId": 122164
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "taskName": "test",
        "taskId": 122164,
        "status": 3,
        "supportTypeId": 101,
        "videoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/video/2024/11/e2e4a41b0fac4f0d99468d582ee3f850.mp4",
        "videoThumbnailUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/11/181efa21c6e94860a964e78b352039bb.png",
        "audioUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/audio/2024/11/c02750852051447e8bd7c105ff42c6dd.mp3",
        "audioDuration": "00:00:16",
        "createTime": "2024-11-27 14:53:50",
        "successTime": "2024-11-27 16:12:20"
    },
    "requestId": "1862408212865413122"
}
```

### &#x20;4.6  Talking Photo Avatar Expression Template Query

#### Use Case

> Used to Retrieve Talking Photo Avatar Expression Templates

#### Notes

> * **Request Rate Limit**: Supports up to 60 concurrent requests per second. Exceeding this limit will trigger rate-limiting.
> * **Usage Restriction**: Requests will fail if the user’s subscription has expired.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/emoList> |
| ------------------ | ----------------------------------------------------- |
| **Request Method** | post                                                  |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                |
| ------------------ | ------------ | -------------------------------- |
| Content-Type       | YES          | application/json                 |
| apiToken           | YES          | 61FDB6A8A14FE77EE2DF893058572EE3 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description** |
| ------------------ | -------- | ------------ | --------------- |
| id                 | Integer  | NO           | Language ID     |
| pageIndex          | Integer  | YES          | Page Number     |
| pageSize           | Integer  | YES          | Items per Page  |

#### Response Parameters

| **Parameter Name**   | **Type** | **Description**          |
| -------------------- | -------- | ------------------------ |
| id                   | Integer  | Language Name            |
| emoVideoUrl          | String   | Template Video File      |
| emoVideoThumbnailUrl | String   | Template Video Thumbnail |
| emoZhDescription     | String   | Title (Chinese)          |
| emoEnDescription     | String   | Title (English)          |

**Example**

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/emoList' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "pageIndex":1,
    "pageSize":1
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "pageIndex": 1,
        "pageSize": 1,
        "totalCount": 11,
        "totalPages": 11,
        "data": [
            {
                "id": 6,
                "emoVideoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/emo/user_upload_emo/2024/10/c91ce03cf85d493c8fa9245bcdfd325b.mp4",
                "emoVideoThumbnailUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/emo/user_upload_emo/2024/10/d39a818c7d9e4b7cb23b630e6dbdcfb0.png",
                "emoZhDescription": "惊讶惊恐",
                "emoEnDescription": "Amazed"
            }
        ]
    },
    "requestId": "1916747301578076162"
}
```

<br>

## 5. Instant Avatar Clone

### 5.1 Instant Avatar Clone Upload

#### Use Case

> This is used for uploading cloned image videos.

#### Notes

> * Usage Restrictions
>   * Requests will fail after the membership expires.
>   * Video orientation: Horizontal or vertical. If the video is rotated, it may affect the result.
>   * Supported file formats: mp4, mov.
>   * Video duration: 5 seconds to 10 minutes.
>   * Resolution: 360p to 3840p. Recommended resolutions are 720p or 1080p.
>   * File size: Less than 300MB.
> * Request Frequency: A maximum of one concurrent upload is supported per second. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/uploadCloneVideo> |
| ------------------ | -------------------------------------------------------------- |
| **Request Method** | post                                                           |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description** |
| ------------------ | -------- | ------------ | --------------- |
| videoUrl           | String   | YES          | Video File URL  |

#### Response Parameters

| **Parameter Name** | **Type** | **Description** |
| ------------------ | -------- | --------------- |
| jobId              | Long     | Task ID         |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/uploadCloneVideo' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "videoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/upload_simple_clone_video/2024/12/a3389d0323cb4f948a9d68f71062efeb.mp4"
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "jobId": 1863777383505321985
    },
    "requestId": "1863777382259613697"
}
```

<br>

### 5.2 Instant Avatar Clone Video Upload Result Query

#### Use Case

> This is used to query the results of the video upload.

#### Notes

> * Usage RestrictionsRequests will fail after the membership expires.
> * Request Frequency: A maximum of 60 concurrent queries per second are supported. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/video/v3/getUploadCloneVideoStatus> |
| ------------------ | ----------------------------------------------------------------------- |
| **Request Method** | post                                                                    |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| **Parameter Name** | **Type** | **Required** | **Description** |
| ------------------ | -------- | ------------ | --------------- |
| jobId              | String   | YES          | Task ID         |

#### Response Parameters

| **Parameter Name**          | **Type**          | **Nested Key**                                | **Type**    | **Description**                                                                                                                                                     |
| --------------------------- | ----------------- | --------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status                      | Integer           | <p><br></p>                                   | <p><br></p> | <p><strong>Status:</strong> </p><ul><li>1 - Waiting for execution </li><li>2 - In progress </li><li>3 - Success </li><li>4 - Failure </li><li>5 - Timeout</li></ul> |
| digitalHuman                | <p>Object<br></p> | digitalHumanId                                | String      | Cloned Digital Human ID                                                                                                                                             |
| digitalHumanThumbnailUrl    | String            | Cloned Digital Human Image File URL           |             |                                                                                                                                                                     |
| digitalHumanPhotoUrl        | String            | Cloned Digital Human Full-body Image File URL |             |                                                                                                                                                                     |
| digitalHumanPreviewVideoUrl | String            | Cloned Digital Human Preview Video File URL   |             |                                                                                                                                                                     |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/video/v3/getUploadCloneVideoStatus' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    
    "jobId": 1866460383784169473
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "status": 3,
        "digitalHuman": {
            "digitalHumanId": 4315,
            "digitalHumanThumbnailUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/talking_photo/results/face_detection/2024/12/10/c6eeb126b6f211efa60f0242ac110005_cover.jpg",
            "digitalHumanPhotoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/image/2024/12/5e4858e0ed4c44d4af2ddcee1effb5d1.png",
            "digitalHumanPreviewVideoUrl": "https://aigc-cdn.kreadoai.com/digitalhuman/api/video/2024/12/4c61e72a680e424c833e542d6599a706.mp4"
        }
    },
    "requestId": "1866461169344892930"
}
```

<br>

## 6. Account Information Query

### 6.1 Membership Expiry Time and K Coin Balance Query

#### Use Case

> This is used for querying membership expiry time and K coin balance information.

#### Notes

> * Usage Restrictions: Requests will fail after the membership expires.
> * Request Frequency: A maximum of 60 concurrent queries per second are supported. Exceeding this will trigger rate-limiting policies.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/user/v3/getInfo> |
| ------------------ | ---------------------------------------------------- |
| **Request Method** | get                                                  |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                 |
| ------------------ | ------------ | --------------------------------- |
| Content-Type       | YES          | application/json                  |
| apiToken           | YES          | 61F3336A8A14FE77EE2DF893058572666 |

#### Response Parameters

| **Parameter Name** | **Type** | **Description**            |
| ------------------ | -------- | -------------------------- |
| balance            | String   | K-Coin Balance             |
| vipExpireTime      | String   | Membership Expiration Time |

#### Example

**Request Example**

```bash
curl --request GET \
--url 'https://api.kreadoai.com/apis/open/user/v3/getInfo' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data ''
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "balance": "138744.00",
        "vipExpireTime": "2026-09-04 15:11:51"
    },
    "requestId": "1862062557001207809"
```

<br>

## 7. Text-to-Speech

### 7.1 Query Supported Languages for Text-to-Speech

#### Use Case

> Retrieve the list of supported languages for text-to-speech functionality.

#### Notes

> * **Request Frequency:** Up to 60 concurrent queries per second are supported. Exceeding this limit will trigger rate limiting.
> * **Usage Restriction:** Requests will fail if the membership has expired.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/voice/v3/getVoiceLanguage> |
| ------------------ | -------------------------------------------------------------- |
| **Request Method** | get                                                            |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                |
| ------------------ | ------------ | -------------------------------- |
| Content-Type       | YES          | application/json                 |
| apiToken           | YES          | 61FDB6A8A14FE77EE2DF893058572EE3 |

<br>

#### Response Parameters

| **Parameter Name**         | **Type** | **Nested Key**                 | **Type**    | **Description**  |
| -------------------------- | -------- | ------------------------------ | ----------- | ---------------- |
| language                   | String   | <p><br></p>                    | <p><br></p> | Language Name    |
| <p>languageDetails<br></p> | Array    | <p><br></p>                    | <p><br></p> | Language Details |
| languageId                 | String   | Language ID                    |             |                  |
| languageEn                 | String   | Language Description (English) |             |                  |
| languageZh                 | String   | Language Description (Chinese) |             |                  |
| languageCityType           | String   | Dialect/Region                 |             |                  |

#### **Example**

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/voice/v3/getVoiceLanguage' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data ''
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": [
        {
            "language": "Chinese",
            "languageDetails": [
                {
                    "languageId": "1767068435121692686",
                    "languageEn": "Chinese",
                    "languageZh": "中文",
                    "languageCityType": "Chinese (Taiwanese Mandarin, Traditional) - 台湾话22"
                },
                {
                    "languageId": "1767068435234938885",
                    "languageEn": "Chinese",
                    "languageZh": "中文",
                    "languageCityType": "Chinese (Northeastern Mandarin, Simplified) - 东北话"
                }
            ]
        }
    ],
    "requestId": "1872576065140785154"
}
```

<br>

### 7.2 Query Supported Voices for Text-to-Speech

#### Use Case

> Retrieve the list of system-supported voice options for text-to-speech.

#### Note

> * **Request Frequency:** Supports up to 60 concurrent queries per second. Exceeding this limit will trigger rate limiting.
> * **Usage Restriction:** Requests will fail if the membership has expired.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/voice/v3/getVoiceList> |
| ------------------ | ---------------------------------------------------------- |
| **Request Method** | post                                                       |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                |
| ------------------ | ------------ | -------------------------------- |
| Content-Type       | YES          | application/json                 |
| apiToken           | YES          | 61FDB6A8A14FE77EE2DF893058572EE3 |

**Body**

| **Parameter Name** | **Type** | **Required**   | **Description**                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| language           | String   | YES            | Language Description (English): Example: Chinese                                                                                                                                                                                                                                                                                                       |
| languageCityType   | String   | NO             | Dialect Region: Specify the region if a particular dialect is required (e.g., Mandarin-China, Cantonese-Hong Kong).                                                                                                                                                                                                                                    |
| gender             | String   | NO             | Gender: female or male                                                                                                                                                                                                                                                                                                                                 |
| ageGroup           | String   | NO             | Age Group: children, young, middle-aged, or old                                                                                                                                                                                                                                                                                                        |
| voiceClone         | Integer  | YES            | Cloned Voice: 0 for No, 1 for Yes                                                                                                                                                                                                                                                                                                                      |
| voiceSource        | Integer  | <p>YES<br></p> | <p>Voice Source: Required when <code>voiceClone = 0</code></p><ul><li><strong>- 1:</strong> Microsoft Voice</li><li><strong>- 3:</strong> Alibaba Voice</li><li><strong>- 4:</strong> ByteDance Voice</li><li><strong>- 5:</strong> MiniMax Voice</li><li><strong>- 6:</strong> Google Voice</li><li><strong>- 21:</strong> ElevenLabs Voice</li></ul> |
| pageIndex          | Integer  | YES            | Page Number                                                                                                                                                                                                                                                                                                                                            |
| pageSize           | Integer  | YES            | Data Per Page                                                                                                                                                                                                                                                                                                                                          |

#### Response Parameters

<table data-header-hidden><thead><tr><th></th><th width="114"></th><th width="121"></th><th width="100"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter Name</strong></td><td><strong>Type</strong></td><td><strong>Nested Key</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>id</td><td>String</td><td><br></td><td><br></td><td>Voice ID</td></tr><tr><td>languageId</td><td>String</td><td><br></td><td><br></td><td>Language ID</td></tr><tr><td>languageCityType</td><td>String</td><td><br></td><td><br></td><td>Dialect/Region</td></tr><tr><td>voiceId</td><td>String</td><td><br></td><td><br></td><td>Voice ID</td></tr><tr><td>voiceName</td><td>String</td><td><br></td><td><br></td><td>Voice Name</td></tr><tr><td>defaultPhotoUrl</td><td>String</td><td><br></td><td><br></td><td>Voice Avatar</td></tr><tr><td>defaultVoiceUrl</td><td>String</td><td><br></td><td><br></td><td>Default Audio</td></tr><tr><td>voiceClone</td><td>Integer</td><td><br></td><td><br></td><td>Cloned Voice: <code>0</code> - No, <code>1</code> - Yes</td></tr><tr><td>voiceSource</td><td>Integer</td><td><br></td><td><br></td><td><p>Voice Source</p><ul><li><strong>- 1:</strong> Microsoft Voice</li><li><strong>- 3:</strong> Alibaba Voice</li><li><strong>- 4:</strong> ByteDance Voice</li><li><strong>- 5:</strong> MiniMax Voice</li><li><strong>- 6:</strong> Google Voice</li><li><strong>- 21:</strong> ElevenLabs Voice</li></ul></td></tr><tr><td>gender</td><td>String</td><td><br></td><td><br></td><td>Gender</td></tr><tr><td>ageGroup</td><td>String</td><td><br></td><td><br></td><td>Age</td></tr><tr><td>voiceStyles</td><td>Array</td><td><br></td><td><br></td><td>Voice Style</td></tr><tr><td>styleId</td><td>String</td><td>Style ID</td><td></td><td></td></tr><tr><td>styleName</td><td>String</td><td>Style Description</td><td></td><td></td></tr></tbody></table>

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/voice/v3/getVoiceList' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "pageIndex": 1,
    "pageSize": 1,
    "language":"Chinese",
    "gender":"male",
    "voiceClone":0,
    "voiceSource":3
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "pageIndex": 1,
        "pageSize": 1,
        "totalCount": 36,
        "totalPages": 36,
        "data": [
            {
                "id": "1784864396515565569",
                "languageId": "1767068435675340832",
                "languageCityType": "Chinese (Mandarin, Simplified) - 普通话",
                "voiceId": "zhida",
                "voiceName": "知达",
                "defaultPhotoUrl": "https://aigc-cdn.kreadoai.com/default_voice_photo/v1/man_teenager/Chinese/Chinese_38.webp",
                "defaultVoiceUrl": "https://aigc-cdn.kreadoai.com/default_voice/audio/2024/4/a5f75b3982744104a7316223ea0bb532.mp3",
                "voiceSource": 3,
                "voiceClone": 0,
                "gender": "male",
                "ageGroup": "young",
                "voiceStyles": []
            }
        ]
    },
    "requestId": "1872576533615181825"
}
```

<br>

### 7.3 Submit Text-to-Speech Synthesis Task

#### Use Case

> Used to generate audio corresponding to the provided text.

#### Notes

> * **Request Frequency:**
>   * Only one request is allowed per second.
>
> **Usage Restrictions:**
>
> * This API is billed separately.
> * Requests will fail if the membership has expired.

#### Request Details

| **Request URL**    | <https://api.kreadoai.com/apis/open/voice/v3/textToSpeech> |
| ------------------ | ---------------------------------------------------------- |
| **Request Method** | post                                                       |

#### Request Parameters

**Header**

| **Parameter Name** | **Required** | **Example Value**                |
| ------------------ | ------------ | -------------------------------- |
| Content-Type       | YES          | application/json                 |
| apiToken           | YES          | 61FDB6A8A14FE77EE2DF893058572EE3 |

**Body**

| **Parameter Name** | **Type**           | **Required** | **Description**                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------ | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| languageId         | String             | YES          | Language ID                                                                                                                                                                                                                                                                                                                                                                                                  |
| content            | String             | YES          | Text Content                                                                                                                                                                                                                                                                                                                                                                                                 |
| voiceId            | String             | YES          | Voice ID                                                                                                                                                                                                                                                                                                                                                                                                     |
| voiceClone         | Integer            | YES          | Cloned Voice: `0` - No, `1` - Yes                                                                                                                                                                                                                                                                                                                                                                            |
| voiceSource        | <p>Integer<br></p> | YES          | <p>Voice Source</p><ul><li><strong>- 1:</strong> Microsoft Voice</li><li><strong>- 3:</strong> Alibaba Voice</li><li><strong>- 4:</strong> ByteDance Voice</li><li><strong>- 5:</strong> MiniMax Voice</li><li><strong>- 6:</strong> Google Voice</li><li><strong>- 21:</strong> ElevenLabs Voice</li></ul>                                                                                                  |
| styleId            | String             | NO           | Style ID                                                                                                                                                                                                                                                                                                                                                                                                     |
| <p>volume<br></p>  | Integer            | NO           | <p>Volume</p><ul><li>voiceSource = 1,Not Set</li><li>voiceSource = 3,Default50,Value Range0~~100(cosyVoice Model：Default50,Value Range 0~~100)</li><li>voiceSource = 4,Default100,Value Range10~~300</li><li>voiceSource = 5,Default1,Value Range0~~10</li><li>voiceSource = 6,Default0,Value Range-96\~16</li><li>voiceSource = 21,Not Set</li></ul>                                                        |
| prosodyRate        | Integer            | NO           | <p>Speed</p><ul><li>voiceSource = 1,Default0,Value Range-100~~0~~200</li><li>voiceSource = 3,Default0,Value Range-500~~500 (cosyVoice Model：Default100，Value Range 50~~200)</li><li>voiceSource = 4,Default100,Value Range20~~300</li><li>voiceSource = 5,Default100,Value Range50~~200</li><li>voiceSource = 6,Default100,Value Range25~~400</li><li>voiceSource = 21,Default50,Value Range0~~100</li></ul> |
| prosodyPitch       | Integer            | NO           | <p>Pitch</p><ul><li>voiceSource = 1,Default0,Value Range-50~~50</li><li>voiceSource = 3,Default0,Value Range-500~~500(cosyVoice Model：Default100，Value Range 50~~200)</li><li>voiceSource = 4,Default100,Value Range10~~300</li><li>voiceSource = 5,Default0,Value Range-120~~120</li><li>voiceSource = 6,Default0,Value Range-20~~20</li><li>voiceSource = 21,Default75,Value Range0\~100</li></ul>         |

#### Response Parameters

| **Parameter Name**      | **Type** | **Nested Key**             | **Type**    | **Description** |
| ----------------------- | -------- | -------------------------- | ----------- | --------------- |
| taskId                  | String   | <p><br></p>                | <p><br></p> | Task ID         |
| <p>textToSpeech<br></p> | Object   | <p><br></p>                | <p><br></p> | <p><br></p>     |
| fileId                  | Integer  | Audio File ID              |             |                 |
| duration                | int      | Audio File Duration        |             |                 |
| audioUrl                | String   | Audio File URL, MP3 format |             |                 |
| paymentMoney            | String   | K-Coins Consumed for TTS   |             |                 |

#### Example

**Request Example**

```bash
curl --location 'https://api.kreadoai.com/apis/open/voice/v3/textToSpeech' \
--header 'apiToken: 61FDB6A8A14FE77EE2DF893058572EE3' \
--header 'Content-Type: application/json' \
--data '{
    "languageId": "1767068435675340832",
    "content": "Kreado-AI提供超过100位数字人形象，快速生成多语种数字人口播视频。集多项AI功能于一身，营销创作更快、更好、更简单。帮助客户降低成本，提高营销增收。",
    "voiceId": "zh_male_jingqiangkanye_moon_bigtts",
    "voiceSource":4,
    "voiceClone": 0,
}'
```

**Response Example**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "taskId": "14689",
        "textToSpeech": {
            "fileId": 1289642,
            "duration": 13,
            "audioUrl": "https://aigc-cdn.kreadoai.com/text_voice/audio/2024/12/265f6e676b074db69105df3f0a03ac08.mp3",
            "paymentMoney": 4
        }
    },
    "requestId": "1872554592623763457"
}
```

## 8. Video Subtitle & Watermark Removal

### **8.1 Submit a Subtitle/Watermark Removal Task**

#### **Use Case**

This API is used to submit a video for automatic subtitle or watermark removal.

#### **Notes**

**Usage Restrictions**

1. Supported video formats: **MP4, MOV**
2. Video duration must be **longer than 5 seconds**
3. Maximum file size: **200MB**
4. Requests will fail if the user’s membership has expired

**Rate Limits**

1. Up to **1 concurrent task submission per second**. Additional requests will be throttled.
2. The server allows a maximum of **4 queued tasks**. Exceeding this limit will result in task submission failure.

#### **Request Details**

**Endpoint**

`https://api.kreadoai.com/apis/open/subtitle_removal/v3/submitTask`

**Method**

`POST`

#### **Request Parameters**

**Headers**

| Parameter    | Required | Example                           |
| ------------ | -------- | --------------------------------- |
| Content-Type | Yes      | application/json                  |
| apiToken     | Yes      | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

<table><thead><tr><th>Parameter</th><th width="130">Type</th><th width="148">Required</th><th>Description</th></tr></thead><tbody><tr><td>taskName</td><td>String</td><td>Yes</td><td>Unique task name, up to 100 characters</td></tr><tr><td>srcFileUrl</td><td>String</td><td>Yes</td><td>URL of the video file (no Chinese or special characters allowed)</td></tr><tr><td>customRectAreaList</td><td>Array</td><td>No</td><td>Coordinates of watermark areas</td></tr><tr><td>rectAreaList</td><td>Array</td><td>No</td><td>Coordinates of subtitle areas</td></tr></tbody></table>

**Coordinate Format (Array items)**

<table><thead><tr><th width="165">Parameter</th><th width="169">Type</th><th width="162">Required</th><th>Description</th></tr></thead><tbody><tr><td>lt_x</td><td>Integer</td><td>Yes</td><td>X-coordinate of the top-left corner</td></tr><tr><td>lt_y</td><td>Integer</td><td>Yes</td><td>Y-coordinate of the top-left corner</td></tr><tr><td>rb_x</td><td>Integer</td><td>Yes</td><td>X-coordinate of the bottom-right corner</td></tr><tr><td>rb_y</td><td>Integer</td><td>Yes</td><td>Y-coordinate of the bottom-right corner</td></tr></tbody></table>

#### **Response Parameters**

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| jobId     | Long | API Task ID |

#### **Example Request**

```bash
curl --location 'https://api.kreadoai.com/apis/open/subtitle_removal/v3/submitTask' \
--header 'apiToken: 61F3336A8A14FE77EE2DF893058572666' \
--header 'Content-Type: application/json' \
--data '{
    "srcFileUrl": "https://aigc-cdn.kreadoai.com/web_static/image/videoSubtitleRemove/sy.mp4",
    "taskName": "Untitled Video (2)",
    "customRectAreaList": [
        {
            "lt_x": 0,
            "lt_y": 0,
            "rb_x": 400,
            "rb_y": 200
        }
    ],
    "rectAreaList": [
        {
            "lt_x": 0,
            "lt_y": 941.212,
            "rb_x": 1068.84,
            "rb_y": 1346.41
        }
    ]
}'
```

#### **Example Response**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "jobId": 1861664658419253250
    },
    "requestId": "1861664651620286466"
}
```

### **8.2 Query Subtitle/Watermark Removal Result**

#### **Use Case**

Retrieve the processing result of a submitted subtitle/watermark removal task.

#### **Notes**

* Requests will fail if the user’s membership has expired
* Rate limit: **up to 60 concurrent queries per second**, excess queries will be throttled

#### **Request Details**

**Endpoint**

`https://api.kreadoai.com/apis/open/subtitle_removal/v3/taskResult`

**Method**

`POST`

#### **Request Parameters**

**Headers**

| Parameter    | Required | Example                           |
| ------------ | -------- | --------------------------------- |
| Content-Type | Yes      | application/json                  |
| apiToken     | Yes      | 61F3336A8A14FE77EE2DF893058572666 |

**Body**

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| jobId     | Long | Yes      | API Task ID |

#### **Response Parameters**

<table><thead><tr><th width="184">Parameter</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td>jobId</td><td>Long</td><td>API Task ID</td></tr><tr><td>businessTaskId</td><td>String</td><td>Subtitle Removal Task ID</td></tr><tr><td>taskName</td><td>String</td><td>Name of the task</td></tr><tr><td>status</td><td>Integer</td><td>Task status: 1-Pending, 2-Processing, 3-Success, 4-Failed, 5-Timeout</td></tr><tr><td>targetVideoUrl</td><td>String</td><td>URL of the processed video (please download promptly; not stored long-term)</td></tr><tr><td>processTime</td><td>Integer</td><td>Processing time (seconds)</td></tr><tr><td>duration</td><td>Integer</td><td>Video duration</td></tr><tr><td>createTime</td><td>String</td><td>Task creation time</td></tr><tr><td>successTime</td><td>String</td><td>Completion time</td></tr></tbody></table>

#### **Example Request**

```bash
curl --location 'https://api.kreadoai.com/apis/open/subtitle_removal/v3/detail' \
--header 'apiToken: 61F3336A8A14FE77EE2DF893058572666' \
--header 'Content-Type: application/json' \
--data '{
    "jobId": "1988133674407751682"
}'
```

#### **Example Response**

```json
{
    "code": "200",
    "message": "Success",
    "data": {
        "jobId": 1989181507324628994,
        "businessTaskId": "1989181524591087618",
        "taskName": "Untitled Video (2)",
        "status": 3,
        "targetVideoUrl": "https://aigc-test-cdn.kreadoai.com/subtitle_removal/2025/11/11/303ec0be7e6a40fa88d99973f5cfcf2c.mp4",
        "processTime": 296,
        "duration": 7,
        "createTime": "2025-11-11T14:36:20",
        "completeTime": "2025-11-11T14:44:11"
    },
    "requestId": "1988434659738996738"
}
```

## 9. Common Status Codes

<table data-header-hidden><thead><tr><th width="242"></th><th></th></tr></thead><tbody><tr><td><strong>Status Code</strong></td><td><strong>Error Message</strong></td></tr><tr><td>200</td><td>Success</td></tr><tr><td>400</td><td>Failed</td></tr><tr><td>405</td><td>To ensure account security, login has expired. Please log in again</td></tr><tr><td>429</td><td>Too many requests, please try again later.</td></tr><tr><td>10001</td><td>Internal system exception.</td></tr><tr><td>10002</td><td>Request parameter error.</td></tr><tr><td>10003</td><td>Audio file download failed.</td></tr><tr><td>10004</td><td>The audio length must be between 1 and 600 seconds.</td></tr><tr><td>10005</td><td>Video file download failed.</td></tr><tr><td>10006</td><td>File download failed.</td></tr><tr><td>10007</td><td>File size is too large.</td></tr><tr><td>10008</td><td>The file content is illegal.</td></tr><tr><td>10009</td><td>Data does not exist.</td></tr><tr><td>10010</td><td>Face check failed.</td></tr><tr><td>10011</td><td>Processing timeout, please try again later.</td></tr><tr><td>10012</td><td>User information does not exist.</td></tr><tr><td>10013</td><td>Failed to generate thumbnail for the video file.</td></tr><tr><td>10014</td><td>The query condition is not supported.</td></tr><tr><td>10015</td><td>Client connection terminated.</td></tr><tr><td>10016</td><td>Order payment failed.</td></tr><tr><td>10017</td><td>Your balance is insufficient. Please recharge and try again.</td></tr><tr><td>10018</td><td>Digital Human video download failed.</td></tr><tr><td>10019</td><td>There are too many tasks queued. Please submit the task later.</td></tr><tr><td>10020</td><td>Digital human information does not exist.</td></tr><tr><td>10021</td><td>The query result is empty. Please contact the administrator.</td></tr><tr><td>10022</td><td>Please upgrade to Pro Membership.</td></tr><tr><td>10999</td><td>Unknown error.</td></tr></tbody></table>

## 9. Contact Us

If you need technical support or wish to learn more about the KreadoAI API, feel free to contact our team!

📧 Email: <support@kreadoai.com>&#x20;

🌐 Website: [www.kreadoai.com](http://www.kreadoai.com)

💬 Whatsapp: +86 135 7289 3712

💬 Skype: <https://join.skype.com/invite/qLThmI6f1RcK><br>