Image Generation

Create Task

POST/v1/images/generations

curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-1",
    "prompt": "Generate a Pixar-style puppy",
    "negative_prompt": "",
    "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png",
    "n": 2,
    "external_task_id": "",
    "callback_url": ""
}'

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status: 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, ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, ms
  }
}

💡

Please note that in order to maintain naming consistency, the original model field has been changed to model_name, so in the future, please use this field to specify the version of the model that needs to be called.
At the same time, we keep the behavior forward-compatible. If you continue to use the original model field, it will not have any impact on the interface call, there will not be any exception, which is equivalent to the default behavior when model_name is empty (i.e., call the V1 model).

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

model_namestringOptionalDefault to kling-v1

Model Name

Enum values：kling-v1kling-v1-5kling-v2kling-v2-newkling-v2-1kling-v3

promptstringRequired

Positive text prompt

Cannot exceed 2500 characters

negative_promptstringOptional

Negative text prompt

Cannot exceed 2500 characters

Note: In the Image-to-Image scenario (when the "image" field is not empty), negative prompts are not supported.

imagestringOptional

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

File size: ≤10MB, dimensions: min 300px, aspect ratio: 1:2.5 ~ 2.5:1

Required when image_reference parameter is not empty

image_referencestringOptional

Image reference type

Enum values：subjectface

subject: character feature reference, face: character appearance reference

When using face, the uploaded image must contain only one face

Required when using kling-v1-5 and image parameter is not empty

image_fidelityfloatOptionalDefault to 0.5

Face reference intensity for user-uploaded images during generation

Value range: [0, 1], The larger the value, the stronger the reference intensity

Only kling-v1, kling-v1-5 support this parameter

human_fidelityfloatOptionalDefault to 0.45

Facial reference intensity, refers to the similarity of the facial features of the person in the reference image

Only image_reference parameter is subject is available

Value range: [0, 1], The larger the value, the stronger the reference intensity

Only kling-v1-5 supports this parameter

element_listarrayOptional

Reference element list based on element library ID

Load with key:value format as follows:

"element_list":[
  { "element_id": long },
  { "element_id": long }
]

The amount of reference element is related to the amount of reference image, the sum of the amount of reference element and the amount of reference image shall not exceed 10.

▾Hide child attributes

element_idlongRequired

Element ID

resolutionstringOptionalDefault to 1k

Image generation resolution

Enum values：1k2k

1k: 1K standard, 2k: 2K high-res

Different model versions support varying ranges. For details, refer to the Capability Map

nintOptionalDefault to 1

Number of generated images

Value range: [1, 9]

aspect_ratiostringOptionalDefault to 16:9

Aspect ratio of the generated images (width:height)

Enum values：16:99:161:14:33:43:22:321:9

Different model versions support varying ranges. For details, refer to the 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 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/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-1",
    "prompt": "Generate a Pixar-style puppy",
    "negative_prompt": "",
    "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png",
    "n": 2,
    "external_task_id": "",
    "callback_url": ""
}'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status: 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, ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, ms
  }
}

Query Task (Single)

GET/v1/images/generations/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/images/generations/{id} \
  --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, 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.)
    "final_unit_deduction": "string", // The deduction units of task
    "watermark_info": {
      "enabled": boolean
    },
    "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
    "task_result": {
      "images": [
        {
          "index": 0, // Image Number, 0-9
          "url": "string", // URL for generating images, such as: https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string" // Watermarked image download URL, anti-leech format
        }
      ]
    }
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

task_idstringRequired

The task ID for image generation. 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/images/generations/{id} \
  --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, 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.)
    "final_unit_deduction": "string", // The deduction units of task
    "watermark_info": {
      "enabled": boolean
    },
    "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
    "task_result": {
      "images": [
        {
          "index": 0, // Image Number, 0-9
          "url": "string", // URL for generating images, such as: https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string" // Watermarked image download URL, anti-leech format
        }
      ]
    }
  }
}

Query Task (List)

GET/v1/images/generations

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/images/generations?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, 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.)
      "final_unit_deduction": "string", // The deduction units of task
      "watermark_info": {
        "enabled": boolean
      },
      "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
      "task_result": {
        "images": [
          {
            "index": 0, // Image Number, 0-9
            "url": "string", // URL for generating images, such as: https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string" // Watermarked image download URL, anti-leech format
          }
        ]
      }
    }
  ]
}

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/images/generations?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, 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.)
      "final_unit_deduction": "string", // The deduction units of task
      "watermark_info": {
        "enabled": boolean
      },
      "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
      "task_result": {
        "images": [
          {
            "index": 0, // Image Number, 0-9
            "url": "string", // URL for generating images, such as: https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string" // Watermarked image download URL, anti-leech format
          }
        ]
      }
    }
  ]
}