tencent cloud

LLM Service TokenHub

DocumentaçãoLLM Service TokenHubAPI Integration GuideVideo Generation ModelKling Video Generation API Guide

Kling Video Generation API Guide

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-10-16 21:32:32
Traduzido e Verificado por IA

Overview

Kling is a video generation model series launched by Kuaishou. It supports text-to-video, image-to-video, Omni video generation, and motion control capabilities, and provides element management (custom subjects) and voice management (custom voices) APIs.
This document describes how to call Kling models through TokenHub: kling-video-v3, kling-video-v3-turbo, kling-video-v3-omni, kling-video-motion-control-v3.0, and kling-video-motion-control-v2.6.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Enable postpaid billing for the corresponding model in Console - Online Inference - Vision Models.
Note:
In all examples below, YOUR_API_KEY must be replaced with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.

Call Process

Video generation is a time-consuming task, so the API uses an asynchronous call mode, which is divided into two steps:
1. Submit a task: Call the generation API (text-to-video/image-to-video/Omni), which returns data.id (task ID) upon success.
2. Poll for results: Call the query task result API with the task ID until data[].status = succeeded, and obtain the video URL from the result.

Model List

Model Name
model Parameter Value
Supported Capability
Video Duration (s)
Resolution Tier
Aspect Ratio (Text-to-Video/Omni)
Selection Recommendations
Kling-Video-V3
kling-video-v3
Text-to-video / image-to-video (including first-last frame and element)
3 ~ 15
720p / 1080p / 4k
16:9,9:16,1:1
Flagship model: supports native audio, multi-shot, element reference, and 4K, with the most comprehensive capabilities.
Kling-Video-V3-omni
kling-video-v3-omni
Omnipotent video generation (multimodal input of text/image/video, and video editing)
3 ~ 15
720p / 1080p / 4k
16:9,9:16,1:1
Scenarios requiring multimodal mixed inputs such as reference video and video editing.
Kling-Video-V3-turbo
kling-video-v3-turbo
Text-to-video / image-to-video
3 ~ 15
720p / 1080p
16:9,9:16,1:1
V3 fast version, faster generation and lower cost, suitable for batch generation; simplified parameters (no audio or multi-shot).
Kling-Video-Motion-Control-V3.0
kling-video-motion-control-v3.0
Motion control (subject reference image + motion reference video, with subject referencing support)
Follow the action reference video (3 to 30s)
720p / 1080p
Follow the input material
Make the character in the subject reference image replicate the actions from the reference video; supports referencing one subject.
Kling-Video-Motion-Control-V2.6
kling-video-motion-control-v2.6
Motion control (subject reference image + motion reference video)
Follow the action reference video (3 to 30s)
720p / 1080p
Follow the input material
Previous generation of motion control, without subject reference support.
Note:
The "Aspect Ratio" column lists the supported value ranges for text-to-video and Omni video generation. Image-to-video and first-last-frame video generation do not have the aspect_ratio parameter, and the output aspect ratio follows the input image ratio. Motion control also does not have the aspect_ratio parameter, and the output aspect ratio follows the input material.

Text-to-Video

1. API Description

Generate videos using only text prompts. 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

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model version. Value range: kling-video-v3, kling-video-v3-turbo
prompt
Yes
string
Prompt, which can include positive and negative descriptions. V3: ≤ 3072 characters (≤ 2500 recommended), supporting multi-shot template syntax; V3 Turbo: ≤ 2500 characters.
settings
No
object
Output configuration. See the table below for subfields (supported fields vary by model).
options
No
object
General configuration. See the table below for subfields.
settings subfields (by model):
Subfield
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 in seconds. An integer from 3 to 15. Default value: 5.
multi_shot
V3 only
Whether to generate multi-shot video. Default value: true. When set to false, multi-shot prompts do not produce multi-shot output.
audio
V3 only
Audio. Options: native (generates native audio that matches the video) / off (default).
Note:
The settings of kling-video-v3-turbo support only three fields: resolution / aspect_ratio / duration. multi_shot and audio are not supported.
options subfields:
Subfield
Required
Description
external_task_id
No
Custom task ID, unique within the account, supports querying tasks by this ID.
watermark_info
No
Watermark configuration. Structure: {"enabled": true/false}, where true enables the watermark.

