Custom Voice

Create Custom Voice

POST/v1/general/custom-voices

curl --request POST \
  --url https://api-singapore.klingai.com/v1/general/custom-voices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_id": "",
    "voice_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/out.mp3",
    "voice_name": "Custom Voice",
    "callback_url": ""
  }'

200

{
  "code": 0, // Error Codes；Specific definitions can be found in Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

voice_namestringRequired

Voice Name

The maximum length of text content is 20 characters

The voices that are no longer used after creation can be deleted through the API

voice_urlstringOptional

The URL of voice data file

Supports .mp3 / .wav audio file and .mp4 / .mov video file

The voice needs to be clean and free of noise, with only one type of human voice present, with a duration of no less than 5 seconds and no longer than 30 seconds

video_idstringOptional

Generated video ID, which can provide audio materials by referencing historical works

Only videos that meet the following conditions can be used to customize voice:
- The video is generated on V2.6 model and the value of sound parameter is on
- The video is generated through Avatar API
- The video is generated through Lip-Sync API

The voice needs to be clean and free of noise, with only one type of human voice present, with a duration of no less than 5 seconds and no longer than 30 seconds

callback_urlstringOptional

The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.

For specific message schema, see Callback Protocol

external_task_idstringOptional

Customized Task ID

Will not overwrite system-generated task ID, but supports querying task by this ID

Please note that the customized task ID must be unique within a single user account.

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/general/custom-voices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_id": "",
    "voice_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/out.mp3",
    "voice_name": "Custom Voice",
    "callback_url": ""
  }'
200
{
  "code": 0, // Error Codes；Specific definitions can be found in Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms
  }
}

Query Custom Voice (Single)

GET/v1/general/custom-voices/{id}

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/custom-voices/{id}' \
  --header 'Authorization: Bearer <token>'

200

{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "voices": [
        {
          "voice_id": "string", // Generated voice ID; globally unique
          "voice_name": "string", // Generated voice name
          "trial_url": "string", // URL for generating videos
          "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
        }
      ]
    },
    "final_unit_deduction": "string", // The deduction units of task
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

task_idstringRequired

The task ID of the element creation task. Request path parameter, directly fill the value in the request path.

external_task_idstringOptional

Customized Task ID for audio generation

The external_task_id filled in when creating the task. You can choose to query by external_task_id or task_id
When creating a task, you can choose to query by external_task_id or task_id.

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/custom-voices/{id}' \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "voices": [
        {
          "voice_id": "string", // Generated voice ID; globally unique
          "voice_name": "string", // Generated voice name
          "trial_url": "string", // URL for generating videos
          "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
        }
      ]
    },
    "final_unit_deduction": "string", // The deduction units of task
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}

Query Custom Voice (List)

GET/v1/general/custom-voices

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/custom-voices?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'

200

{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "voices": [
          {
            "voice_id": "string", // Generated voice ID; globally unique
            "voice_name": "string", // Generated voice name
            "trial_url": "string", // URL for generating videos
            "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
          }
        ]
      }
      "final_unit_deduction": "string", // The deduction units of task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
    }
  ]
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Query Parameters

pageNumintOptionalDefault to 1

Page number

Value range: [1, 1000]

pageSizeintOptionalDefault to 30

Data volume per page

Value range: [1, 1000]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/custom-voices?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "voices": [
          {
            "voice_id": "string", // Generated voice ID; globally unique
            "voice_name": "string", // Generated voice name
            "trial_url": "string", // URL for generating videos
            "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
          }
        ]
      }
      "final_unit_deduction": "string", // The deduction units of task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
    }
  ]
}

Query Presets Voice (List)

GET/v1/general/presets-voices

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/presets-voices?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'

200

{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
      "task_result": {
        "voices": [
          {
            "voice_id": "string", // Official voice ID; globally unique
            "voice_name": "string", // Official voice name
            "trial_url": "string", // URL for official videos
            "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
          }
        ]
      }
    }
  ]
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Query Parameters

pageNumintOptionalDefault to 1

Page number

Value range: [1, 1000]

pageSizeintOptionalDefault to 30

Data volume per page

Value range: [1, 1000]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/presets-voices?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values：submitted、processing、succeed、failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
      "task_result": {
        "voices": [
          {
            "voice_id": "string", // Official voice ID; globally unique
            "voice_name": "string", // Official voice name
            "trial_url": "string", // URL for official videos
            "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
          }
        ]
      }
    }
  ]
}

Delete Custom Voice

POST/v1/general/delete-voices

curl --request POST \
  --url https://api-singapore.klingai.com/v1/general/delete-voices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "voice_id": "850087542757535834"
  }'

200

{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string" // Task status, Enum values：submitted、processing、succeed、failed
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

voice_idstringRequired

The ID of the voice to be deleted, only supports deleting custom voices

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/general/delete-voices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "voice_id": "850087542757535834"
  }'
200
{
  "code": 0, // Error codes；Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string" // Task status, Enum values：submitted、processing、succeed、failed
  }
}