Kling โ
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-videoAuthentication: Tokenhub API Key / Bearer
Kling is a video generation model that supports text- and image-based video generation, as well as Omni multimodal reference generation and video editing. It also provides management APIs for reference characters and voices, helping keep characters and voices consistent.
Basic Information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail removal support | Not supported |
Supported Specifications by Version โ
| Version | Resolution | Aspect ratio | Duration |
|---|---|---|---|
kling-video-v3 | 720p / 1080p / 4k | 16:9 / 9:16 / 1:1 | 3 ~ 15 seconds |
kling-video-v3-omni | 720p / 1080p / 4k | 16:9 / 9:16 / 1:1 | 3 ~ 15 seconds |
kling-video-v3-turbo | 720p / 1080p | 16:9 / 9:16 / 1:1 | 3 ~ 15 seconds |
Input Modes โ
| Version | Input |
|---|---|
kling-video-v3 | Text-to-video / image-to-video (including first and last frames and elements) |
kling-video-v3-omni | Omni video generation (multimodal input of text/image/video and video editing) |
kling-video-v3-turbo | Text-to-video / image-to-video |
Call Procedure โ
Video generation is a time-consuming task, so API uses asynchronous calls, which are divided into the following two steps.
- Submit the task: Call the generation API (text-to-video / image-to-video / Omni). On success,
data.id(task ID) is returned. - Poll for the result: Until
data.status = succeeded, call the task result query API with the task ID, and obtain the video URL from the result.
Text-Based Video Generation โ
API Description โ
Generates a video using only a text prompt. V3 supports multi-shot template syntax (for details, see "Appendix: Multi-Shot Prompt Syntax"), native audio, and 4K output.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model version. Valid values: kling-video-v3, kling-video-v3-turbo |
| prompt | Required | string | Prompt, which can include positive and negative descriptions. V3: โค 3072 characters (โค 2500 recommended), with multi-shot template syntax supported. V3 Turbo: โค 2500 characters. |
| settings | Optional | object | Output configuration. For sub-fields, see the table below (supported fields vary by model). |
| options | Optional | object | General configuration. For sub-fields, see the table below. |
settings sub-fields (by model):
| Sub-field | Applicable model | Description |
|---|---|---|
| resolution | All | Resolution. V3: 720p / 1080p / 4k; V3 Turbo: 720p / 1080p. Default value: 720p. |
| aspect_ratio | All | Aspect ratio. Options: 16:9 / 9:16 / 1:1. Default value: 16:9. |
| duration | All | Duration (seconds). An integer in 3~15. Default value: 5. |
| multi_shot | V3 only | Whether to generate a multi-shot video. Default value: true. When set to false, a multi-shot prompt does not produce multi-shot output. |
| audio | V3 only | Audio. Options: native (generates native audio matching the video) / off (default value). |
Reference: The settings for kling-video-v3-turbo support only the three fields resolution / aspect_ratio / duration. multi_shot and audio are not supported.
options sub-fields:
| Sub-field | Required | Description |
|---|---|---|
| external_task_id | Optional | A custom task ID that is unique within the account. You can query the task by this ID. |
| watermark_info | Optional | Watermark configuration. Structure: {"enabled": true/false}. When true, the watermark is enabled. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "kling-video-v3",
"prompt": "A girl sat on the train, looking out the window, sunlight streaming across her face",
"settings": {
"resolution": "1080p",
"aspect_ratio": "16:9",
"duration": 5,
"audio": "native"
}
}'Reference: To call the corresponding model, replace model in the example with kling-video-v3-turbo. V3 Turbo does not support the audio / multi_shot fields.
Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success; for other values, see Appendix: Unified Error Codes. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | The request ID generated by the system, used for issue tracking and resolution. |
| data | object | Task data object. |
| data.id | string | The task ID generated by the system, used for subsequent task queries. |
| data.status | string | Task status. It is fixed to submitted upon successful submission; subsequent statuses are obtained through the query API. |
| data.message | string | Task status message. When the task fails, it shows the failure reason. |
| data.create_time | long | Task generation time. A Unix timestamp in milliseconds. |
| data.update_time | long | Task update time. A Unix timestamp in milliseconds. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"data": {
"id": "task_xxxxxxxxxxxx",
"status": "submitted",
"message": "",
"create_time": 1714000000000,
"update_time": 1714000000000
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". After a task is submitted successfully, the task status of the generation phase can be obtained through "Task Result Query" API.
| status | Description | Handling recommendation |
|---|---|---|
| processing | Processing (including queuing) | Continue querying the status. |
| succeeded | Generated successfully | Use the video URL in the result. |
| failed | Generation failed | Check and fix the failure reason, then retry. If the failure persists, contact technical support and provide request_id. |
Image-to-Video โ
API Description โ
Uses an image as the first frame (V3 optionally supports a last frame) and combines it with a text prompt to generate a video. V3 also supports element references. The image can be passed in directly as a public URL or Base64, and the output aspect ratio follows the input image.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model version. Valid values: kling-video-v3, kling-video-v3-turbo |
| contents | Required | array | A collection of reference materials. Place the fields of the same material in the same object. At least one prompt and one first_frame must each be included. For sub-fields, see the table below. |
| settings | Optional | object | Output configuration. For sub-fields, see the table below. Reference: Image-to-video has no aspect_ratio parameter; the aspect ratio is determined by the input image. |
| options | Optional | object | General configuration, the same as for text-to-video. |
Sub-fields of the contents array elements:
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Required | string | Material type. Supported scope by model: V3: prompt / first_frame / last_frame / element; V3 Turbo: prompt / first_frame. |
| text | Conditionally required | string | Text prompt. Required when type=prompt. โค 2500 characters. V3 supports multi-shot template syntax and @element references. |
| url | Conditionally required | string | Image asset (URL or Base64). Required when type=first_frame / last_frame. Constraints: .jpg/.jpeg/.png, โค 50 MB, both width and height โฅ 300 px, aspect ratio 1:2.5โ2.5:1. |
| element_id | Conditionally required | string | Element reference (defined by JSON). Required when type=element, and supported only on V3. Maximum 3, referenced as @xxx in the prompt. |
settings sub-fields (by model):
| Sub-field | Applicable model | Description |
|---|---|---|
| resolution | All | Resolution. V3: 720p / 1080p / 4k; V3 Turbo: 720p / 1080p. Default value: 720p. |
| duration | All | Duration (seconds). An integer in 3~15. Default value: 5. |
| multi_shot | V3 only | Whether to generate a multi-shot video. Default value: true. |
| audio | V3 only | Audio. Options: native / off (default value: off). |
Reference: For first and last frames, only "first frame only" and "first frame + last frame" are supported. "Last frame only" is not supported. Do not use element names that are substrings of each other (for example, @Zhang and @ZhangSan).
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "kling-video-v3",
"contents": [
{
"type": "prompt",
"text": "Make the subject in the image turn its head naturally while the camera slowly zooms in"
},
{
"type": "first_frame",
"url": "https://example.com/start.jpg"
}
],
"settings": {
"resolution": "1080p",
"duration": 5
}
}'Response Parameters โ
The same as the output parameters of "Text-to-Video".
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"data": {
"id": "task_xxxxxxxxxxxx",
"status": "submitted",
"message": "",
"create_time": 1714000000000,
"update_time": 1714000000000
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". The task status descriptions are the same as for "Text-to-Video".
Omni Video Generation โ
API Description โ
The unified multimodal generation entry point of V3 Omni. You can comprehensively use prompts, reference images (first/last frames, reference images), reference videos (feature video / base video to be edited), and elements to generate or edit videos.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model version. Value: kling-video-v3-omni |
| contents | Required | array | A collection of multimodal reference materials. Place the fields of the same material in the same object. For sub-fields, see the table below. |
| settings | Optional | object | Output configuration. For sub-fields, see the table below. |
| options | Optional | object | General configuration, the same as for text-to-video. |
Sub-fields of the contents array elements:
| Parameter | Required | Type | Description |
|---|---|---|---|
| type | Required | string | Material type. Enumerated values: prompt / first_frame / last_frame / refer_image / feature_video (feature reference video) / base_video (base video to be edited) / element / voice (timbre). |
| text | Conditionally required | string | Text prompt. Required when type=prompt. โค 3072 characters (โค 2500 recommended). Supports @xxx material references and multi-shot syntax, and voice materials can be referenced via @id. |
| url | Conditionally required | string | Image/video asset. Images support a URL or Base64; videos support only a URL. Image constraints: jpg/jpeg/png, โค 50 MB, width and height โฅ 300 px, aspect ratio 1:2.5โ2.5:1. Video constraints: mp4/mov, โค 200 MB, duration 3~15.5 seconds. |
| element_id | Conditionally required | string | Element ID (generated through element management API). Required when type=element. |
| voice_id | Conditionally required | string | Voice ID. Required when type=voice. Obtain it by querying after generation in "Voice Management", or use a system preset voice. |
| id | Conditionally required | string | Material index ID. Required when type=voice, and it must be unique within the same task. To use this voice, reference it as @id in the prompt. |
settings sub-fields:
| Sub-field | Required | Description |
|---|---|---|
| resolution | Optional | Resolution. 720p / 1080p / 4k. Default value: 720p. |
| aspect_ratio | Conditionally required | Aspect ratio: 16:9 / 9:16 / 1:1, default value 16:9. Required when neither a first frame nor a reference video is provided. |
| duration | Optional | Duration (seconds). An integer in 3~15. Default value: 5. |
| multi_shot | Optional | Whether to generate a multi-shot video. Default value: true. |
| audio | Optional | Audio. Options: native / original / off (default value: off). original = retains the original audio of the reference video. |
**Reference:**Input combination limits: For first and last frames, only "first frame only" and "first frame + last frame" are supported. At most 1 reference video can be provided. feature_video does not support a last frame, and base_video does not support first/last frames or multi-shot. The total of reference images and elements must not exceed 7 when there is no reference video, and must not exceed 4 when there is a reference video. Voices (type=voice) can be referenced up to 2. When a voice is specified, settings.audio cannot be set to off. When feature_video is used, audio can only be off and multi_shot can only be true. When base_video is used, audio cannot be native (it can be original or off), and multi-shot is not supported.
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "kling-video-v3-omni",
"contents": [
{
"type": "prompt",
"text": "Change the color of the parrots feathers to blue, keeping the background unchanged"
},
{
"type": "base_video",
"url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
}
],
"settings": {
"resolution": "1080p",
"duration": 5,
"audio": "original"
}
}'Response Parameters โ
The same as the output parameters of "Text-to-Video".
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"data": {
"id": "task_xxxxxxxxxxxx",
"status": "submitted",
"message": "",
"create_time": 1714000000000,
"update_time": 1714000000000
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". The task status descriptions are the same as for "Text-to-Video".
Element Management โ
Element management is used to generate, query, and delete custom reference objects (custom characters). You can generate a reference object based on multiple reference images (image_refer) or a reference video (video_refer). After generation, in the image-to-video and Omni video generation API you can reference it as element_id to reuse the custom character.
Generating a Reference Object โ
API Description โ
Generates a custom reference object. Generation is an asynchronous task. After submission, poll the task status through "Reference Object Query" API. On success, obtain element_id.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| element_name | Required | string | Element name, up to 20 characters. For example: "my_hero". |
| element_description | Required | string | Element description, up to 100 characters. |
| reference_type | Required | string | Reference method. Values: image_refer (multi-image reference object) / video_refer (video reference object). |
| element_image_list | Conditionally required | object | A multi-image reference object, required when reference_type=image_refer. It includes frontal_image (a frontal image of 1 or more) and refer_images[].image_url (images from other angles or close-ups, 1~3).Images can be passed in as a public URL or Base64. Constraints: jpg/jpeg/png, 10 MB or less, both width and height 300 px or more, aspect ratio 1:2.5โ2.5:1. |
| element_video_list | Conditionally required | object | A video reference object, required when reference_type=video_refer. Structure: {"refer_videos": [{"video_url": "..."}]}. Constraints: MP4/MOV, duration 3~8 seconds, 1080P, aspect ratio 16:9 or 9:16, 200 MB or less. |
| element_voice_id | Optional | string | Associates the ID of an existing voice in the voice library. When empty, no voice is associated. |
| tag_list | Optional | array | Tag configuration, with the structure [{ "tag_id": "o_101" }]. tag_id enumeration: o_101 meme / o_102 person / o_103 animal / o_104 prop / o_105 clothing / o_106 scene / o_107 effect / o_108 other. |
| external_task_id | Optional | string | A custom task ID that is unique within the account. |
Request Examples โ
Multi-image reference object (image_refer):
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"element_name": "my_hero",
"element_description": "A young man with short hair, wearing a blue jacket",
"reference_type": "image_refer",
"element_image_list": {
"frontal_image": "https://example.com/front.jpg",
"refer_images": [
{
"image_url": "https://example.com/side.jpg"
}
]
}
}'Video reference object (video_refer):
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"element_name": "my_hero",
"element_description": "A young man with short hair, wearing a blue jacket",
"reference_type": "video_refer",
"element_video_list": {
"refer_videos": [
{
"video_url": "https://example.com/demo.mp4"
}
]
}
}'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | The request ID generated by the system, used for issue tracking and resolution. |
| data.task_id | string | The task ID generated by the system. |
| data.task_status | string | Task status: submitted / processing / succeed / failed. |
| data.task_info.external_task_id | string | Custom task ID (returned if provided during generation). |
| data.task_status_msg | string | Shows the failure reason when the task fails; an empty string when normal. |
| data.created_at | number | Task generation time. A Unix timestamp in milliseconds. |
| data.updated_at | number | The time the task was last updated. A Unix timestamp in milliseconds. |
| data.final_unit_deduction | string | The final point value deducted for the task. |
| data.final_balance_deduction.quota | string | The discounted price of the quota deduction. |
| data.final_balance_deduction.list_price | string | The list price of the quota deduction. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "02f9537c-9319-4cfb-b347-8f22cb73ffc8",
"data": {
"task_id": "921939922066997283",
"task_status": "submitted",
"task_info": {},
"created_at": 1787836125041,
"updated_at": 1787836125041
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes".
Reference Object Query โ
API Description โ
Queries the status and result of a reference object generation task. After submitting the generation task and receiving the task ID, until the status becomes data.task_status = succeed, poll this API, and obtain the reference object information from data.task_result.elements.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/{id}
Reference: The {id} in the path is the data.task_id returned when the task was generated; it can also be replaced with the external_task_id passed in during generation.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task ID of the element generation task, entered into {id} of the query path. Alternatively, it can be replaced with the external_task_id used during generation. |
Request Example โ
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | The request ID generated by the system, used for issue tracking and resolution. |
| data.task_id | string | The task ID generated by the system. |
| data.task_status | string | Task status: submitted / processing / succeed / failed. |
| data.task_info.external_task_id | string | Custom task ID (returned if provided during generation). |
| data.task_status_msg | string | Shows the failure reason when the task fails; an empty string when normal. |
| data.task_result.elements[] | array | Reference object list. Returned when task_status=succeed. |
| data.task_result.elements[].element_id | number | A globally unique reference object ID. |
| data.task_result.elements[].element_name | string | Reference object name. |
| data.task_result.elements[].element_description | string | Reference object description. |
| data.task_result.elements[].element_type | string | Reference method: image_refer (multi-image reference object) / video_refer (video reference object). |
| data.task_result.elements[].element_image_list | object | Image reference information (available for image_refer). It includes frontal_image and refer_images[].image_url. |
| data.task_result.elements[].element_video_list | object | Video reference information (available for video_refer). |
| data.task_result.elements[].owned_by | string | Reference object source. kling indicates the official reference object library; other values indicate the creator ID. |
| data.task_result.elements[].status | string | Reference object status: succeed (normal) / deleted. |
| data.created_at | number | Task generation time. A Unix timestamp in milliseconds. |
| data.updated_at | number | The time the task was last updated. A Unix timestamp in milliseconds. |
| data.final_unit_deduction | string | The final point value deducted for the task. |
| data.final_balance_deduction.quota | string | The discounted price of the quota deduction. |
| data.final_balance_deduction.list_price | string | The list price of the quota deduction. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "656ee178-de4f-48ea-9763-166bbaa3e4cc-query-1787836129",
"data": {
"task_id": "921939922066997283",
"task_status": "succeed",
"task_info": {},
"task_result": {
"elements": [
{
"element_id": 319807609263140,
"element_name": "Advanced Subject_Image Test",
"element_description": "A young man with short hair, wearing a blue jacket",
"element_type": "image_refer",
"element_image_list": {
"frontal_image": "https://example.com/front.jpg",
"refer_images": [
{
"image_url": "https://example.com/side.jpg"
}
]
},
"element_video_list": {},
"owned_by": "826925436873121851",
"status": "succeed"
}
]
},
"task_status_msg": "",
"created_at": 1787836125041,
"updated_at": 1787836128102,
"final_unit_deduction": "0",
"final_balance_deduction": {
"quota": "0",
"list_price": "0"
}
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". For task failure reasons, see data.task_status_msg.
Deleting a Reference Object โ
API Description โ
Deletes a custom reference object. Only custom elements can be deleted. Official elements (owned_by=kling) cannot be deleted.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| element_id | Required | string | The ID of the element to delete. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"element_id": "319807609263140"
}'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | The request ID generated by the system, used for issue tracking and resolution. |
| data.task_id | string | The task ID generated by the system. |
| data.task_status | string | Task status: submitted / processing / succeed / failed. |
| data.task_status_msg | string | Shows the failure reason when the task fails; an empty string when normal. |
| data.created_at | number | Task generation time. A Unix timestamp in milliseconds. |
| data.updated_at | number | The time the task was last updated. A Unix timestamp in milliseconds. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "dd4a503f-8afd-415d-b3e8-de4c26d4f87a",
"data": {
"task_id": "921939922066997283",
"task_status": "succeed",
"task_info": {},
"task_result": {},
"task_status_msg": "",
"created_at": 1787836125041,
"updated_at": 1787836128102,
"final_unit_deduction": "0",
"final_balance_deduction": {
"quota": "0",
"list_price": "0"
}
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes".
Voice Management โ
Voice management is used to generate, query, and delete custom voices. A voice is generated based on reference audio (or a video that contains audio). After generation, Omni video generation (as a material with type=voice in contents), digital human (avatar), lip sync (advanced-lip-sync), and other API can reference it as voice_id.
Voice generation is an asynchronous task and is divided into the following two steps.
- Submit the task: Call the generation API. On success,
data.task_id(task ID) is returned. - Poll for the result: Until the status becomes
data.task_status = succeed, call the voice task query API with the task ID, and fromdata.task_result.voicesobtainvoice_id.
Generating a Voice โ
API Description โ
Generates a custom voice based on reference audio (or a video that contains audio).
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| voice_name | Required | string | Voice name. |
| voice_url | Conditionally required | string | The public URL of the reference audio. Choose either this parameter or video_id. |
| video_id | Conditionally required | string | The video ID of the video that contains the target audio (a video generated by a video generation task). Choose either this parameter or voice_url. |
| external_task_id | Optional | string | A custom task ID that is unique within the account. |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"voice_name": "Test voice",
"voice_url": "https://example.com/reference.mp3"
}'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | The request ID generated by the system, used for issue tracking and resolution. |
| data.task_id | string | The task ID generated by the system, used for subsequent task queries. |
| data.task_status | string | Task status: submitted / processing / succeed / failed. |
| data.task_info.external_task_id | string | Custom task ID (returned if provided during generation). |
| data.created_at | number | Task generation time. A Unix timestamp in milliseconds. |
| data.updated_at | number | The time the task was last updated. A Unix timestamp in milliseconds. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "a90bd11c-f272-4686-bad9-72310898a217",
"data": {
"task_id": "917124237444943953",
"task_status": "submitted",
"task_info": {},
"created_at": 1786687976483,
"updated_at": 1786687976483
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes".
Voice Task Query โ
API Description โ
Polls the voice generation task with the task ID returned by the generation API. When the task succeeds, obtain voice_id and the preview URL from the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/{task_id}
Reference: The {task_id} in the path is the API-returned data.task_id. It can also be replaced with the external_task_id passed in during generation. Polling every 2~3 seconds is recommended.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task ID (a path parameter), that is, the generation API-returned data.task_id. |
Request Example โ
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | Request ID. |
| data.task_id | string | Task ID. |
| data.task_status | string | Task status: submitted / processing / succeed / failed. |
| data.task_status_msg | string | Task status message. When the task fails, it shows the failure reason. |
| data.task_info.external_task_id | string | Custom task ID (returned if provided during generation). |
| data.task_result.voices[] | array | Voice list. Returned when task_status=succeed. |
| data.task_result.voices[].voice_id | string | Voice ID, used for referencing in API such as digital human and lip sync. |
| data.task_result.voices[].voice_name | string | Voice name. |
| data.task_result.voices[].trial_url | string | The voice preview audio URL is a temporary URL. Download and save it immediately. |
| data.task_result.voices[].owned_by | string | The voice owner identifier. |
| data.task_result.voices[].status | string | Voice status: succeed (normal) / deleted. |
| data.created_at | number | Task generation time. A Unix timestamp in milliseconds. |
| data.updated_at | number | The time the task was last updated. A Unix timestamp in milliseconds. |
| data.final_unit_deduction | string | The number of units deducted for this task. |
| data.final_balance_deduction.quota | string | The discounted price of the quota deduction. |
| data.final_balance_deduction.list_price | string | The list price of the quota deduction. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "8efcf51b-4637-4616-a21b-436501eaef96-query-1786687983",
"data": {
"task_id": "917124237444943953",
"task_status": "succeed",
"task_info": {},
"task_result": {
"voices": [
{
"voice_id": "917124264959582304",
"voice_name": "Test voice",
"trial_url": "https://example.com/voice-trial.wav",
"owned_by": "826925436873121851",
"status": "succeed"
}
]
},
"task_status_msg": "",
"created_at": 1786687976483,
"updated_at": 1786687982942,
"final_unit_deduction": "0.05",
"final_balance_deduction": {
"quota": "0",
"list_price": "0"
}
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". For task failure reasons, see data.task_status_msg.
Deleting a Voice โ
API Description โ
Deletes the specified custom voice. Only custom voices can be deleted. After deletion, the voice can no longer be referenced in the generation API.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| voice_id | Required | string | The voice ID to delete (the query API-returned voice_id). |
Request Example โ
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"voice_id": "917124264959582304"
}'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. On success, it is "SUCCEED". |
| request_id | string | Request ID. |
| data.task_id | string | The generation task ID corresponding to the voice. |
| data.task_status | string | Task status: submitted / processing / succeed / failed. |
| data.task_result | object | The deletion result object (usually an empty object {}, indicating that the deletion succeeded). |
| data.task_status_msg | string | Shows the failure reason when the task fails; an empty string when normal. |
| data.created_at | number | Task generation time. A Unix timestamp in milliseconds. |
| data.updated_at | number | The time the task was last updated. A Unix timestamp in milliseconds. |
Response Example โ
{
"code": 0,
"message": "SUCCEED",
"request_id": "b641fc55-7f23-41e5-8155-2fa371c3d871",
"data": {
"task_id": "917124237444943953",
"task_status": "succeed",
"task_info": {},
"task_result": {},
"task_status_msg": "",
"created_at": 1786687976483,
"updated_at": 1786687982942,
"final_unit_deduction": "0.05",
"final_balance_deduction": {
"quota": "0",
"list_price": "0"
}
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes".
Task Result Query โ
API Description โ
The task query method shared by all generation API (text-to-video / image-to-video / unified). After submitting a task and receiving the task ID, poll the task status through the unified task query endpoint. On success, obtain the video URL from the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/{task_id}
Reference: The {task_id} in the path is the data.id returned when the task was submitted. Video generation takes about a few minutes, so polling every 3~5 seconds is recommended. The response fields are provided according to the official Kling API structure; the actual returned response takes precedence.
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| task_id | Required | string | The task ID (a path parameter), which is the data.id returned when the task was submitted. |
Request Example โ
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| code | int | Business error code. 0 indicates success. |
| message | string | Error or informational message. |
| request_id | string | Request ID. |
| data | array | Task result list. |
| data[].id | string | Task ID. |
| data[].status | string | Task status: processing / succeeded / failed. |
| data[].message | string | Task status message. When the task fails, it shows the failure reason. |
| data[].outputs | array | Video result list. |
| data[].outputs[].type | string | Generation result type. Currently, the video result is video. |
| data[].outputs[].id | string | Video ID. |
| data[].outputs[].url | string | The video file URL is a temporary URL. Download and save it immediately. |
| data[].outputs[].duration | string | Video duration (seconds). |
| data[].create_time | long | Task generation time. A Unix timestamp in milliseconds. |
| data[].update_time | long | Task update time. A Unix timestamp in milliseconds. |
| tokenhub_usage | object | Usage. |
| tokenhub_usage.total_tokens | integer | The number of tokens consumed by this task, used for billing/settlement. |
Response Example โ
{
"code": 0,
"data": [
{
"update_time": 1786429168170,
"create_time": 1786428992000,
"id": "251435731-WandVideo-7d1997fb7ad74bfabd2814b4a9962571",
"message": "",
"outputs": [
{
"duration": "10.041",
"id": "916037982829322296",
"type": "video",
"url": "https://example.com/output-video.mp4?q-sign-algorithm=sha1&q-signature=xxxxxx"
}
],
"status": "succeeded"
}
],
"message": "SUCCEED",
"request_id": "5d0b35d5-da56-4dae-8e6c-81035122e716-query-1786429167",
"tokenhub_usage": {
"total_tokens": 600000
}
}Error Codes โ
When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". The task status descriptions are the same as for "Text-to-Video".
Appendix โ
Unified Error Codes โ
| HTTP status code | Business code | Error message | Description |
|---|---|---|---|
200 | 0 | success | Request succeeded |
401 | 1000 | Authentication failed | Authorization is missing or the apikey is invalid. |
401 | 1001 | Authorization is empty | The Authorization header is not included. |
401 | 1002 | Authorization is invalid | The apikey is invalid or has expired. |
401 | 1003 | Authorization is not yet valid | The apikey is not yet valid. |
401 | 1004 | Authorization expired | The apikey has expired. |
429 | 1100 | Account exception | Account exception (the account may be overdue, suspended, or blocked) |
429 | 1101 | Account overdue (postpaid) | The postpaid account payment is overdue. |
429 | 1102 | Resource pack exhausted or expired | The resource pack has been fully used or has expired. |
403 | 1103 | Access to the requested resource denied | The requested resource cannot be accessed (the corresponding model/feature is not subscribed). |
400 | 1200 | Invalid request parameter | The request parameters are incorrect (missing required fields, incorrect type, enumerated value out of range, and so on). |
400 | 1201 | Invalid parameter | The parameter value is incorrect. Check the valid value range in the documentation. |
404 | 1202 | The requested method is invalid | The HTTP method is incorrect. |
404 | 1203 | The requested resource does not exist | The endpoint path is incorrect or the resource does not exist. |
400 | 1300 | Platform policy triggered | A platform policy was triggered (content moderation failure or non-compliant input, and so on). |
400 | 1301 | Platform sensitive word list triggered | A sensitive word or a non-compliant prompt was detected. |
429 | 1302 | API calls are too frequent | The call frequency is too high, and rate limiting has been applied. |
429 | 1303 | Concurrency or QPS limit exceeded | Concurrency or QPS exceeded the preset quota. |
400 | 1304 | IP policy triggered | Blocking based on the IP address policy was triggered. |
500 | 5000 | Internal server error | Internal server error |
503 | 5001 | The server is temporarily unavailable | The service is temporarily unavailable (usually due to high load or maintenance). |
504 | 5002 | Internal server timeout | Internal server timeout |
Multi-Shot Prompt Syntax โ
- Format:
shot n, m, words; shot n, m, words;. Separate each shot with a half-width semicolon. n: Shot number. A minimum of1and a maximum of6shots are supported.m: Shot duration (seconds). Each shot must be at least1 second, and the sum of all shot durations must equal the total video duration.words: The prompt for this shot. Maximum length:512characters.- The maximum length of the entire prompt is
3072characters (2500characters or fewer recommended). Both positive and negative descriptions are supported. - Only
kling-video-v3andkling-video-v3-omnisupport this feature, andmulti_shot=true(the default value) is required for it to take effect.
General Constraints for Image Assets โ
Formats: .jpg / .jpeg / .png (transparent channels are not supported). File size: 50 MB or less. Width and height: at least 300 px each. Aspect ratio: 1:2.5โ2.5:1. URL or Base64 input is supported.
FAQ โ
1. Which of the three models should I choose? โ
- The most comprehensive option in terms of features, including
4K/ native audio / multi-shot / element support:kling-video-v3. - Multimodal mixed input and video editing (reference video, base video rewriting):
kling-video-v3-omni. - Batch generation that prioritizes speed and cost:
kling-video-v3-turbo(audio and multi-shot are not supported).
2. Can I specify the aspect ratio for image-to-video? โ
No. The output aspect ratio of image-to-video is determined by the input image, and the aspect_ratio parameter cannot be used. Only text-to-video and Omni video generation support this parameter, and in Omni video generation it is required when neither a first frame nor a reference video is provided.
3. What is a custom element and how do I use it? โ
An element is a custom visual reference object (for example, a character) generated from multiple reference images (image_refer) or a reference video (video_refer). Once generated through element management API, you obtain element_id, and you can reference it in image-to-video and Omni video generation to maintain character consistency across tasks. Reference the element as @ElementName in the prompt, and do not use element names that are substrings of each other.
4. What is a custom voice and how do I use it? โ
A voice is a custom sound reference object generated from reference audio (or a video that contains audio). Once generated through voice management API, you obtain voice_id, and you can reference it in API such as Omni video generation, digital human (avatar), and lip sync (advanced-lip-sync). The trial_url in the query result is a temporary preview URL, so download and save it immediately.