3. Sample Request

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"
  }
}'
Note:
Replace model in the example with kling-video-v3-turbo to call the corresponding model. Note that V3 Turbo does not support the audio / multi_shot fields.

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success, and for other values, see Appendix: Unified Error Codes.
message
string
Error or prompt information; "SUCCEED" on success.
request_id
string
Request ID generated by the system, used for issue tracking and troubleshooting.
data
object
Task data object.
data.id
string
Task ID generated by the system, used for subsequent task queries.
data.status
string
Task status; fixed as submitted upon successful submission, and subsequent statuses are obtained through the query API.
data.message
string
Task status information; displays the failure reason when the task fails.
data.create_time
long
Task creation time; Unix timestamp in milliseconds.
data.update_time
long
Task update time; Unix timestamp in milliseconds.

5. Sample Response

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". After a task is submitted successfully, the task status during the generation phase can be obtained through the "Query Task Result" API:
status
Description
Handling Recommendation
processing
Processing (including queued)
Keep polling.
succeeded
Generation succeeded
Obtain the video URL from the query result.
failed
Generation failed
Check the failure cause, make modifications, and retry. If the failure persists, contact technical support and provide the request_id.

Image-to-Video

1. API Description

Generate videos using an image as the first frame (V3 optionally supports the last frame) combined with text prompts. V3 additionally supports Element references. Images can be passed directly as public URLs or Base64, and the output aspect ratio follows the input image.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model version. Value range: kling-video-v3, kling-video-v3-turbo
contents
Yes
array
A collection of reference materials. Place fields of the same material in the same object. It must contain at least one prompt and one first_frame. See the table below for sub-fields.
settings
No
object
Output configuration. See the table below for sub-fields. Note: Image-to-video does not have the aspect_ratio parameter, and the aspect ratio is determined by the input image.
options
No
object
General configuration, same as that for text-to-video.
Subfields of contents array elements:
Parameter Name
Required
Type
Description
type
Yes
string
Material type. Supported by each 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 contents[].url (type=first_frame/last_frame): supports 1-2 image inputs, supports URL and Base64 formats. Image format: jpg/jpeg/png, width and height ≥300 px, aspect ratio 1:2.5~2.5:1; single image size <=50 MB.
1) Base64: total size of all images <75 MB, and total size after Base64 conversion <=100 MB; format requirement: data:image/<image format>;base64,<Base64 encoding>.
2) URL: must be publicly accessible (http/https).
element_id
Conditionally required
string
Element reference (JSON definition). Required when type=element, V3 only; up to 3, referenced in prompt as @xxx.
settings subfields (by model):
Subfield
Applicable Model
Description
resolution
All
Resolution. V3: 720p / 1080p / 4k; V3 Turbo: 720p / 1080p. Default value: 720p.
duration
All
Duration in seconds. An integer from 3 to 15. Default value: 5.
multi_shot
V3 only
Whether to generate multi-shot video. Default value: true.
audio
V3 only
Audio. Options: native / off (default: off).
Note:
First and last frames support only "first frame only" and "first frame + last frame". "Last frame only" is not supported.
Avoid element names that are substrings of each other (for example, @Zhang and @ZhangSan).

3. Sample Request

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

4. Output Parameters

Same as the output parameters of "Text-to-Video".

5. Sample Response

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". The task status description is the same as that in "Text-to-Video".

Omni Video Generation

1. API Description

The unified multimodal generation entry point of V3 Omni: it can generate or edit videos by comprehensively using prompts, reference images (first/last frames, reference images), reference videos (feature videos / base videos to be edited), and elements.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model version. Value: kling-video-v3-omni
contents
Yes
array
A collection of multimodal reference materials. Place fields of the same material in the same object. See the table below for sub-fields.
settings
No
object
Output configuration. See the table below for subfields.
options
No
object
General configuration, same as that for text-to-video.
Subfields of contents array elements:
Parameter Name
Required
Type
Description
type
Yes
string
Material type. Enum 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 (recommended ≤ 2500); supports @xxx material references and multi-shot syntax; can reference voice materials through @id.
url
Conditionally required
string
Image/video asset. Images support URL or Base64; videos support URL only. Image constraints: jpg/jpeg/png, ≤ 50 MB, width and height ≥ 300 px, aspect ratio 1:2.5 to 2.5:1. Video constraints: mp4/mov, ≤ 200 MB, duration 3 to 15.5 seconds.

