Skip to content

Kling โ€‹

Updated

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-videoAuthentication: Tokenhub API Key / Bearer

Kling is a video generation model that supports text- and image-based video generation, as well as Omni multimodal reference generation and video editing. It also provides management APIs for reference characters and voices, helping keep characters and voices consistent.

Basic Information โ€‹

ItemValue
Call pathTokenhub API
Guardrail removal supportNot supported

Supported Specifications by Version โ€‹

VersionResolutionAspect ratioDuration
kling-video-v3720p / 1080p / 4k16:9 / 9:16 / 1:13 ~ 15 seconds
kling-video-v3-omni720p / 1080p / 4k16:9 / 9:16 / 1:13 ~ 15 seconds
kling-video-v3-turbo720p / 1080p16:9 / 9:16 / 1:13 ~ 15 seconds

Input Modes โ€‹

VersionInput
kling-video-v3Text-to-video / image-to-video (including first and last frames and elements)
kling-video-v3-omniOmni video generation (multimodal input of text/image/video and video editing)
kling-video-v3-turboText-to-video / image-to-video

Call Procedure โ€‹

Video generation is a time-consuming task, so API uses asynchronous calls, which are divided into the following two steps.

  1. Submit the task: Call the generation API (text-to-video / image-to-video / Omni). On success, data.id (task ID) is returned.
  2. Poll for the result: Until data.status = succeeded, call the task result query API with the task ID, and obtain the video URL from the result.

Text-Based Video Generation โ€‹

API Description โ€‹

Generates a video using only a text prompt. V3 supports multi-shot template syntax (for details, see "Appendix: Multi-Shot Prompt Syntax"), native audio, and 4K output.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel version. Valid values: kling-video-v3, kling-video-v3-turbo
promptRequiredstringPrompt, which can include positive and negative descriptions. V3: โ‰ค 3072 characters (โ‰ค 2500 recommended), with multi-shot template syntax supported. V3 Turbo: โ‰ค 2500 characters.
settingsOptionalobjectOutput configuration. For sub-fields, see the table below (supported fields vary by model).
optionsOptionalobjectGeneral configuration. For sub-fields, see the table below.

settings sub-fields (by model):

Sub-fieldApplicable modelDescription
resolutionAllResolution. V3: 720p / 1080p / 4k; V3 Turbo: 720p / 1080p. Default value: 720p.
aspect_ratioAllAspect ratio. Options: 16:9 / 9:16 / 1:1. Default value: 16:9.
durationAllDuration (seconds). An integer in 3~15. Default value: 5.
multi_shotV3 onlyWhether to generate a multi-shot video. Default value: true. When set to false, a multi-shot prompt does not produce multi-shot output.
audioV3 onlyAudio. Options: native (generates native audio matching the video) / off (default value).

Reference: The settings for kling-video-v3-turbo support only the three fields resolution / aspect_ratio / duration. multi_shot and audio are not supported.

options sub-fields:

Sub-fieldRequiredDescription
external_task_idOptionalA custom task ID that is unique within the account. You can query the task by this ID.
watermark_infoOptionalWatermark configuration. Structure: {"enabled": true/false}. When true, the watermark is enabled.

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-video-v3",
  "prompt": "A girl sat on the train, looking out the window, sunlight streaming across her face",
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "audio": "native"
  }
}'

Reference: To call the corresponding model, replace model in the example with kling-video-v3-turbo. V3 Turbo does not support the audio / multi_shot fields.

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success; for other values, see Appendix: Unified Error Codes.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringThe request ID generated by the system, used for issue tracking and resolution.
dataobjectTask data object.
data.idstringThe task ID generated by the system, used for subsequent task queries.
data.statusstringTask status. It is fixed to submitted upon successful submission; subsequent statuses are obtained through the query API.
data.messagestringTask status message. When the task fails, it shows the failure reason.
data.create_timelongTask generation time. A Unix timestamp in milliseconds.
data.update_timelongTask update time. A Unix timestamp in milliseconds.

Response Example โ€‹

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

Error Codes โ€‹

