Text to Audio

Create Task

POST/v1/audio/text-to-audio

curl --request POST \
  --url https://api-singapore.klingai.com/v1/audio/text-to-audio \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Fireworks sound during Chinese New Year celebration",
    "duration": 3,
    "external_task_id": "",
    "callback_url": ""
  }'

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, 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

promptstringRequired

Text prompt

Cannot exceed 200 characters

durationfloatRequired

Generated audio duration

Value range: 3.0s - 10.0s, supports one decimal place precision

external_task_idstringOptional

Customized Task ID

Users can provide a customized task ID, which will not overwrite the system-generated task ID but can be used for task queries.

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

callback_urlstringOptional

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

The specific message schema of the notification can be found in Callback Protocol

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/audio/text-to-audio \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Fireworks sound during Chinese New Year celebration",
    "duration": 3,
    "external_task_id": "",
    "callback_url": ""
  }'
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, 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 Task (Single)

GET/v1/audio/text-to-audio/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/audio/text-to-audio/{task_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

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, 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 message, displaying the failure reason when the task fails (such as triggering the platform's content risk control, etc.)
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "audios": [
        {
          "id": "string", // Audio ID; globally unique
          "url_mp3": "string", // URL for generated audio in MP3 format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
          "url_wav": "string", // URL for generated audio in WAV format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
          "duration_mp3": "string", // Total duration of the audio in MP3 format, unit: s
          "duration_wav": "string" // Total duration of the audio in WAV format, unit: s
        }
      ]
    },
    "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_idstringOptional

The task ID for audio generation

Request path parameter, fill the value directly in the request path

You can choose to query by external_task_id or task_id

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

cURL
curl --request GET \
  --url https://api-singapore.klingai.com/v1/audio/text-to-audio/{task_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
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, 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 message, displaying the failure reason when the task fails (such as triggering the platform's content risk control, etc.)
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "audios": [
        {
          "id": "string", // Audio ID; globally unique
          "url_mp3": "string", // URL for generated audio in MP3 format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
          "url_wav": "string", // URL for generated audio in WAV format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
          "duration_mp3": "string", // Total duration of the audio in MP3 format, unit: s
          "duration_wav": "string" // Total duration of the audio in WAV format, unit: s
        }
      ]
    },
    "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 Task (List)

GET/v1/audio/text-to-audio

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/audio/text-to-audio?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

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, 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 message, displaying the failure reason when the task fails (such as triggering the platform's content risk control, etc.)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "audios": [
          {
            "id": "string", // Audio ID; globally unique
            "url_mp3": "string", // URL for generated audio in MP3 format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
            "url_wav": "string", // URL for generated audio in WAV format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
            "duration_mp3": "string", // Total duration of the audio in MP3 format, unit: s
            "duration_wav": "string" // Total duration of the audio in WAV format, unit: s
          }
        ]
      },
      "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

Number of items per page

Value range: [1, 500]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/audio/text-to-audio?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
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, 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 message, displaying the failure reason when the task fails (such as triggering the platform's content risk control, etc.)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "audios": [
          {
            "id": "string", // Audio ID; globally unique
            "url_mp3": "string", // URL for generated audio in MP3 format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
            "url_wav": "string", // URL for generated audio in WAV format (Please note that for information security, generated audios will be cleared after 30 days. Please save them promptly.)
            "duration_mp3": "string", // Total duration of the audio in MP3 format, unit: s
            "duration_wav": "string" // Total duration of the audio in WAV format, unit: s
          }
        ]
      },
      "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
    }
  ]
}