Image contents[].url (type=first_frame / last_frame / refer_image): supports 1-2 image inputs, supports URL and Base64 formats. Image format: jpg/jpeg/png, width and height ≥300 px, aspect ratio 1:2.5~2.5:1; single image size <=50 MB.
1) Base64: total size of all images <75 MB, and total size after Base64 conversion <=100 MB; format requirement: data:image/<image format>;base64,<Base64 encoding>. Note: when the image is jpg, fill in jpeg as the image format.
2) URL: must be publicly accessible (http/https).

Video contents[].url (type=feature_video/base_video): supports 1-6 video inputs, supports URL and Base64 formats. Video format: mp4/mov, video duration 3-15.5 seconds, video width and height should be between 700 pixels and 4553 pixels, total pixel area <= 8294400. Video aspect ratio should be between 0.4 and 2, video frame rate based on 24fps to 60fps, up to 1 reference video can be added, and after a reference video is added, up to one video character element can be added; single file size <=200 MB.
1) Base64: total size of all videos <=75 MB, and total size after Base64 conversion <=100 MB; format requirement: data:video/<video format>;base64,<Base64 encoding>. Note: when the video is mov, fill in quicktime as the video format.
2) URL: must be publicly accessible (http/https).
element_id
Conditionally required
string
Element ID (created through the element management API). Required when type=element.
voice_id
Conditionally required
string
Voice ID. Required when type=voice. Obtained by querying after creation in "Voice Management", or use system preset voices.
id
Conditionally required
string
Material index ID. Required when type=voice; must be unique within the same task, and referenced in the prompt as @id to use this voice.
settings subfields:
Subfield
Required
Description
resolution
No
Resolution. 720p / 1080p / 4k. Default value: 720p.
aspect_ratio
Conditionally required
Aspect ratio: 16:9 / 9:16 / 1:1, default 16:9. Required when there is no first frame and no reference video.
duration
No
Duration in seconds. An integer from 3 to 15. Default value: 5.
multi_shot
No
Whether to generate multi-shot video. Default value: true.
audio
No
Audio. Options: native / original / off (default: off). original=retains the original audio of the reference video.
Note:
Input combination restrictions:
First and last frames support only "first frame only" and "first frame + last frame".
You can provide at most one reference video. feature_video does not support the last frame, and base_video does not support first/last frames or multiple shots.
Reference images and elements: the total number must not exceed 7 when no reference video is provided, and must not exceed 4 when a reference video is provided.
You can reference at most 2 voices (type=voice). When a voice is specified, settings.audio cannot be 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 multiple shots are not supported.

3. Sample Request

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://example.com/input.mp4"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "audio": "original"
  }
}'

4. Output Parameters

Same as the output parameters of "Text-to-Video".

5. Sample Response

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". The task status description is the same as that in "Text-to-Video".

Motion Control

1. API Description