When a request fails, code is not 0. For specific error codes and handling recommendations, see "Appendix: Unified Error Codes". After a task is submitted successfully, the task status of the generation phase can be obtained through "Task Result Query" API.

statusDescriptionHandling recommendation
processingProcessing (including queuing)Continue querying the status.
succeededGenerated successfullyUse the video URL in the result.
failedGeneration failedCheck and fix the failure reason, then retry. If the failure persists, contact technical support and provide request_id.

Image-to-Video โ€‹

API Description โ€‹

Uses an image as the first frame (V3 optionally supports a last frame) and combines it with a text prompt to generate a video. V3 also supports element references. The image can be passed in directly as a public URL or Base64, and the output aspect ratio follows the input image.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel version. Valid values: kling-video-v3, kling-video-v3-turbo
contentsRequiredarrayA collection of reference materials. Place the fields of the same material in the same object. At least one prompt and one first_frame must each be included. For sub-fields, see the table below.
settingsOptionalobjectOutput configuration. For sub-fields, see the table below. Reference: Image-to-video has no aspect_ratio parameter; the aspect ratio is determined by the input image.
optionsOptionalobjectGeneral configuration, the same as for text-to-video.

Sub-fields of the contents array elements:

ParameterRequiredTypeDescription
typeRequiredstringMaterial type. Supported scope by model: V3: prompt / first_frame / last_frame / element; V3 Turbo: prompt / first_frame.
textConditionally requiredstringText prompt. Required when type=prompt. โ‰ค 2500 characters. V3 supports multi-shot template syntax and @element references.
urlConditionally requiredstringImage asset (URL or Base64). Required when type=first_frame / last_frame. Constraints: .jpg/.jpeg/.png, โ‰ค 50 MB, both width and height โ‰ฅ 300 px, aspect ratio 1:2.5โ€“2.5:1.
element_idConditionally requiredstringElement reference (defined by JSON). Required when type=element, and supported only on V3. Maximum 3, referenced as @xxx in the prompt.

settings sub-fields (by model):

Sub-fieldApplicable modelDescription
resolutionAllResolution. V3: 720p / 1080p / 4k; V3 Turbo: 720p / 1080p. Default value: 720p.
durationAllDuration (seconds). An integer in 3~15. Default value: 5.
multi_shotV3 onlyWhether to generate a multi-shot video. Default value: true.
audioV3 onlyAudio. Options: native / off (default value: off).

Reference: For first and last frames, only "first frame only" and "first frame + last frame" are supported. "Last frame only" is not supported. Do not use element names that are substrings of each other (for example, @Zhang and @ZhangSan).

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-video-v3",
  "contents": [
    {
      "type": "prompt",
      "text": "Make the subject in the image turn its head naturally while the camera slowly zooms in"
    },
    {
      "type": "first_frame",
      "url": "https://example.com/start.jpg"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5
  }
}'

Response Parameters โ€‹

The same as the output parameters of "Text-to-Video".

Response Example โ€‹

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

Error Codes โ€‹

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

Omni Video Generation โ€‹

API Description โ€‹

The unified multimodal generation entry point of V3 Omni. You can comprehensively use prompts, reference images (first/last frames, reference images), reference videos (feature video / base video to be edited), and elements to generate or edit videos.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video

Request Parameters โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel version. Value: kling-video-v3-omni
contentsRequiredarrayA collection of multimodal reference materials. Place the fields of the same material in the same object. For sub-fields, see the table below.
settingsOptionalobjectOutput configuration. For sub-fields, see the table below.
optionsOptionalobjectGeneral configuration, the same as for text-to-video.

Sub-fields of the contents array elements:

ParameterRequiredTypeDescription
typeRequiredstringMaterial type. Enumerated values: prompt / first_frame / last_frame / refer_image / feature_video (feature reference video) / base_video (base video to be edited) / element / voice (timbre).
textConditionally requiredstringText prompt. Required when type=prompt. โ‰ค 3072 characters (โ‰ค 2500 recommended). Supports @xxx material references and multi-shot syntax, and voice materials can be referenced via @id.
urlConditionally requiredstringImage/video asset. Images support a URL or Base64; videos support only a URL. Image constraints: jpg/jpeg/png, โ‰ค 50 MB, width and height โ‰ฅ 300 px, aspect ratio 1:2.5โ€“2.5:1. Video constraints: mp4/mov, โ‰ค 200 MB, duration 3~15.5 seconds.
element_idConditionally requiredstringElement ID (generated through element management API). Required when type=element.
voice_idConditionally requiredstringVoice ID. Required when type=voice. Obtain it by querying after generation in "Voice Management", or use a system preset voice.
idConditionally requiredstringMaterial index ID. Required when type=voice, and it must be unique within the same task. To use this voice, reference it as @id in the prompt.

