Image Expansion

Create Task

POST/v1/images/editing/expand

curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/editing/expand \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "up_expansion_ratio": 0.1495,
    "down_expansion_ratio": 0.1495,
    "left_expansion_ratio": 0.6547,
    "right_expansion_ratio": 0.6547,
    "prompt": "",
    "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png",
    "n": 2,
    "external_task_id": ""
  }'

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

Expand the image in any direction based on the original image.

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

imagestringRequired

Reference Image

Supports image input as either Base64-encoded string or URL (ensure accessibility)

Important: When using Base64, do NOT add any prefix like data:image/png;base64,. Submit only the raw Base64 string.

Correct Base64 format:

iVBORw0KGgoAAAANSUhEUgAAAAUA...

Incorrect Base64 format (with data: prefix):

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

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

Image file size must not exceed 10MB. Image dimensions must be at least 300px in width and height, aspect ratio: 1:2.5 ~ 2.5:1

up_expansion_ratiofloatRequired

Expand upwards range; calculated based on multiples of the original image height

Value range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image

Example: If original height is 20 and value is 0.1, then:
- The distance from the top edge of the original image to the top edge of the new image is 20 × 0.1 = 2, and the area within is the expansion range

down_expansion_ratiofloatRequired

Expand downwards range; calculated based on multiples of the original image height

Value range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image

Example: If original height is 20 and value is 0.2, then:
- The distance from the bottom edge of the original image to the bottom edge of the new image is 20 × 0.2 = 4, and the area within is the expansion range

left_expansion_ratiofloatRequired

Expand leftwards range; calculated based on multiples of the original image width

Value range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image

Example: If original width is 30 and value is 0.3, then:
- The distance from the left edge of the original image to the left edge of the new image is 30 × 0.3 = 9, and the area within is the expansion range

right_expansion_ratiofloatRequired

Expand rightwards range; calculated based on multiples of the original image width

Value range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image

Example: If original width is 30 and value is 0.4, then:
- The distance from the right edge of the original image to the right edge of the new image is 30 × 0.4 = 12, and the area within is the expansion range

promptstringOptional

Positive text prompt

Cannot exceed 2500 characters

nintOptionalDefault to 1

Number of generated images

Value range: [1, 9]

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

Must be unique within a single user account

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/editing/expand \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "up_expansion_ratio": 0.1495,
    "down_expansion_ratio": 0.1495,
    "left_expansion_ratio": 0.6547,
    "right_expansion_ratio": 0.6547,
    "prompt": "",
    "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png",
    "n": 2,
    "external_task_id": ""
  }'
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, is 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
  }
}

Example code

import math

def calculate_expansion_ratios(width, height, area_multiplier, aspect_ratio):
    """
    Calculate top/bottom/left/right expansion ratios for image outpainting.
    
    Parameters:
    - width: Original image width
    - height: Original image height
    - area_multiplier: Multiplier for the outpainted area relative to original image
    - aspect_ratio: Width/height ratio for the outpainted area（width/height）
    
    Returns:
    - Formatted string with 4 decimal places, e.g."0.1495,0.1495,0.6547,0.6547"
    """
    # Calculate target total area
    target_area = area_multiplier * width * height
    
    # Calculate target height and width (maintaining aspect ratio)
    target_height = math.sqrt(target_area / aspect_ratio)
    target_width = target_height * aspect_ratio
    
    # Calculate expansion pixels
    expand_top = (target_height - height) / 2
    expand_bottom = expand_top
    expand_left = (target_width - width) / 2
    expand_right = expand_left
    
    # Calculate relative ratios
    top_ratio = expand_top / height
    bottom_ratio = expand_bottom / height
    left_ratio = expand_left / width
    right_ratio = expand_right / width
    
    # Format to 4 decimal places
    return f"{top_ratio:.4f},{bottom_ratio:.4f},{left_ratio:.4f},{right_ratio:.4f}"

# Example: Original 100x100, 3x area multiplier, 16:9 aspect ratio
print(calculate_expansion_ratios(100, 100, 3, 16/9))  
# Output: "0.1495,0.1495,0.6547,0.6547"

Query Task (Single)

GET/v1/images/editing/expand/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/images/editing/expand/{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, 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 message, 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
      },
      "final_unit_deduction": "string", // Final unit deduction for the task
      "watermark_info": {
        "enabled": boolean
      },
      "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 index, 0-9
            "url": "string", // URL for generating images (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          }
        ]
      }
    }
  ]
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

task_idstringRequired

The task ID generated by images. 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/editing/expand/{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, 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 message, 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
      },
      "final_unit_deduction": "string", // Final unit deduction for the task
      "watermark_info": {
        "enabled": boolean
      },
      "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 index, 0-9
            "url": "string", // URL for generating images (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          }
        ]
      }
    }
  ]
}

Query Task (List)

GET/v1/images/editing/expand

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/images/editing/expand?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, 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 message, 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
      },
      "final_unit_deduction": "string", // Final unit deduction for the task
      "watermark_info": {
        "enabled": boolean
      },
      "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 index, 0-9
            "url": "string", // URL for generating images (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-hotlinking 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

Data volume per page

Value range: [1, 500]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/images/editing/expand?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, 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 message, 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
      },
      "final_unit_deduction": "string", // Final unit deduction for the task
      "watermark_info": {
        "enabled": boolean
      },
      "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 index, 0-9
            "url": "string", // URL for generating images (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-hotlinking format
          }
        ]
      }
    }
  ]
}