Use a motion reference video to drive the character in the image reference to generate a video with motions consistent with the reference video. In V3.0, you can also directly specify a custom character through an Element.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/motion-control

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model version. Value range: kling-video-motion-control-v3.0, kling-video-motion-control-v2.6
contents
Yes
array
A collection of reference materials, which must include a subject reference image and an action reference video, with prompt words and reference subjects optional. See the table below for subfields.
settings
Yes
object
Output configuration. See the table below for subfields.
options
No
object
General configuration, same as that for text-to-video.
Subfields of contents array elements:
Parameter Name
Required
Type
Description
type
Yes
string
Material type. Enum values: prompt (text prompt) / image (image reference) / video (motion reference video) / element (reference subject).
text
Conditionally required
string
Text prompt. Required when type=prompt. No more than 2500 characters. You can use prompts to add elements to the frame and achieve camera movement effects. It is recommended not to describe motion, as motion is determined by the reference video.
url
Conditionally required
string
Asset content. Required when type=image or type=video. Images support URL or Base64 input; videos support URL only.
element_id
Conditionally required
string
Element ID (created through the element management API). Required when type=element. Supported only by kling-video-motion-control-v3.0, with a maximum of 1 subject specified.
id
Conditionally required
string
Material index ID. Required when type=element, used to specify in the prompt; must be unique within the same task.
Material format constraints:
Asset
Format
Size
Size
Duration
Character reference image (type=image)
.jpg / .jpeg / .png
≤ 50MB
Width and height both ≥ 300px, aspect ratio 1:2.5 to 2.5:1
-
Motion reference video (type=video)
.mp4 / .mov
≤ 100MB
Width and height between 340px and 3850px (inclusive)
No shorter than 3 seconds. For the upper limit, see the description below.
settings subfields:
Subfield
Required
Description
character_orientation
Yes
Orientation of the character in the generated video. Enum values: image (consistent with the character in the image reference) / video (consistent with the character in the motion reference video).
audio
No
Whether to generate a video with audio. Options: original (retains the original audio of the reference video, default) / off (the generated video contains no audio).
resolution
No
Resolution of the generated video. Options: 720p (default) / 1080p.
Note:
The maximum duration of the motion reference video is related to settings.character_orientation:
image (orientation consistent with the image): The reference video can be up to 10 seconds long.
video (orientation consistent with the video): The reference video can be up to 30 seconds long.
Image reference content requirements: Keep the character proportions in the image as consistent as possible with those in the reference video. Avoid using full-body motions to drive a half-body character. The character must show a clear upper body or full-body limbs and head without occlusion. Avoid extreme orientations such as upside-down or lying flat. The character must not occupy too small a proportion of the frame. Realistic and stylized characters are supported, including humans, humanoid animals, some non-humanoid animals, and characters with partially humanoid limb proportions.
Motion reference video content requirements: Upload a single-person motion video. If the video contains two or more people, the motion of the person occupying the largest frame area is used. Real human motion is recommended. The motion must be captured in a single continuous shot with the character always visible in the frame. Avoid cuts and camera movements, otherwise the video will be truncated. Excessively fast motion can significantly affect the result. When the motion is highly difficult or fast, the generated video may be shorter than the uploaded video because the model extracts only the valid motion duration, with a minimum of 3 seconds of usable continuous motion required for generation. Credits are deducted based on the duration of the output video.
API limits:
When a subject (element) is referenced, the generated video can only reference the character orientation in the video.
This API does not have a duration parameter, and the output duration follows the motion reference video.

3. Sample Request

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/motion-control' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-motion-control-v3.0",
  "contents": [
    {
      "type": "prompt",
      "text": "The girl is wearing a loose gray T-shirt and denim shorts"
    },
    {
      "type": "image",
      "url": "https://example.com/character.png"
    },
    {
      "type": "video",
      "url": "https://example.com/motion.mp4"
    }
  ],
  "settings": {
    "character_orientation": "video",
    "resolution": "1080p"
  }
}'
Note:
To reference a subject (Element), append an item {"type": "element", "element_id": "ElementID", "id": "e1"} to contents. This is supported only by kling-video-motion-control-v3.0, with a maximum of 1.

4. Output Parameters

Same as the output parameters of "Text-to-Video".

5. Sample Response

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". The task status description is the same as that in "Text-to-Video".

Element Management

Element Management is used to create, query, and delete custom subjects (customized characters). A subject can be created based on multiple reference images (image_refer) or a reference video (video_refer). After creation, it can be referenced through element_id in the Image-to-Video and Omni Video Generation APIs to reuse the customized character.

Creating a Principal

1. API Description

Create a custom subject. The creation is an asynchronous task. After submission, poll the task status through the "Query Subject" API. Upon success, you will obtain the element_id.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements

2. Input Parameters

