AI Multi-Shot

Create Task

POST/v1/general/ai-multi-shot

curl --request POST \
  --url https://api-singapore.klingai.com/v1/general/ai-multi-shot \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "element_frontal_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
    "external_task_id": "",
    "callback_url": ""
  }'

200

{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "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_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

element_frontal_imagestringRequired

The frontal side of element image

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

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

Image file size cannot exceed 10MB, and the width and height dimensions shall not be less than 300px, and the aspect ratio should be between 1:2.5 ~ 2.5:1

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

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

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/general/ai-multi-shot \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "element_frontal_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
    "external_task_id": "",
    "callback_url": ""
  }'
200
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "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_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/general/ai-multi-shot/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/general/ai-multi-shot/{task_id} \
  --header 'Authorization: Bearer <token>'

200

{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "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": {
      "images": [
        {
          "index": 0, // Image result index, 0-2
          "url_1": "string", // URL for generated image, anti-hotlinking format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "url_2": "string", // URL for generated image, anti-hotlinking format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "url_3": "string" // URL for generated image, anti-hotlinking format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
        }
      ]
    },
    "final_unit_deduction": "string", // Final unit deduction for the 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

Task ID for AI Multi-Shot. Fill the value directly in the request path.

cURL
curl --request GET \
  --url https://api-singapore.klingai.com/v1/general/ai-multi-shot/{task_id} \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "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": {
      "images": [
        {
          "index": 0, // Image result index, 0-2
          "url_1": "string", // URL for generated image, anti-hotlinking format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "url_2": "string", // URL for generated image, anti-hotlinking format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "url_3": "string" // URL for generated image, anti-hotlinking format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
        }
      ]
    },
    "final_unit_deduction": "string", // Final unit deduction for the 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/general/ai-multi-shot

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

200

{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "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": {
        "images": [
          {
            "index": 0, // Image result index, 0-2
            "url_1": "string", // URL for generated image, anti-hotlinking format (Please note that for information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
            "url_2": "string", // URL for generated image, anti-hotlinking format (Please note that for information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
            "url_3": "string" //URL for generated image, anti-hotlinking format (Please note that for information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
          }
        ]
      },
      "final_unit_deduction": "string", // Final unit deduction for the 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/general/ai-multi-shot?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "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": {
        "images": [
          {
            "index": 0, // Image result index, 0-2
            "url_1": "string", // URL for generated image, anti-hotlinking format (Please note that for information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
            "url_2": "string", // URL for generated image, anti-hotlinking format (Please note that for information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
            "url_3": "string" //URL for generated image, anti-hotlinking format (Please note that for information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
          }
        ]
      },
      "final_unit_deduction": "string", // Final unit deduction for the task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
    }
  ]
}