Avatar

Create Task

POST/v1/videos/avatar/image2video

curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/avatar/image2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/pink_boy.png",
    "sound_file": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/go-to-world.mp3",
    "prompt": "While talking, excitedly shaking head, finally reaching out and making a fist, deciding to set off, hopping happily",
    "mode": "std",
    "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
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "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

imagestringRequired

Avatar Reference Image

Support inputting image Base64 encoding or image URL (ensure accessibility).

Base64 Encoding Note:
Please note, if you use the Base64 method, make sure all image data parameters you pass are in Base64 encoding format. When using Base64, do NOT add any prefix like data:image/png;base64,. Only provide the Base64-encoded string.

Correct:

iVBORw0KGgoAAAANSUhEUgAAAAUA...

Incorrect:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...

Supported image formats: .jpg / .jpeg / .png

Image file size ≤ 10MB, dimensions ≥ 300px, aspect ratio between 1:2.5 ~ 2.5:1

audio_idstringOptional

Audio ID Generated via TTS API

Only supports audio generated within the last 30 days, duration between 2-300 seconds

Either audio_id or sound_file must be provided (mutually exclusive)

sound_filestringOptional

Sound File

Supports Base64-encoded audio or accessible audio URL

Accepted formats: .mp3/.wav/.m4a/.aac, max 5MB, format mismatch or file too large will return error codes and other information

Duration must be between 2-300 seconds

Either audio_id or sound_file must be provided (mutually exclusive)

System will verify audio content and return error codes if there are problems

promptstringOptional

Positive text prompt

Can be used to define avatar actions, emotions, and camera movements

Cannot exceed 2500 characters

modestringOptionalDefault to std

Video generation mode

Enum values：stdpro

std: Standard Mode, cost-effective

pro: Professional Mode, higher quality video output

Different model versions and video modes have different support ranges. For details, see Capability Map

watermark_infoobjectOptional

Whether to generate watermarked results simultaneously

Defined by the enabled parameter, format:

  "watermark_info": { "enabled": boolean } 

true: generate watermarked result, false: do not generate

Custom watermarks are not currently supported

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 the specific message schema, see Callback Protocol

external_task_idstringOptional

Customized Task ID

Will not overwrite system-generated task ID, but can be used for task queries

Must be unique within a single user account

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/avatar/image2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/pink_boy.png",
    "sound_file": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/go-to-world.mp3",
    "prompt": "While talking, excitedly shaking head, finally reaching out and making a fist, deciding to set off, hopping happily",
    "mode": "std",
    "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
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "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/videos/avatar/image2video/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/avatar/image2video/{task_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": {
      "videos": [
        {
          "id": "string", // Generated video ID; globally unique
          "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string", // Watermarked video download URL, anti-leech format
          "duration": "string" // Total video duration, unit: s (seconds)
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "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

Task ID for avatar, fill the value directly in the request path

external_task_idstringOptional

Customized Task ID for avatar. Fill the value directly in the request path. Choose either task_id or external_task_id for querying.

cURL
curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/avatar/image2video/{task_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": {
      "videos": [
        {
          "id": "string", // Generated video ID; globally unique
          "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string", // Watermarked video download URL, anti-leech format
          "duration": "string" // Total video duration, unit: s (seconds)
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "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/videos/avatar/image2video

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

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, 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": {
        "videos": [
          {
            "id": "string", // Generated video ID; globally unique
            "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string", // Watermarked video download URL, anti-leech format
            "duration": "string" // Total video duration, unit: s (seconds)
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "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/videos/avatar/image2video?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
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, 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": {
        "videos": [
          {
            "id": "string", // Generated video ID; globally unique
            "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string", // Watermarked video download URL, anti-leech format
            "duration": "string" // Total video duration, unit: s (seconds)
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "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
    }
  ]
}