Omni-Image

Create Task

POST/v1/images/omni-image

curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/omni-image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-image-o1",
    "prompt": "Merge all the people in the images into the <<<object_1>>> image",
    "element_list": [
        {
            "element_id": 829836802793406551
        }
    ],
    "image_list": [
        {
            "image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-4.png"
        },
        {
            "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/video_effects/1.png"
        },
        {
            "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/video_effects/4.png"
        }
    ],
    "resolution": "2k",
    "n": 1,
    "aspect_ratio": "3:2"
  }'

200

{
  "code": 0, // Error code; Specific definitions can be found in Error codes
  "message": "string", // Error message
  "request_id": "string", // Request ID, system-generated, used for tracking requests and troubleshooting
  "data": {
    "task_id": "string", // Task ID, system-generated
    "task_info": { //Task creation parameters
      "external_task_id": "string" //User-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

model_namestringOptionalDefault to kling-image-o1

Model Name

Enum values：kling-image-o1kling-v3-omni

promptstringRequired

Text prompt words, which can include positive and negative descriptions

The prompt words can be templated to meet different image generation needs

Must not exceed 2,500 characters

Specify an image in the format of <<<>>>, such as <<<image_1>>>

The scope of abilities can be found in the user manual: KLING Omni Model User Guide

image_listarrayOptional

Reference Image List

Load with key:value format as follows:

"image_list":[
  { "image":"image_url" }
]

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

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

Image file size must not exceed 10MB. Image dimensions must be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1

The sum of reference elements and reference images must not exceed 10

The value of image_url parameter must not be empty

▾Hide child attributes

imagestringRequired

Image URL or Base64 string

element_listarrayOptional

Reference Element List based on element ID configuration

Load with key:value format as follows:

"element_list":[
  { "element_id": 829836802793406551 }
]

The sum of reference elements and reference images must not exceed 10

The support range for different model versionsvaries. For details, see Capability Map

▾Hide child attributes

element_idlongRequired

Element ID from element library

resolutionstringOptionalDefault to 1k

Image generation resolution

Enum values：1k2k4k

1k: 1K standard definition

2k: 2K high-res

4k: 4K high-res

The support range for different model versionsvaries. For details, see Capability Map

result_typestringOptionalDefault to single

Control whether to generate a single image or a series of images

Enum values：singleseries

The support range for different model versionsvaries. For details, see Capability Map

nintOptionalDefault to 1

Number of generated images

Value range: [1, 9]

When result_type is series, this parameter is invalid

series_amountintOptionalDefault to 4

Number of images in a series

Value range: [2, 9]

When result_type is single, this parameter is invalid

The support range for different model versionsvaries. For details, see Capability Map

aspect_ratiostringOptionalDefault to auto

Aspect ratio of the generated images (width:height)

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

auto is to intelligently aspect ratio of the generated image based on incoming content.

When generating a new image based on the aspect ratio of the original image, this parameter is invalid

The support range for different model versionsvaries. 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

User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID

Please note that it must be unique for each user

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/omni-image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-image-o1",
    "prompt": "Merge all the people in the images into the <<<object_1>>> image",
    "element_list": [
        {
            "element_id": 829836802793406551
        }
    ],
    "image_list": [
        {
            "image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-4.png"
        },
        {
            "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/video_effects/1.png"
        },
        {
            "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/video_effects/4.png"
        }
    ],
    "resolution": "2k",
    "n": 1,
    "aspect_ratio": "3:2"
  }'
200
{
  "code": 0, // Error code; Specific definitions can be found in Error codes
  "message": "string", // Error message
  "request_id": "string", // Request ID, system-generated, used for tracking requests and troubleshooting
  "data": {
    "task_id": "string", // Task ID, system-generated
    "task_info": { //Task creation parameters
      "external_task_id": "string" //User-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
  }
}

Invocation examples

Image generation with element

curl --location 'https://xxx/v1/images/generations' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3-omni",
    "prompt": "Generate a recommended cover for each subject <<element_1>> based on the style of the reference image <<image_1>>",
    "element_list": [
      {
        "element_id": "160"
      },
      {
        "element_id": "161"
      }
    ],
    "image_list": [
      {
        "image": "xxx"
      },
      {
        "image": "xxx"
      }
    ],
    "resolution": "2k",
    "result_type": "series",
    "series_amount": 2,
    "aspect_ratio": "auto",
    "external_task_id": "",
    "callback_url": ""
  }'

Query Task (Single)

GET/v1/images/omni-image/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/images/omni-image/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

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_status_msg": "string", // Task status message, failure reason when task fails
    "task_info": { //Task creation parameters
      "external_task_id": "string" //Customer-defined task ID
    },
    "task_result": {
      "result_type": "single",
      "images": [
        {
          "index": 0, // Image number
          "url": "string", // URL for generated image, anti-hotlinking format (Generated images/videos will be cleared after 30 days. Please save promptly.)
          "watermark_url": "string" // Watermarked image download URL, anti-hotlinking format
        }
      ],
      "series_images": [
        {
          "index": 0, // Series-image sequence number
          "url": "string", // URL for generated image, anti-hotlinking format
          "watermark_url": "string" // Watermarked image download URL
        }
      ]
    },
    "watermark_info": { "enabled": boolean },
    "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

The task ID for image generation. Request path parameter, directly fill the value in the request path. 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
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/omni-image/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
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_status_msg": "string", // Task status message, failure reason when task fails
    "task_info": { //Task creation parameters
      "external_task_id": "string" //Customer-defined task ID
    },
    "task_result": {
      "result_type": "single",
      "images": [
        {
          "index": 0, // Image number
          "url": "string", // URL for generated image, anti-hotlinking format (Generated images/videos will be cleared after 30 days. Please save promptly.)
          "watermark_url": "string" // Watermarked image download URL, anti-hotlinking format
        }
      ],
      "series_images": [
        {
          "index": 0, // Series-image sequence number
          "url": "string", // URL for generated image, anti-hotlinking format
          "watermark_url": "string" // Watermarked image download URL
        }
      ]
    },
    "watermark_info": { "enabled": boolean },
    "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/images/omni-image

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

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "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: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status message
      "task_info": { //Task creation parameters
        "external_task_id": "string" //Customer-defined task ID
      },
      "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
      "watermark_info": { "enabled": boolean },
      "task_result": {
        "result_type": "single",
        "images": [
          {
            "index": 0, // Image number
            "url": "string", // URL for generated image, anti-hotlinking format (Generated images/videos will be cleared after 30 days. Please save promptly.)
            "watermark_url": "string" // Watermarked image download URL
          }
        ],
        "series_images": [
          {
            "index": 0, // Series-image sequence number
            "url": "string", // URL for generated image, anti-hotlinking format
            "watermark_url": "string" // Watermarked image download URL
          }
        ]
      }
    }
  ]
}

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/omni-image?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "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: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status message
      "task_info": { //Task creation parameters
        "external_task_id": "string" //Customer-defined task ID
      },
      "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
      "watermark_info": { "enabled": boolean },
      "task_result": {
        "result_type": "single",
        "images": [
          {
            "index": 0, // Image number
            "url": "string", // URL for generated image, anti-hotlinking format (Generated images/videos will be cleared after 30 days. Please save promptly.)
            "watermark_url": "string" // Watermarked image download URL
          }
        ],
        "series_images": [
          {
            "index": 0, // Series-image sequence number
            "url": "string", // URL for generated image, anti-hotlinking format
            "watermark_url": "string" // Watermarked image download URL
          }
        ]
      }
    }
  ]
}