Parameter Name
Required
Type
Description
element_name
Yes
string
Element name, up to 20 characters. Example: "my_hero".
element_description
Yes
string
Element description, up to 100 characters.
reference_type
Yes
string
Reference method. Values: image_refer (multi-image subject) / video_refer (video subject).
element_image_list
Conditionally required
object
Multi-image reference object, required when reference_type=image_refer. Contains frontal_image (at least 1 front image) and refer_images[].image_url (1 to 3 images from different angles or close-ups). Images can be passed in via public URL or Base64. Constraints: jpg/jpeg/png, no more than 10 MB, width and height greater than or equal to 300 px, aspect ratio between 1:2.5 and 2.5:1.
element_video_list
Conditionally required
object
Video reference object, required when reference_type=video_refer. Structure: {"refer_videos": [{"video_url": "..."}]}. Constraints: MP4/MOV, duration 3 to 8 seconds, 1080P, aspect ratio 16:9 or 9:16, no more than 200 MB.
element_voice_id
No
string
Binds the ID of an existing voice in the voice library. If empty, no voice is bound.
tag_list
No
array
Tag configuration, 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
No
string
Custom task ID, unique within the account.

3. Sample Request

Multi-image subject (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 subject (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" }
    ]
  }
}'

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information; "SUCCEED" on success.
request_id
string
Request ID generated by the system, used for issue tracking and troubleshooting.
data.task_id
string
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 at creation).
data.task_status_msg
string
Displays the failure reason when the task fails, and is an empty string in normal cases.
data.created_at
number
Task creation time, Unix timestamp in milliseconds.
data.updated_at
number
Task last update time, Unix timestamp in milliseconds.
data.final_unit_deduction
string
Final deducted points value for the task.
data.final_balance_deduction.quota
string
Discounted price for quota deduction.
data.final_balance_deduction.list_price
string
List price for quota deduction.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes".

Querying a Principal

1. API Description

Query the status and result of the subject creation task. After submitting the creation task and receiving the task ID, poll through this API until data.task_status = succeed, and obtain the subject information from data.task_result.elements[].
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/{id}
Note:
The {id} in the path is the data.task_id returned when the task was created, and it can also be replaced by the external_task_id passed in at creation time.

2. Input Parameters

Parameter Name
Required
Type
Description
task_id
Yes
string
Task ID of the element creation task, which is filled into the query path {id}; alternatively, it can be replaced by the external_task_id used at creation.

3. Sample Request

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information; "SUCCEED" on success.
request_id
string
Request ID generated by the system, used for issue tracking and troubleshooting.
data.task_id
string
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 at creation).
data.task_status_msg
string
Displays the failure reason when the task fails, and is an empty string in normal cases.
data.task_result.elements[]
array
List of subjects, returned when task_status=succeed.
data.task_result.elements[].element_id
number
Subject ID, globally unique.
data.task_result.elements[].element_name
string
Subject name.
data.task_result.elements[].element_description
string
Subject description.
data.task_result.elements[].element_type
string
Reference method: image_refer (multi-image subject) / video_refer (video subject).
data.task_result.elements[].element_image_list
object
Image reference information (available for image_refer). Contains 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
Subject source; kling indicates the official subject library, and other values indicate the creator ID.
data.task_result.elements[].status
string
Subject status: succeed (normal) / deleted.
data.created_at
number
Task creation time, Unix timestamp in milliseconds.
data.updated_at
number
Task last update time, Unix timestamp in milliseconds.
data.final_unit_deduction
string
Final deducted points value for the task.
data.final_balance_deduction.quota
string
Discounted price for quota deduction.
data.final_balance_deduction.list_price
string
List price for quota deduction.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". For the reason of task failure, see data.task_status_msg.

Deleting a Principal

1. API Description

Delete a custom subject. 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

2. Input Parameters

Parameter Name
Required
Type
Description
element_id
Yes
string
ID of the element to delete.

3. Sample Request

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

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information; "SUCCEED" on success.
request_id
string
Request ID generated by the system, used for issue tracking and troubleshooting.
data.task_id
string
Task ID generated by the system.
data.task_status
string
Task status: submitted / processing / succeed / failed.
data.task_status_msg
string
Displays the failure reason when the task fails, and is an empty string in normal cases.
data.created_at
number
Task creation time, Unix timestamp in milliseconds.
data.updated_at
number
Task last update time, Unix timestamp in milliseconds.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes".

Voice Management

