> ## Documentation Index
>
> Fetch the complete documentation index at: https://kling.ai/document-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Management

> Source: https://kling.ai/document-api/api/video/4-0/voice-customization
> Locale: en
> Current Tab: Voice Management
> Sibling Tabs: Text to Video / Image to Video / Omni Video Generation / Element Management / Voice Management
> This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted.

---

## Create Custom Voice

### API Overview

- Method: `POST`
- Path: `/v1/general/custom-voices`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `voice_name` | string | Yes | - | - | Voice Name |
| `voice_url` | string | No | - | - | The URL of voice data file |
| `video_id` | string | No | - | - | Generated video ID, which can provide audio materials by referencing historical works |
| `callback_url` | string | No | - | - | The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes. |
| `external_task_id` | string | No | - | - | Customized Task ID |

#### Request Body Field Notes

- `voice_name`: The maximum length of text content is 20 characters
- `voice_name`: The voices that are no longer used after creation can be deleted through the API
- `voice_url`: Exactly one of voice_url and video_id must be provided. Providing both or neither will result in an error.
- `voice_url`: Supports .mp3 / .wav audio file and .mp4 / .mov video file
- `voice_url`: 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_id`: Exactly one of video_id and voice_url must be provided. Providing both or neither will result in an error.
- `video_id`: 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
- `video_id`: 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_url`: For specific message schema, see [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks)
- `external_task_id`: Will not overwrite system-generated task ID, but supports querying task by this ID
- `external_task_id`: Please note that the customized task ID must be unique within a single user account.

### Request Example

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

### Response Example

```json
{
  "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)

### API Overview

- Method: `GET`
- Path: `/v1/general/custom-voices/{id}`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Path Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `task_id` | string | No | - | - | The task ID returned when creating the custom voice. Use either task_id or external_task_id as the {id} path parameter; exactly one is required. |
| `external_task_id` | string | No | - | - | Custom task ID for voice customization |

#### Path Params Field Notes

- `external_task_id`: Use either external_task_id or task_id as the {id} path parameter; exactly one is required
  - external_task_id must be unique for each user

### Request Example

```bash
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/custom-voices/{id}' \
  --header "Authorization: Bearer ${KLING_API_KEY}"
```

### Response Example

```json
{
  "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", // Preview audio URL for the custom voice
          "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
    "final_balance_deduction": { // Balance deduction information
      "quota": "string", // Balance deduction discount price
      "list_price": "string" // Balance deduction list price
    },
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}
```

---

## Query Custom Voice (List)

### API Overview

- Method: `GET`
- Path: `/v1/general/custom-voices`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Query Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `pageNum` | int | No | `1` | - | Page number |
| `pageSize` | int | No | `30` | - | Data volume per page |

#### Query Params Field Notes

- `pageNum`: Value range: [1, 1000]
- `pageSize`: Value range: [1, 1000]

### Request Example

```bash
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/custom-voices?pageNum=1&pageSize=30' \
  --header "Authorization: Bearer ${KLING_API_KEY}"
```

### Response Example

```json
{
  "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", // Preview audio URL for the custom voice
            "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
      "final_balance_deduction": { // Balance deduction information
        "quota": "string", // Balance deduction discount price
        "list_price": "string" // Balance deduction list price
      },
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
    }
  ]
}
```

---

## Query Presets Voice (List)

### API Overview

- Method: `GET`
- Path: `/v1/general/presets-voices`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Query Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `pageNum` | int | No | `1` | - | Page number |
| `pageSize` | int | No | `30` | - | Data volume per page |

#### Query Params Field Notes

- `pageNum`: Value range: [1, 1000]
- `pageSize`: Value range: [1, 1000]

### Request Example

```bash
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/general/presets-voices?pageNum=1&pageSize=30' \
  --header "Authorization: Bearer ${KLING_API_KEY}"
```

### Response Example

```json
{
  "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", // Preview audio URL for the preset voice
            "owned_by": "kling" // Voice source, kling is the official voice library, and others are the creator's ID
          }
        ]
      }
    }
  ]
}
```

---

## Delete Custom Voice

### API Overview

- Method: `POST`
- Path: `/v1/general/delete-voices`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `voice_id` | string | Yes | - | - | The ID of the voice to be deleted, only supports deleting custom voices |

### Request Example

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

### Response Example

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