settings sub-fields:

Sub-fieldRequiredDescription
resolutionOptionalResolution. 720p / 1080p / 4k. Default value: 720p.
aspect_ratioConditionally requiredAspect ratio: 16:9 / 9:16 / 1:1, default value 16:9. Required when neither a first frame nor a reference video is provided.
durationOptionalDuration (seconds). An integer in 3~15. Default value: 5.
multi_shotOptionalWhether to generate a multi-shot video. Default value: true.
audioOptionalAudio. Options: native / original / off (default value: off). original = retains the original audio of the reference video.

**Reference:**Input combination limits: For first and last frames, only "first frame only" and "first frame + last frame" are supported. At most 1 reference video can be provided. feature_video does not support a last frame, and base_video does not support first/last frames or multi-shot. The total of reference images and elements must not exceed 7 when there is no reference video, and must not exceed 4 when there is a reference video. Voices (type=voice) can be referenced up to 2. When a voice is specified, settings.audio cannot be set to off. When feature_video is used, audio can only be off and multi_shot can only be true. When base_video is used, audio cannot be native (it can be original or off), and multi-shot is not supported.

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-video-v3-omni",
  "contents": [
    {
      "type": "prompt",
      "text": "Change the color of the parrots feathers to blue, keeping the background unchanged"
    },
    {
      "type": "base_video",
      "url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "audio": "original"
  }
}'

Response Parameters โ€‹

The same as the output parameters of "Text-to-Video".

Response Example โ€‹

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

Error Codes โ€‹

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

Element Management โ€‹

Element management is used to generate, query, and delete custom reference objects (custom characters). You can generate a reference object based on multiple reference images (image_refer) or a reference video (video_refer). After generation, in the image-to-video and Omni video generation API you can reference it as element_id to reuse the custom character.

Generating a Reference Object โ€‹

API Description โ€‹

Generates a custom reference object. Generation is an asynchronous task. After submission, poll the task status through "Reference Object Query" API. On success, obtain element_id.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements

Request Parameters โ€‹

ParameterRequiredTypeDescription
element_nameRequiredstringElement name, up to 20 characters. For example: "my_hero".
element_descriptionRequiredstringElement description, up to 100 characters.
reference_typeRequiredstringReference method. Values: image_refer (multi-image reference object) / video_refer (video reference object).
element_image_listConditionally requiredobjectA multi-image reference object, required when reference_type=image_refer. It includes frontal_image (a frontal image of 1 or more) and refer_images[].image_url (images from other angles or close-ups, 1~3).
Images can be passed in as a public URL or Base64.
Constraints: jpg/jpeg/png, 10 MB or less, both width and height 300 px or more, aspect ratio 1:2.5โ€“2.5:1.
element_video_listConditionally requiredobjectA video reference object, required when reference_type=video_refer. Structure: {"refer_videos": [{"video_url": "..."}]}. Constraints: MP4/MOV, duration 3~8 seconds, 1080P, aspect ratio 16:9 or 9:16, 200 MB or less.
element_voice_idOptionalstringAssociates the ID of an existing voice in the voice library. When empty, no voice is associated.
tag_listOptionalarrayTag configuration, with the structure [{ "tag_id": "o_101" }]. tag_id enumeration: o_101 meme / o_102 person / o_103 animal / o_104 prop / o_105 clothing / o_106 scene / o_107 effect / o_108 other.
external_task_idOptionalstringA custom task ID that is unique within the account.

Request Examples โ€‹