Voice Management is used to create, query, and delete custom voices. A voice is created based on a reference audio (or a video containing audio). After creation, it can be referenced through voice_id in APIs such as Omni Video Generation (materials with type=voice in contents), Digital Human (avatar), and Lip Sync (advanced-lip-sync).
Voice creation is an asynchronous task and is divided into two steps:
1. Submit a task: Call the creation API, which returns data.task_id (task ID) upon success.
2. Poll for results: Call the query voice task API with the task ID until data.task_status = succeed, and obtain the voice_id from data.task_result.voices[].

Creating a Voice

1. API Description

Create a custom voice based on a reference audio (or a video containing audio).
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices

2. Input Parameters

Parameter Name
Required
Type
Description
voice_name
Yes
string
Voice name.
voice_url
Conditionally required
string
Public URL of the reference audio. Select either this parameter or video_id.
video_id
Conditionally required
string
Video ID of the video that contains the target audio (a video generated by a video generation task). Select either this parameter or voice_url.
external_task_id
No
string
Custom task ID, unique within the account.

3. Sample Request

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

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information; "SUCCEED" on success.
request_id
string
Request ID generated by the system, used for issue tracking and troubleshooting.
data.task_id
string
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 at creation).
data.created_at
number
Task creation time, Unix timestamp in milliseconds.
data.updated_at
number
Task last update time, Unix timestamp in milliseconds.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes".

Querying Voice Tasks

1. API Description

Poll the voice creation task with the task ID returned by the creation API. After the task succeeds, obtain the voice_id and preview URL from the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/{task_id}
Note:
The {task_id} in the path is the data.task_id returned by the creation API. It can also be replaced by the external_task_id passed in at creation time. Polling every 2 to 3 seconds is recommended.

2. Input Parameters

Parameter Name
Required
Type
Description
task_id
Yes
string
Task ID (path parameter), which is the data.task_id returned by the creation API.

3. Sample Request

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information; "SUCCEED" on success.
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 information; displays the failure reason when the task fails.
data.task_info.external_task_id
string
Custom task ID (returned if provided at creation).
data.task_result.voices[]
array
List of voices, returned when task_status=succeed.
data.task_result.voices[].voice_id
string
Voice ID, used for reference by APIs 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 temporary. Download and save it promptly.
data.task_result.voices[].owned_by
string
Voice owner identifier.
data.task_result.voices[].status
string
Voice status: succeed (normal) / deleted.
data.created_at
number
Task creation time, Unix timestamp in milliseconds.
data.updated_at
number
Task last update time, Unix timestamp in milliseconds.
data.final_unit_deduction
string
Number of units deducted for this task.
data.final_balance_deduction.quota
string
Discounted price for quota deduction.
data.final_balance_deduction.list_price
string
List price for quota deduction.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". For the reason of task failure, see data.task_status_msg.

Deleting a Voice

1. API Description

Delete 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

2. Input Parameters

Parameter Name
Required
Type
Description
voice_id
Yes
string
Voice ID to delete (the voice_id returned by the query API).

3. Sample Request

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

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information; "SUCCEED" on success.
request_id
string
Request ID.
data.task_id
string
Creation task ID corresponding to the voice.
data.task_status
string
Task status: submitted / processing / succeed / failed.
data.task_result
object
Deletion result object (usually an empty object {}, indicating successful deletion).
data.task_status_msg
string
Displays the failure reason when the task fails, and is an empty string in normal cases.
data.created_at
number
Task creation time, Unix timestamp in milliseconds.
data.updated_at
number
Task last update time, Unix timestamp in milliseconds.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes".

Querying the Task Result

1. API Description

Task query method shared by all generation APIs (text-to-video/image-to-video/all-in-one): After a task is submitted and a task ID is returned, poll the task status through the unified task query endpoint. Upon success, obtain the video URL from the result.
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/{task_id}
Note:
The {task_id} in the path is the data.id returned when the task was submitted (represented by YOUR_TASK_ID in the example). Video generation takes approximately several minutes, so polling every 3 to 5 seconds is recommended. Response fields are provided according to the official Kling API structure, and the actual returned response prevails.

2. Input Parameters

Parameter Name
Required
Type
Description
task_id
Yes
string
Task ID (path parameter), which is the data.id returned when the task is submitted.

3. Sample Request

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'

4. Output Parameters

