Kling - Image Generation API Reference

This document applies only to the China (Beijing) region. Use an API key from this region.

Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope.aliyuncs.com to the new domain.{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Model overview

Model name	Capabilities	Input modality	Output image specifications
kling/kling-v3-image-generation	Text-to-image Reference image-to-image: accepts only a single input image.	Text, image	Image resolution: 1k, 2k Aspect ratio: 16:9, 9:16, 1:1 Number of images: specified by parameter n (1–9) Image format: png
kling/kling-v3-omni-image-generation	Text-to-image Reference image-to-image: supports multiple input images and storyboard generation.	Text, image	Image resolution: 1k, 2k, 4k Aspect ratio: 16:9, 9:16, 1:1 Number of images: Single-image mode: specified by parameter `n` (1–9) Storyboard mode: specified by `series_amount` (2–9) Image format: png

Model name

Capabilities

Input modality

Output image specifications

kling/kling-v3-image-generation

Text-to-image
Reference image-to-image: accepts only a single input image.

Text, image

Image resolution: 1k, 2k

Aspect ratio: 16:9, 9:16, 1:1

Number of images: specified by parameter n (1–9)

Image format: png

kling/kling-v3-omni-image-generation

Text-to-image
Reference image-to-image: supports multiple input images and storyboard generation.

Text, image

Image resolution: 1k, 2k, 4k

Aspect ratio: 16:9, 9:16, 1:1

Number of images:

Single-image mode: specified by parameter n (1–9)
Storyboard mode: specified by series_amount (2–9)

Image format: png

Prerequisites

Activate the service: Go to the Alibaba Cloud Model Studio console, search for “Kling”, find the Kling AI model card, click Activate Now, and confirm activation and authorization in the pop-up window.
Configure your API key: Select the region and retrieve your API key, then configure the API key as an environment variable.

HTTP invocation

Image generation takes time, typically one to two minutes. The API uses asynchronous invocation. The full process includes two core steps: Create task → Poll for results, as follows:

Step 1: Submit an image generation task

Beijing region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Request headers

Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.

If this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body

model string (required)The model name. Valid values:

kling/kling-v3-image-generation
kling/kling-v3-omni-image-generation

input object (required)Input parameters object, containing the following fields:

Properties

messages array (required)An array of request content. Only single-turn conversations are supported, so the array must contain exactly one object with the properties role and content.

Properties

rolestring (optional)The message role. Set this parameter to user.contentarray (required)Message content, including a text prompt (text) and optional reference images (image, multiple allowed).

Properties

textstring(conditionally required)A positive prompt describing the desired image content, style, and composition.Supports Chinese and English. Maximum length is 2500 characters. Each Chinese character, letter, digit, or symbol counts as one character. Exceeding the limit will result in an error.Example value: A sitting orange cat with a happy expression, lively and cute, photorealistic.Note: Only one text field is allowed. Omitting it or providing multiple will cause an error.image string (optional)URL of a reference image.

Supports HTTP or HTTPS protocols.
Example value: https://xxx/xxx.png.

Image constraints:

Format: JPEG, JPG, or PNG (alpha channel not supported).
Resolution: width and height between 300 and 8000 pixels.
Aspect ratio: between 1:2.5 and 2.5:1.
File size: no more than 10 MB.
Quantity limit: the total number of reference images plus reference subjects (element_list array length) must not exceed 10.

element_list array (optional)List of subjects to preserve.

Properties

element_id integer (conditionally required)Required when element_list is provided. Represents the subject ID. Retrieve subject IDs from Kling - Subject ID list.Quantity limit: the total number of reference images plus reference subjects (element_list array length) must not exceed 10.

parameters object (optional)Controls image generation, such as number of images and aspect ratio.

Properties

n integer (optional)Number of images to generate.

kling/kling-v3-image-generation: valid range 1–9. Default is 1.
kling/kling-v3-omni-image-generation:
- Takes effect only when result_type=single.
- Valid range 1–9. Default is 1.

result_type string (optional)Supported model: kling/kling-v3-omni-image-generation.Type of generated images.

single (default): single image. Batch outputs share similar style but no storyboard continuity.
series: storyboard. Generates a series of images with narrative or visual continuity.

series_amount integer (optional)Supported model: kling/kling-v3-omni-image-generation.Number of images in storyboard mode. Valid range 2–9. Default is 4.Takes effect only when result_type=series.aspect_ratio string (optional)Aspect ratio of the output image.

16:9: default.
9:16
1:1

Example value: 16:9.resolution string (optional)Output image resolution.

kling/kling-v3-image-generation: valid values 1k, 2k. Default is 1k.
kling/kling-v3-omni-image-generation: valid values 1k, 2k, 4k. Default is 1k.

Example value: 1k.watermark bool (optional)Specifies whether to simultaneously generate a watermarked version of the image. The watermark appears in the bottom-right corner with fixed text “Kling AI”.

false: Default value. No watermarked image is generated.
true: A watermarked image is generated simultaneously.

Example value: false.

Text-to-image
Image-to-image (storyboard mode)

Supported models: kling/kling-v3-omni-image-generation and kling/kling-v3-image-generation.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling/kling-v3-image-generation",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "A flower shop with delicate windows and a beautiful wooden door, filled with flowers"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "n": 2,
        "aspect_ratio": "1:1",
        "resolution": "1k"
    }
}'

Supported model: kling/kling-v3-omni-image-generation.Supports the following modes:

Single image (result_type=single): generated independently; batch outputs share similar style only.
Storyboard (result_type=series): generates a sequence of shots with consistent characters, scenes, and narrative continuity.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling/kling-v3-omni-image-generation",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Generate tomato scrambled eggs in the style of reference image 1 and background of reference image 2"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    },
                    {
                        "image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "n": 4,
        "result_type": "series",
        "aspect_ratio": "1:1",
        "resolution": "1k"
    }
}'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

Successful response
Error response

Save the task_id to query the task status and result.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query task results

Beijing region: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} Replace {WorkspaceId} with your actual workspace ID.

Polling recommendation: Image generation takes several minutes. Use a polling mechanism with a reasonable interval, such as five seconds, to fetch results.
Task status flow: PENDING (queued) → RUNNING (in progress) → SUCCEEDED (success) or FAILED (failure).
task_id validity: 24 hours. After expiration, results cannot be retrieved and the API returns status UNKNOWN.
RPS limit: The query endpoint has a default RPS of 20. For higher-frequency polling or event notifications, configure asynchronous task callbacks.
Additional operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

Request parameters

Request headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

URL path parameters

task_id string (Required)The ID of the task.

Query task results

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectTask output information.

Properties

choices arrayModel-generated output. This array contains exactly one element.

Properties

finish_reason stringReason the task stopped. Value is stop for natural completion.message objectMessage returned by the model.

Properties

rolestringMessage role. Always assistant.contentarray

Properties

type stringType of output content. Always image.image stringURL of the generated image in PNG format. The link expires after 30 days. Download and save the image promptly.

usage objectStatistics for successful outputs.

Properties

image_count integerNumber of generated images.size stringResolution of generated images in width*height format. Example value: 1360*768.SR stringResolution tier of generated images. Example value: 1080.

Task succeeded
Task failed

{
    "request_id": "95146d89-9d70-481a-8c16-xxxxxx",
    "output": {
        "task_id": "2c502d25-12a9-4517-8972-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 22:46:01.536",
        "scheduled_time": "2026-03-27 22:46:01.580",
        "end_time": "2026-03-27 22:46:24.831",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://p4-fdl.klingai.com/xxx.png?xxx",
                            "type": "image"
                        },
                        {
                            "image": "https://p4-fdl.klingai.com/xxx.png?xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "size": "1024*1024",
        "image_count": 2,
        "SR": "1080"
    }
}

If the task fails for any reason, the response includes error details in the code and message fields. See Error messages for troubleshooting.

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

​Model overview

​Prerequisites

​HTTP invocation

​Step 1: Submit an image generation task

Request parameters

Request headers

Request body

Response parameters

​Step 2: Query task results

Request parameters

Request headers

URL path parameters

Response parameters

​Error codes

Model overview

Prerequisites

HTTP invocation

Step 1: Submit an image generation task

Step 2: Query task results

Error codes