Multi-image reference object (image_refer):

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "element_name": "my_hero",
  "element_description": "A young man with short hair, wearing a blue jacket",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "https://example.com/front.jpg",
    "refer_images": [
      {
        "image_url": "https://example.com/side.jpg"
      }
    ]
  }
}'

Video reference object (video_refer):

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "element_name": "my_hero",
  "element_description": "A young man with short hair, wearing a blue jacket",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [
      {
        "video_url": "https://example.com/demo.mp4"
      }
    ]
  }
}'

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringThe request ID generated by the system, used for issue tracking and resolution.
data.task_idstringThe task ID generated by the system.
data.task_statusstringTask status: submitted / processing / succeed / failed.
data.task_info.external_task_idstringCustom task ID (returned if provided during generation).
data.task_status_msgstringShows the failure reason when the task fails; an empty string when normal.
data.created_atnumberTask generation time. A Unix timestamp in milliseconds.
data.updated_atnumberThe time the task was last updated. A Unix timestamp in milliseconds.
data.final_unit_deductionstringThe final point value deducted for the task.
data.final_balance_deduction.quotastringThe discounted price of the quota deduction.
data.final_balance_deduction.list_pricestringThe list price of the quota deduction.

Response Example โ€‹

json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "02f9537c-9319-4cfb-b347-8f22cb73ffc8",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1787836125041,
    "updated_at": 1787836125041
  }
}

Error Codes โ€‹

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

Reference Object Query โ€‹

API Description โ€‹

Queries the status and result of a reference object generation task. After submitting the generation task and receiving the task ID, until the status becomes data.task_status = succeed, poll this API, and obtain the reference object information from data.task_result.elements.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/{id}

Reference: The {id} in the path is the data.task_id returned when the task was generated; it can also be replaced with the external_task_id passed in during generation.

Request Parameters โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringThe task ID of the element generation task, entered into {id} of the query path. Alternatively, it can be replaced with the external_task_id used during generation.

Request Example โ€‹

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

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringThe request ID generated by the system, used for issue tracking and resolution.
data.task_idstringThe task ID generated by the system.
data.task_statusstringTask status: submitted / processing / succeed / failed.
data.task_info.external_task_idstringCustom task ID (returned if provided during generation).
data.task_status_msgstringShows the failure reason when the task fails; an empty string when normal.
data.task_result.elements[]arrayReference object list. Returned when task_status=succeed.
data.task_result.elements[].element_idnumberA globally unique reference object ID.
data.task_result.elements[].element_namestringReference object name.
data.task_result.elements[].element_descriptionstringReference object description.
data.task_result.elements[].element_typestringReference method: image_refer (multi-image reference object) / video_refer (video reference object).
data.task_result.elements[].element_image_listobjectImage reference information (available for image_refer). It includes frontal_image and refer_images[].image_url.
data.task_result.elements[].element_video_listobjectVideo reference information (available for video_refer).
data.task_result.elements[].owned_bystringReference object source. kling indicates the official reference object library; other values indicate the creator ID.
data.task_result.elements[].statusstringReference object status: succeed (normal) / deleted.
data.created_atnumberTask generation time. A Unix timestamp in milliseconds.
data.updated_atnumberThe time the task was last updated. A Unix timestamp in milliseconds.
data.final_unit_deductionstringThe final point value deducted for the task.
data.final_balance_deduction.quotastringThe discounted price of the quota deduction.
data.final_balance_deduction.list_pricestringThe list price of the quota deduction.

Response Example โ€‹

json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "656ee178-de4f-48ea-9763-166bbaa3e4cc-query-1787836129",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {
      "elements": [
        {
          "element_id": 319807609263140,
          "element_name": "Advanced Subject_Image Test",
          "element_description": "A young man with short hair, wearing a blue jacket",
          "element_type": "image_refer",
          "element_image_list": {
            "frontal_image": "https://example.com/front.jpg",
            "refer_images": [
              {
                "image_url": "https://example.com/side.jpg"
              }
            ]
          },
          "element_video_list": {},
          "owned_by": "826925436873121851",
          "status": "succeed"
        }
      ]
    },
    "task_status_msg": "",
    "created_at": 1787836125041,
    "updated_at": 1787836128102,
    "final_unit_deduction": "0",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

