KreadoAI—API V3.0
API Support Documentation
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. Once your account is created, upgrade to the Pro membership to unlock the powerful AI features that allow you to create professional-grade digital avatar videos.
1.2 Access your API key
After logging into your KreadoAI account, navigate to Account Overview -> API Settings to retrieve your API key.
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:
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
Request URL
https://api.kreadoai.com/apis/open/avatar/v3/list
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
cloneDigitalHuman
Integer
YES
Query Digital Human Clone List: 0 - Do not query, 1 - Query
supportTypeId
Integer
YES
Digital Human Type: 100 - Photo, 101 - Video
digitalHumanId
Integer
NO
Digital Human ID
tagIds
List<Integer>
NO
Gender Tags：
211: Female
210: Male
Style Tags：
137: Realistic
138: Featured
139: Premium
areaTypeIds
List<Integer>
NO
Digital Human Region Tag:
141: Western
140: Asian
142: Japanese/Korean
143: Southeast Asian
145: Indian
144: Middle Eastern
146: African
pageIndex
Integer
YES
Page Number
pageSize
Integer
YES
Data Per Page
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
Response Example
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 maximum image size you can upload is 10MB
I have agreed to the "User Terms of Service"
Request Frequency: Supports a maximum of 30 concurrent uploads per second. Exceeding this limit will trigger rate-limiting policies.
Request Details
Request URL
https://api.kreadoai.com/apis/open/avatar/v3/uploadAvatar
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
fileUrl
String
YES
Any publicly accessible image URL that meets the following requirements:
Supported Formats: jpg, jpeg, png, webp
Restrictions: Special characters, such as Chinese or other non-standard symbols, are not allowed in the URL.
Response Parameters
Parameter Name
Type
Description
jobId
Long
Upload photo task ID
Example
Request Example
Response Example
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
Parameter Name
Type
Nested Key
Type
Description
status
Integer
Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
digitalHuman
Object
digitalHumanId
Integer
Digital Human Image ID
supportTypeId
Integer
Digital Human Type:
100 - Photo
101 - Video
digitalHumanThumbnailUrl
String
Thumbnail Avatar
digitalHumanPhotoUrl
String
Full-body Image of Digital Human
digitalHumanPreviewVideoUrl
String
Digital Human Preview Video
Example
Request Example
Response Example
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
Videos must be in mp4 or mov format and use h264 encoding.
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
Response Example
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
Parameter Name
Type
Nested Key
Type
Nested Key
Type
Required
Description
taskName
String
YES
Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
videoRatio
Integer
YES
Video Aspect Ratio:
1 - Represents 16:9 aspect ratio
2 - Represents 9:16 aspect ratio
audio
Object
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.
digitalHuman
Object
digitalHumanId
Integer
YES
Digital Human Image ID
mask
Integer
NO
Mask Type:
0 - No mask
1 - Circular mask
2 - Rectangular mask (This field currently only applies to photo digital humans)
x
Integer
NO
Digital Human Position X-axis Coordinate
y
Integer
NO
Digital Human Position Y-axis Coordinate
background
Object
type
Integer
NO
Background Type:302 - Color background; 303 - User-defined background
color
String
NO
Background Color:When type=302, this field is required. For example, green screen: rgb (0, 255, 0)
backgroundElements
Array
elementType
Integer
NO
Type: 330 - Image; type=303 is required
fileUrl
String
NO
Background image URL (supports PNG, JPEG, JPG, WEBM); type=303 is required
resize
String
NO
Image scaling ratio (up to two decimal places), default: 1.00
Response Parameters
Parameter Name
Type
Description
jobId
Long
Task ID
示例
Request Example
Response Example
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
Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
videoTask
Object
taskId
Integer
Video ID
videoUrl
String
Video File URL
Example
Request Example
Response Example
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
Video Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
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
Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
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
Response Example
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
Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
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
Response Example
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
Response Example
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
Status:
1 - Waiting for execution
2 - In progress
3 - Success
4 - Failure
5 - Timeout
digitalHuman
Object
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
Response Example
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
Response Example
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
Response Parameters
Parameter Name
Type
Nested Key
Type
Description
language
String
Language Name
languageDetails
Array
Language Details
languageId
String
Language ID
languageEn
String
Language Description (English)
languageZh
String
Language Description (Chinese)
languageCityType
String
Dialect/Region
Example
Request Example
Response Example
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
YES
Voice Source: Required when voiceClone = 0
- 1: Microsoft Voice
- 3: Alibaba Voice
- 4: ByteDance Voice
- 5: MiniMax Voice
- 6: Google Voice
- 21: ElevenLabs Voice
pageIndex
Integer
YES
Page Number
pageSize
Integer
YES
Data Per Page
Response Parameters
Parameter Name
Type
Nested Key
Type
Description
id
String
Voice ID
languageId
String
Language ID
languageCityType
String
Dialect/Region
voiceId
String
Voice ID
voiceName
String
Voice Name
defaultPhotoUrl
String
Voice Avatar
defaultVoiceUrl
String
Default Audio
voiceClone
Integer
Cloned Voice: 0 - No, 1 - Yes
voiceSource
Integer
Voice Source
- 1: Microsoft Voice
- 3: Alibaba Voice
- 4: ByteDance Voice
- 5: MiniMax Voice
- 6: Google Voice
- 21: ElevenLabs Voice
gender
String
Gender
ageGroup
String
Age
voiceStyles
Array
Voice Style
styleId
String
Style ID
styleName
String
Style Description
Example
Request Example
Response Example
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/getVoiceLanguage
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
Integer
YES
Voice Source
- 1: Microsoft Voice
- 3: Alibaba Voice
- 4: ByteDance Voice
- 5: MiniMax Voice
- 6: Google Voice
- 21: ElevenLabs Voice
styleId
String
NO
Style ID
volume
Integer
NO
Volume
voiceSource = 1,Not Set
voiceSource = 3,Default50,Value Range0~100(cosyVoice Model：Default50,Value Range 0~100)
voiceSource = 4,Default100,Value Range10~300
voiceSource = 5,Default1,Value Range0~10
voiceSource = 6,Default0,Value Range-96~16
voiceSource = 21,Not Set
prosodyRate
Integer
NO
Speed
voiceSource = 1,Default0,Value Range-100~0~200
voiceSource = 3,Default0,Value Range-500~500 (cosyVoice Model：Default100，Value Range 50~200)
voiceSource = 4,Default100,Value Range20~300
voiceSource = 5,Default100,Value Range50~200
voiceSource = 6,Default100,Value Range25~400
voiceSource = 21,Default50,Value Range0~100
prosodyPitch
Integer
NO
Pitch
voiceSource = 1,Default0,Value Range-50~50
voiceSource = 3,Default0,Value Range-500~500(cosyVoice Model：Default100，Value Range 50~200)
voiceSource = 4,Default100,Value Range10~300
voiceSource = 5,Default0,Value Range-120~120
voiceSource = 6,Default0,Value Range-20~20
voiceSource = 21,Default75,Value Range0~100
Response Parameters
Parameter Name
Type
Nested Key
Type
Description
taskId
String
Task ID
textToSpeech
Object
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
Response Example
8. Common Status Codes
Status Code
Error Message
200
Success
400
Failed
405
To ensure account security, login has expired. Please log in again
429
Too many requests, please try again later.
10001
Internal system exception.
10002
Request parameter error.
10003
Audio file download failed.
10004
The audio length must be between 1 and 600 seconds.
10005
Video file download failed.
10006
File download failed.
10007
File size is too large.
10008
The file content is illegal.
10009
Data does not exist.
10010
Face check failed.
10011
Processing timeout, please try again later.
10012
User information does not exist.
10013
Failed to generate thumbnail for the video file.
10014
The query condition is not supported.
10015
Client connection terminated.
10016
Order payment failed.
10017
Your balance is insufficient. Please recharge and try again.
10018
Digital Human video download failed.
10019
There are too many tasks queued. Please submit the task later.
10020
Digital human information does not exist.
10021
The query result is empty. Please contact the administrator.
10022
Please upgrade to Pro Membership.
10999
Unknown error.
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
🌐 Website: www.kreadoai.com
💬 Whatsapp: +86 135 7289 3712
Last updated