Field
Type
Description
code
int
Business error code; 0 indicates success.
message
string
Error or prompt information.
request_id
string
Request ID.
data
array
List of task results.
data[].id
string
Task ID.
data[].status
string
Task status: processing / succeeded / failed.
data[].message
string
Task status information; displays the failure reason when the task fails.
data[].outputs
array
List of video results.
data[].outputs[].type
string
Type of generated result; the current video result is video.
data[].outputs[].id
string
Video ID.
data[].outputs[].url
string
The video file URL is temporary. Download and save it promptly.
data[].outputs[].duration
string
Video duration in seconds.
data[].create_time
long
Task creation time; Unix timestamp in milliseconds.
data[].update_time
long
Task update time; Unix timestamp in milliseconds.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Sample Response

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

6. Error Codes

When a request fails, code is not 0. For specific error codes and handling suggestions, see "Appendix: Unified Error Codes". The task status description is the same as that in "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 missing or invalid apikey
401
1001
Authorization is empty
Authorization header not carried
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 has expired
The apikey has expired.
429
1100
Account exception
Account exception (possibly due to overdue payment, suspension, or ban)
429
1101
Account in arrears (postpaid)
Postpaid account overdue payment
429
1102
Resource pack depleted or expired
The resource pack has been used up or has expired.
403
1103
Access denied for the requested resource
No access to the requested resource (the corresponding model/capability is not subscribed)
400
1200
Invalid request parameters
Invalid request parameters (missing required fields, incorrect types, out-of-range enum values, and so on)
400
1201
Invalid parameters
Invalid parameter value. Check the valid value range in the documentation.
404
1202
The requested method is invalid
Incorrect HTTP method
404
1203
The requested resource does not exist
Incorrect endpoint path or nonexistent resource
400
1300
Trigger the platform strategy
Triggers a platform policy (such as failed content moderation or non-compliant input)
400
1301
Trigger platform sensitive word list
Hit sensitive words or non-compliant prompts
429
1302
Too frequent API calls
Calls are too frequent, triggering rate limiting.
429
1303
Concurrency or QPS exceeds the limit
The concurrency or QPS exceeds the preset quota.
400
1304
Trigger IP strategy
Trigger IP address policy-based interception
500
5000
Internal server error
Internal server error
503
5001
Server is temporarily unavailable
Service temporarily unavailable (usually due to high load or maintenance).
504
5002
Server internal 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 of 1 and a maximum of 6 shots are supported.
m: Shot duration in seconds. Each shot must be at least 1 second, and the sum of all shot durations must equal the total video duration.
words: The prompt for this shot. Maximum length: 512 characters.
The total maximum prompt length is 3072 characters (2500 or fewer recommended). Both positive and negative descriptions are supported.
Only kling-video-v3 and kling-video-v3-omni support this feature, and multi_shot=true (default) is required for it to take effect.

General Constraints on Image Assets

Format: .jpg / .jpeg / .png (transparent channels are not supported). File size: no more than 50 MB. Width and height: at least 300 px each. Aspect ratio: 1:2.5 to 2.5:1. Input via URL or Base64 is supported.

FAQs

1. How to Choose a Model?

The most comprehensive option, with 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 with speed and cost as priorities: kling-video-v3-turbo (audio and multi-shot are not supported).
To make a character replicate a specified motion: use kling-video-motion-control-v3.0 (select this when you need to reference a custom subject). If you do not need to reference a subject, you can use the previous generation kling-video-motion-control-v2.6.

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 is not available. Only text-to-video and Omni video generation support this parameter, and it is required for Omni video generation when no first frame or reference video is provided.

3. What Are Custom Elements and How to Use Them?

An element is a custom visual subject (such as a character) created from multiple reference images (image_refer) or a reference video (video_refer). After it is created through the Element Management API, an element_id is obtained, which can be referenced in Image-to-Video and Omni Video Generation to maintain character consistency across tasks. Reference an element in prompts using @ElementName, and avoid using element names that are substrings of each other.

4. What Are Custom Voices and How to Use Them?

A voice is a custom sound subject created from a reference audio (or a video containing audio). After it is created through the Voice Management API, a voice_id is obtained, which can be referenced in APIs 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 store it promptly.

Anterior: PixVerse Video Generation API GuidePróximo: MiniMax Video Generation API Guide

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation