{
  "Create Task": "Create Task\nPOST\n/v1/images/editing/expand\ncURL\nCopy\nCollapse\ncurl --request POST \\\n--url https://api-singapore.klingai.com/v1/images/editing/expand \\\n--header 'Authorization: Bearer <token>' \\\n--header 'Content-Type: application/json' \\\n--data '{\n\"up_expansion_ratio\": 0.1495,\n\"down_expansion_ratio\": 0.1495,\n\"left_expansion_ratio\": 0.6547,\n\"right_expansion_ratio\": 0.6547,\n\"prompt\": \"\",\n\"image\": \"https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png\",\n\"n\": 2,\n\"external_task_id\": \"\"\n}'\n200\nCopy\nCollapse\n{\n\"code\": 0, // Error code; Specific definitions can be found in Error code\n\"message\": \"string\", // Error message\n\"request_id\": \"string\", // Request ID, generated by the system, is used to track requests and troubleshoot problems\n\"data\": {\n\"task_id\": \"string\", // Task ID, generated by the system\n\"task_info\": { // Task creation parameters\n\"external_task_id\": \"string\" // Customer-defined task ID\n},\n\"task_status\": \"string\", // Task status, Enum values: submitted, processing, succeed, failed\n\"created_at\": 1722769557708, // Task creation time, Unix timestamp, unit: ms\n\"updated_at\": 1722769557708 // Task update time, Unix timestamp, unit: ms\n}\n}\nExpand the image in any direction based on the original image.\nRequest Header\nContent-Type\nstring\nRequired\nDefault to application/json\nData Exchange Format\nAuthorization\nstring\nRequired\nAuthentication information, refer to API authentication\nRequest Body\nimage\nstring\nRequired\nReference Image\nSupports image input as either Base64-encoded string or URL (ensure accessibility)\nImportant: When using Base64, do NOT add any prefix like data:image/png;base64,. Submit only the raw Base64 string.\nCorrect Base64 format:\niVBORw0KGgoAAAANSUhEUgAAAAUA...\nIncorrect Base64 format (with data: prefix):\ndata:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...\nSupported image formats: .jpg / .jpeg / .png\nImage 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\nup_expansion_ratio\nfloat\nRequired\nExpand upwards range; calculated based on multiples of the original image height\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original height is 20 and value is 0.1, then:\nThe 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\ndown_expansion_ratio\nfloat\nRequired\nExpand downwards range; calculated based on multiples of the original image height\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original height is 20 and value is 0.2, then:\nThe 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\nleft_expansion_ratio\nfloat\nRequired\nExpand leftwards range; calculated based on multiples of the original image width\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original width is 30 and value is 0.3, then:\nThe 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\nright_expansion_ratio\nfloat\nRequired\nExpand rightwards range; calculated based on multiples of the original image width\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original width is 30 and value is 0.4, then:\nThe 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\nprompt",
  "Parameters": "\"task_info\": { // Task creation parameters\n\"external_task_id\": \"string\" // Customer-defined task ID\n},\n\"task_status\": \"string\", // Task status, Enum values: submitted, processing, succeed, failed\n\"created_at\": 1722769557708, // Task creation time, Unix timestamp, unit: ms\n\"updated_at\": 1722769557708 // Task update time, Unix timestamp, unit: ms\n}\n}\nExpand the image in any direction based on the original image.\nRequest Header\nContent-Type\nstring\nRequired\nDefault to application/json\nData Exchange Format\nAuthorization\nstring\nRequired\nAuthentication information, refer to API authentication\nRequest Body\nimage\nstring\nRequired\nReference Image\nSupports image input as either Base64-encoded string or URL (ensure accessibility)\nImportant: When using Base64, do NOT add any prefix like data:image/png;base64,. Submit only the raw Base64 string.\nCorrect Base64 format:\niVBORw0KGgoAAAANSUhEUgAAAAUA...\nIncorrect Base64 format (with data: prefix):\ndata:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...\nSupported image formats: .jpg / .jpeg / .png\nImage 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\nup_expansion_ratio\nfloat\nRequired\nExpand upwards range; calculated based on multiples of the original image height\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original height is 20 and value is 0.1, then:\nThe 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\ndown_expansion_ratio\nfloat\nRequired\nExpand downwards range; calculated based on multiples of the original image height\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original height is 20 and value is 0.2, then:\nThe 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\nleft_expansion_ratio\nfloat\nRequired\nExpand leftwards range; calculated based on multiples of the original image width\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original width is 30 and value is 0.3, then:\nThe 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\nright_expansion_ratio\nfloat\nRequired\nExpand rightwards range; calculated based on multiples of the original image width\nValue range: [0, 2]. The total area of the new image must not exceed 3 times that of the original image\nExample: If original width is 30 and value is 0.4, then:\nThe 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\nprompt\nstring\nOptional\nPositive text prompt\nCannot exceed 2500 characters\nn\nint\nOptional\nDefault to 1\nNumber of generated images\nValue range: [1, 9]\nwatermark_info\nobject\nOptional\nWhether to generate watermarked results simultaneously\nDefined by the enabled parameter, format:\n\"watermark_info\": { \"enabled\": boolean }\ntrue: generate watermarked result, false: do not generate\nCustom watermarks are not currently supported\ncallback_url\nstring\nOptional\nThe callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.\nFor specific message schema, see Callback Protocol\nexternal_task_id\nstring\nOptional\nCustomized Task ID\nWill not overwrite system-generated task ID, but supports querying task by this ID\nMust be unique within a single user account",
  "Callback Protocol": "For specific message schema, see Callback Protocol\nexternal_task_id\nstring\nOptional\nCustomized Task ID\nWill not overwrite system-generated task ID, but supports querying task by this ID\nMust be unique within a single user account\nExample code\nimport math\ndef calculate_expansion_ratios(width, height, area_multiplier, aspect_ratio):\n\"\"\"\nCalculate top/bottom/left/right expansion ratios for image outpainting.\nParameters:\n- width: Original image width\n- height: Original image height\n- area_multiplier: Multiplier for the outpainted area relative to original image\n- aspect_ratio: Width/height ratio for the outpainted area（width/height）\nReturns:\n- Formatted string with 4 decimal places, e.g.\"0.1495,0.1495,0.6547,0.6547\"\n\"\"\"\n# Calculate target total area\ntarget_area = area_multiplier * width * height\n# Calculate target height and width (maintaining aspect ratio)\ntarget_height = math.sqrt(target_area / aspect_ratio)\ntarget_width = target_height * aspect_ratio\n# Calculate expansion pixels\nexpand_top = (target_height - height) / 2\nexpand_bottom = expand_top\nexpand_left = (target_width - width) / 2\nexpand_right = expand_left\n# Calculate relative ratios\ntop_ratio = expand_top / height\nbottom_ratio = expand_bottom / height\nleft_ratio = expand_left / width\nright_ratio = expand_right / width\n# Format to 4 decimal places\nreturn f\"{top_ratio:.4f},{bottom_ratio:.4f},{left_ratio:.4f},{right_ratio:.4f}\"\n# Example: Original 100x100, 3x area multiplier, 16:9 aspect ratio\nprint(calculate_expansion_ratios(100, 100, 3, 16/9))\n# Output: \"0.1495,0.1495,0.6547,0.6547\"\nQuery Task (Single)\nGET\n/v1/images/editing/expand/{id}\ncURL\nCopy\nCollapse\ncurl --request GET \\\n--url https://api-singapore.klingai.com/v1/images/editing/expand/{id} \\\n--header 'Authorization: Bearer <token>'\n200\nCopy\nCollapse\n{\n\"code\": 0, // Error code; Specific definitions can be found in Error code\n\"message\": \"string\", // Error message\n\"request_id\": \"string\", // Request ID, generated by the system, is used to track requests and troubleshoot problems\n\"data\": [\n{\n\"task_id\": \"string\", // Task ID, generated by the system\n\"task_status\": \"string\", // Task status, Enum values: submitted, processing, succeed, failed\n\"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.)\n\"task_info\": { // Task creation parameters\n\"external_task_id\": \"string\" // Customer-defined task ID\n},\n\"final_unit_deduction\": \"string\", // Final unit deduction for the task\n\"watermark_info\": {\n\"enabled\": boolean\n},\n\"created_at\": 1722769557708, // Task creation time, Unix timestamp, unit: ms\n\"updated_at\": 1722769557708, // Task update time, Unix timestamp, unit: ms\n\"task_result\": {\n\"images\": [\n{\n\"index\": 0, // Image index, 0-9\n\"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.)\n}\n]\n}\n}\n]\n}\nRequest Header\nContent-Type\nstring\nRequired\nDefault to application/json\nData Exchange Format\nAuthorization\nstring\nRequired"
}