Error Codes โ€‹

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

Deleting a Reference Object โ€‹

API Description โ€‹

Deletes a custom reference object. Only custom elements can be deleted. Official elements (owned_by=kling) cannot be deleted.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements

Request Parameters โ€‹

ParameterRequiredTypeDescription
element_idRequiredstringThe ID of the element to delete.

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "element_id": "319807609263140"
}'

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringThe request ID generated by the system, used for issue tracking and resolution.
data.task_idstringThe task ID generated by the system.
data.task_statusstringTask status: submitted / processing / succeed / failed.
data.task_status_msgstringShows the failure reason when the task fails; an empty string when normal.
data.created_atnumberTask generation time. A Unix timestamp in milliseconds.
data.updated_atnumberThe time the task was last updated. A Unix timestamp in milliseconds.

Response Example โ€‹

json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "dd4a503f-8afd-415d-b3e8-de4c26d4f87a",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {},
    "task_status_msg": "",
    "created_at": 1787836125041,
    "updated_at": 1787836128102,
    "final_unit_deduction": "0",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

Error Codes โ€‹

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

Voice Management โ€‹

Voice management is used to generate, query, and delete custom voices. A voice is generated based on reference audio (or a video that contains audio). After generation, Omni video generation (as a material with type=voice in contents), digital human (avatar), lip sync (advanced-lip-sync), and other API can reference it as voice_id.

Voice generation is an asynchronous task and is divided into the following two steps.

  1. Submit the task: Call the generation API. On success, data.task_id (task ID) is returned.
  2. Poll for the result: Until the status becomes data.task_status = succeed, call the voice task query API with the task ID, and from data.task_result.voices obtain voice_id.

Generating a Voice โ€‹

API Description โ€‹

Generates a custom voice based on reference audio (or a video that contains audio).

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices

Request Parameters โ€‹

ParameterRequiredTypeDescription
voice_nameRequiredstringVoice name.
voice_urlConditionally requiredstringThe public URL of the reference audio. Choose either this parameter or video_id.
video_idConditionally requiredstringThe video ID of the video that contains the target audio (a video generated by a video generation task). Choose either this parameter or voice_url.
external_task_idOptionalstringA custom task ID that is unique within the account.

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "voice_name": "Test voice",
  "voice_url": "https://example.com/reference.mp3"
}'

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringThe request ID generated by the system, used for issue tracking and resolution.
data.task_idstringThe task ID generated by the system, used for subsequent task queries.
data.task_statusstringTask status: submitted / processing / succeed / failed.
data.task_info.external_task_idstringCustom task ID (returned if provided during generation).
data.created_atnumberTask generation time. A Unix timestamp in milliseconds.
data.updated_atnumberThe time the task was last updated. A Unix timestamp in milliseconds.

Response Example โ€‹

json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a90bd11c-f272-4686-bad9-72310898a217",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1786687976483,
    "updated_at": 1786687976483
  }
}

Error Codes โ€‹

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

Voice Task Query โ€‹

API Description โ€‹

Polls the voice generation task with the task ID returned by the generation API. When the task succeeds, obtain voice_id and the preview URL from the result.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/{task_id}

Reference: The {task_id} in the path is the API-returned data.task_id. It can also be replaced with the external_task_id passed in during generation. Polling every 2~3 seconds is recommended.

Request Parameters โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringThe task ID (a path parameter), that is, the generation API-returned data.task_id.

Request Example โ€‹

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

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringRequest ID.
data.task_idstringTask ID.
data.task_statusstringTask status: submitted / processing / succeed / failed.
data.task_status_msgstringTask status message. When the task fails, it shows the failure reason.
data.task_info.external_task_idstringCustom task ID (returned if provided during generation).
data.task_result.voices[]arrayVoice list. Returned when task_status=succeed.
data.task_result.voices[].voice_idstringVoice ID, used for referencing in API such as digital human and lip sync.
data.task_result.voices[].voice_namestringVoice name.
data.task_result.voices[].trial_urlstringThe voice preview audio URL is a temporary URL. Download and save it immediately.
data.task_result.voices[].owned_bystringThe voice owner identifier.
data.task_result.voices[].statusstringVoice status: succeed (normal) / deleted.
data.created_atnumberTask generation time. A Unix timestamp in milliseconds.
data.updated_atnumberThe time the task was last updated. A Unix timestamp in milliseconds.
data.final_unit_deductionstringThe number of units deducted for this task.
data.final_balance_deduction.quotastringThe discounted price of the quota deduction.
data.final_balance_deduction.list_pricestringThe list price of the quota deduction.

