DocsICP FilingConsole
官方文档
首页

Kling - Image Generation API Reference

更新时间：
复制 MD 格式
产品详情
我的收藏

The Kling image generation model supports two tasks: text-to-image and reference image-to-image.

Important

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

Important

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

Prerequisites

  1. 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.

  2. 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

Text-to-image

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"
    }
}'

Image-to-image (storyboard mode)

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"
    }
}'
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.

Important

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

role string (optional)

The message role. Set this parameter to user.

content array (required)

Message content, including a text prompt (text) and optional reference images (image, multiple allowed).

Properties

text string (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.

Response parameters

Successful 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"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

Task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: The task does not exist or its status is unknown.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

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.

Note

  • 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

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"
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.

Response parameters

Task succeeded

{
    "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"
    }
}

Task failed

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"
}

output object

Task output information.

Properties

choices array

Model-generated output. This array contains exactly one element.

Properties

finish_reason string

Reason the task stopped. Value is stop for natural completion.

message object

Message returned by the model.

Properties

role string

Message role. Always assistant.

content array

Properties

type string

Type of output content. Always image.

image string

URL of the generated image in PNG format. The link expires after 30 days. Download and save the image promptly.

usage object

Statistics for successful outputs.

Properties

image_count integer

Number of generated images.

size string

Resolution of generated images in width*height format. Example value: 1360*768.

SR string

Resolution tier of generated images. Example value: 1080.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Error codes

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

Previous：KlingNext：Vidu