tencent cloud

LLM Service TokenHub

ドキュメントLLM Service TokenHubAPI Integration GuideVideo Generation ModelKling Video Generation API Guide

Kling Video Generation API Guide

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-23 23:20:14
AI翻訳・品質チェック済み

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-v4, 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-v4
kling-video-v4
Text-to-video / image-to-video (including first-last frame) / omnipotent video generation (mixed input of reference image, reference video, subject, and voice)
3 ~ 30
720p / 1080p
21:9, 16:9, 9:16, 1:1; Omni also supports adaptive
New-generation flagship: up to 30 seconds per generation, 21:9 widescreen support, and up to 15 reference assets combined per task for omni video generation.
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
Native audio, multi-shot, element reference, and 4K support.
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. For kling-video-v4 Omni video generation, the aspect_ratio defaults to adaptive, which is automatically selected by the model based on the input material.

Text-to-Video

1. API Description

Generate videos from text prompts alone. v4 supports a maximum of 30 seconds per generation and a 21:9 wide aspect ratio. 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-v4, kling-video-v3, kling-video-v3-turbo
prompt
Yes
string
Prompt, which can contain positive and negative descriptions. v4: pure English ≤ 26000 characters, pure non-English ≤ 11000 characters, and for mixed Chinese and English, number of English characters ÷ 26000 + number of non-English characters ÷ 11000 ≤ 1; 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; v4 / V3 Turbo: 720p / 1080p. Default value: 1080p for v4, and 720p for others.
aspect_ratio
All
Aspect ratio. Options: 16:9 / 9:16 / 1:1 (v4 also supports 21:9). Default value: 16:9.
duration
All
Duration (seconds). v4: an integer from 3 to 30; V3 / V3 Turbo: 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-v4 and 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-v4 or kling-video-v3-turbo to call the corresponding model. Note that v4 and V3 Turbo do not support the audio / multi_shot fields, so remove the audio field when making the call.

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 by using an image as the first frame (with an optional last frame for v4 / V3) combined with text prompts. V3 additionally supports element references (Element). 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-v4, 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: v4: prompt / first_frame / last_frame; V3: prompt / first_frame / last_frame / element; V3 Turbo: prompt / first_frame.
text
Conditionally required
string
Text prompt. Required when type=prompt. ≤ 2500 characters (v4 has the same length limit as text-to-video); 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 (v4: ≤ 30 MB per image).
1. Base64: The size of each image must be <75 MB, and the size after conversion to Base64 must be <=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; v4 / V3 Turbo: 720p / 1080p. Default value: 1080p for v4, and 720p for others.
duration
All
Duration (seconds). v4: an integer from 3 to 30; V3 / V3 Turbo: 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.
kling-video-v4: 1 first frame and optionally 1 last frame. Each image must be ≤ 30MB.
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
  }
}'
Note:
Replace model in the example with kling-video-v4 or kling-video-v3-turbo to call the corresponding model. To use first and last frames, append an item {"type": "last_frame", "url": "last frame image URL"} to contents. V3 Turbo does not support last frames.

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 multimodal unified generation entry for v4 / V3 Omni: Videos can be generated or edited by combining prompts, reference images (first/last frames, reference images), reference videos (feature videos / base videos to be edited), and elements (Element). v4 does not support base videos to be edited (base_video), meaning video editing is not supported.
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 range: kling-video-v4, 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. base_video is not supported in v4.
text
Conditionally required
string
Text prompt. Required when type=prompt. ≤ 3072 characters (≤ 2500 recommended); v4 has the same length limit as text-to-video; supports @xxx material references and multi-shot syntax (multi-shot only in V3 Omni); voice materials can be referenced by @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: The size of each image must be <75 MB, and the size after conversion to Base64 must be <=100 MB. Format requirement: data:image/<image format>;base64,<Base64 encoding>. Note: For jpg images, use "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 1 video character element can be added. Single file size <= 200 MB (v4: videos support URL only, single file ≤ 300 MB, single segment and total duration 3-30 seconds, up to 5 reference videos; images ≤ 30 MB per image, up to 10 images).
1. Base64: The total size of all videos must be <=75 MB, and the total size after conversion to Base64 must be <=100 MB. Format requirement: data:video/<video format>;base64,<Base64 encoding>. Note: For mov videos, use "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. V3 Omni: 720p / 1080p / 4k; v4: 720p / 1080p, with 4k not supported yet. Default value: 1080p for v4, and 720p for V3 Omni.
aspect_ratio
Conditionally required
Aspect ratio. v4: 21:9 / 16:9 / 9:16 / 1:1 / adaptive, with adaptive as the default; V3 Omni: 16:9 / 9:16 / 1:1, with 16:9 as the default. Required for V3 Omni when there is no first frame and no reference video.
duration
No
Duration (seconds). v4: an integer from 3 to 30; V3 Omni: an integer from 3 to 15. Default value: 5.
multi_shot
No
V3 Omni only. Whether to generate multi-shot video. Default value: true.
audio
No
V3 Omni only. Audio. Options: native / original / off (default: off). original=retains the original audio of the reference video. Kling-Video-v4 does not support this parameter.
Note:
Kling-Video-v4 does not support the audio parameter. The settings of v4 supports only resolution / aspect_ratio / duration. To specify a voice, use {"type": "voice", "voice_id": "voice ID", "id": "1"} in contents. You do not need to (and cannot) pass settings.audio.
v4 input combination limits:
First and last frames support only "first frame only" and "first frame + last frame". "Last frame only" is not supported.
base_video (video editing) and middle_frame (middle frame) are not supported. The audio parameter is not supported, so do not pass it.
Reference images: no more than 10. Reference videos: no more than 5 (when video character subjects are present, the total number of video character subjects and reference videos must not exceed 5). Subjects: no more than 7 (of which video character subjects must not exceed 3). Voices: no more than 3.
The total number of materials in a single task (images + videos + subjects + voices) must not exceed 15.
Reference images, reference videos, and subjects are automatically numbered as image_1 / video_1 / element_1 in the order they are provided. You can reference them in prompts as @image_1, @video_1, and @element_1.
To reference a voice, append {"type": "voice", "voice_id": "voice ID", "id": "1"} in contents. You do not need to pass settings.audio.
V3 Omni input combination limits:
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"
  }
}'
v4 request example (reference image + feature reference video):
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-v4",
  "contents": [
    {
      "type": "prompt",
      "text": "Reference the clothing in @image_1, absorb the movement rhythm of @video_1, and deliver a realistic cinematic quality."
    },
    {
      "type": "refer_image",
      "url": "https://example.com/refer.jpg"
    },
    {
      "type": "feature_video",
      "url": "https://example.com/motion.mp4"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}'
Note:
v4 does not support base_video (video editing) or settings.audio. To reference a voice, append {"type": "voice", "voice_id": "voice ID", "id": "1"} in contents.
v4 voice reference example (contents.type=voice, without passing settings.audio):
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-v4",
  "contents": [
    {
      "type": "prompt",
      "text": "A girl sits by the window of a moving train, quietly looking outside. After a moment, she stands up and walks down the aisle. As she passes another passenger, she says softly @1: \\"Excuse me.\\""
    },
    {
      "type": "refer_image",
      "url": "https://example.com/girl.jpg"
    },
    {
      "type": "voice",
      "voice_id": "829826751244537879",
      "id": "1"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "9:16",
    "duration": 5
  }
}'
Note:
voice_id is obtained by querying after creation in "Voice Management". You can also use a system preset voice.
id is the index ID of the voice material, referenced in the prompt as @id (for example, @1). It must be unique within the same task.
You can reference at most 3 voices. v4 does not support settings.audio.

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: ≤ 50MB (≤ 30MB for kling-video-v4). Width and height: both ≥ 300px. Aspect ratio: 1:2.5 to 2.5:1. Images can be passed in via URL or Base64. For kling-video-v4, the total number of images per task must be ≤ 10.

Video Asset Constraints (kling-video-v4)

Item
Constraint
Format
.mp4 / .mov
File Size
≤ 300MB
Single Segment Duration
3 to 30 seconds (inclusive)
Total Duration
3 to 30 seconds (inclusive), including the duration of the reference video and the video character subject
Size
Width and height both between 700px and 4553px (inclusive), with a total pixel area no greater than 8294400.
Aspect Ratio
1:2.5 ~ 2.5:1
Frame Rate
24fps to 60fps (generated video frame rate is 24fps)
Quantity
Up to 5 segments when no video character subject is present; when a video character subject is present, the total number of video character subjects and reference videos must not exceed 5.
Input Method
Only public URLs (http/https) are supported.

FAQs

1. How to Choose a Model?

Up to 30 seconds per generation, 21:9 wide aspect ratio, and up to 15 Omni reference materials: kling-video-v4 (audio and video editing are not supported).
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.


前の記事へ: PixVerse Video Generation API Guide次の記事へ: MiniMax Video Generation API Guide

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック

キーワードで検索
    Enter keywords to search documentation