Response Example โ€‹

json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "8efcf51b-4637-4616-a21b-436501eaef96-query-1786687983",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {
      "voices": [
        {
          "voice_id": "917124264959582304",
          "voice_name": "Test voice",
          "trial_url": "https://example.com/voice-trial.wav",
          "owned_by": "826925436873121851",
          "status": "succeed"
        }
      ]
    },
    "task_status_msg": "",
    "created_at": 1786687976483,
    "updated_at": 1786687982942,
    "final_unit_deduction": "0.05",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

Error Codes โ€‹

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

Deleting a Voice โ€‹

API Description โ€‹

Deletes the specified custom voice. Only custom voices can be deleted. After deletion, the voice can no longer be referenced in the generation API.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice

Request Parameters โ€‹

ParameterRequiredTypeDescription
voice_idRequiredstringThe voice ID to delete (the query API-returned voice_id).

Request Example โ€‹

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "voice_id": "917124264959582304"
}'

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message. On success, it is "SUCCEED".
request_idstringRequest ID.
data.task_idstringThe generation task ID corresponding to the voice.
data.task_statusstringTask status: submitted / processing / succeed / failed.
data.task_resultobjectThe deletion result object (usually an empty object {}, indicating that the deletion succeeded).
data.task_status_msgstringShows the failure reason when the task fails; an empty string when normal.
data.created_atnumberTask generation time. A Unix timestamp in milliseconds.
data.updated_atnumberThe time the task was last updated. A Unix timestamp in milliseconds.

Response Example โ€‹

json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "b641fc55-7f23-41e5-8155-2fa371c3d871",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {},
    "task_status_msg": "",
    "created_at": 1786687976483,
    "updated_at": 1786687982942,
    "final_unit_deduction": "0.05",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

Error Codes โ€‹

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

Task Result Query โ€‹

API Description โ€‹

The task query method shared by all generation API (text-to-video / image-to-video / unified). After submitting a task and receiving the task ID, poll the task status through the unified task query endpoint. On success, obtain the video URL from the result.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/{task_id}

Reference: The {task_id} in the path is the data.id returned when the task was submitted. Video generation takes about a few minutes, so polling every 3~5 seconds is recommended. The response fields are provided according to the official Kling API structure; the actual returned response takes precedence.

Request Parameters โ€‹

ParameterRequiredTypeDescription
task_idRequiredstringThe task ID (a path parameter), which is the data.id returned when the task was submitted.

Request Example โ€‹

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

Response Parameters โ€‹

FieldTypeDescription
codeintBusiness error code. 0 indicates success.
messagestringError or informational message.
request_idstringRequest ID.
dataarrayTask result list.
data[].idstringTask ID.
data[].statusstringTask status: processing / succeeded / failed.
data[].messagestringTask status message. When the task fails, it shows the failure reason.
data[].outputsarrayVideo result list.
data[].outputs[].typestringGeneration result type. Currently, the video result is video.
data[].outputs[].idstringVideo ID.
data[].outputs[].urlstringThe video file URL is a temporary URL. Download and save it immediately.
data[].outputs[].durationstringVideo duration (seconds).
data[].create_timelongTask generation time. A Unix timestamp in milliseconds.
data[].update_timelongTask update time. A Unix timestamp in milliseconds.
tokenhub_usageobjectUsage.
tokenhub_usage.total_tokensintegerThe number of tokens consumed by this task, used for billing/settlement.

Response Example โ€‹

json
{
  "code": 0,
  "data": [
    {
      "update_time": 1786429168170,
      "create_time": 1786428992000,
      "id": "251435731-WandVideo-7d1997fb7ad74bfabd2814b4a9962571",
      "message": "",
      "outputs": [
        {
          "duration": "10.041",
          "id": "916037982829322296",
          "type": "video",
          "url": "https://example.com/output-video.mp4?q-sign-algorithm=sha1&q-signature=xxxxxx"
        }
      ],
      "status": "succeeded"
    }
  ],
  "message": "SUCCEED",
  "request_id": "5d0b35d5-da56-4dae-8e6c-81035122e716-query-1786429167",
  "tokenhub_usage": {
    "total_tokens": 600000
  }
}

Error Codes โ€‹

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

Appendix โ€‹

Unified Error Codes โ€‹

HTTP status codeBusiness codeError messageDescription
2000successRequest succeeded
4011000Authentication failedAuthorization is missing or the apikey is invalid.
4011001Authorization is emptyThe Authorization header is not included.
4011002Authorization is invalidThe apikey is invalid or has expired.
4011003Authorization is not yet validThe apikey is not yet valid.
4011004Authorization expiredThe apikey has expired.
4291100Account exceptionAccount exception (the account may be overdue, suspended, or blocked)
4291101Account overdue (postpaid)The postpaid account payment is overdue.
4291102Resource pack exhausted or expiredThe resource pack has been fully used or has expired.
4031103Access to the requested resource deniedThe requested resource cannot be accessed (the corresponding model/feature is not subscribed).
4001200Invalid request parameterThe request parameters are incorrect (missing required fields, incorrect type, enumerated value out of range, and so on).
4001201Invalid parameterThe parameter value is incorrect. Check the valid value range in the documentation.
4041202The requested method is invalidThe HTTP method is incorrect.
4041203The requested resource does not existThe endpoint path is incorrect or the resource does not exist.
4001300Platform policy triggeredA platform policy was triggered (content moderation failure or non-compliant input, and so on).
4001301Platform sensitive word list triggeredA sensitive word or a non-compliant prompt was detected.
4291302API calls are too frequentThe call frequency is too high, and rate limiting has been applied.
4291303Concurrency or QPS limit exceededConcurrency or QPS exceeded the preset quota.
4001304IP policy triggeredBlocking based on the IP address policy was triggered.
5005000Internal server errorInternal server error
5035001The server is temporarily unavailableThe service is temporarily unavailable (usually due to high load or maintenance).
5045002Internal server timeoutInternal 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 (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 maximum length of the entire prompt is 3072 characters (2500 characters 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 (the default value) is required for it to take effect.

General Constraints for Image Assets โ€‹

Formats: .jpg / .jpeg / .png (transparent channels are not supported). File size: 50 MB or less. Width and height: at least 300 px each. Aspect ratio: 1:2.5โ€“2.5:1. URL or Base64 input is supported.

FAQ โ€‹

1. Which of the three models should I choose? โ€‹

  • The most comprehensive option in terms of features, including 4K / native audio / multi-shot / element support: kling-video-v3.
  • Multimodal mixed input and video editing (reference video, base video rewriting): kling-video-v3-omni.
  • Batch generation that prioritizes speed and cost: kling-video-v3-turbo (audio and multi-shot are not supported).

2. Can I specify the aspect ratio for image-to-video? โ€‹

No. The output aspect ratio of image-to-video is determined by the input image, and the aspect_ratio parameter cannot be used. Only text-to-video and Omni video generation support this parameter, and in Omni video generation it is required when neither a first frame nor a reference video is provided.

3. What is a custom element and how do I use it? โ€‹

An element is a custom visual reference object (for example, a character) generated from multiple reference images (image_refer) or a reference video (video_refer). Once generated through element management API, you obtain element_id, and you can reference it in image-to-video and Omni video generation to maintain character consistency across tasks. Reference the element as @ElementName in the prompt, and do not use element names that are substrings of each other.

4. What is a custom voice and how do I use it? โ€‹

A voice is a custom sound reference object generated from reference audio (or a video that contains audio). Once generated through voice management API, you obtain voice_id, and you can reference it in API such as Omni video generation, digital human (avatar), and lip sync (advanced-lip-sync). The trial_url in the query result is a temporary preview URL, so download and save it immediately.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages