可灵-图像生成API参考

本文档仅适用于华北2（北京）地域，且必须使用该地域的API Key。

模型概览

模型名称	能力支持	输入模态	输出图像规格
kling/kling-v3-image-generation	文生图参考图生图：仅单图输入。	文本、图像	图像分辨率：1k、2k 宽高比：16:9、9:16、1:1 图像张数：通过参数n指定（1～9）图像格式：png
kling/kling-v3-omni-image-generation	文生图参考图生图：支持多图输入，支持生成分镜组图。	文本、图像	图像分辨率：1k、2k、4k 宽高比：16:9、9:16、1:1 图像张数：单图模式通过参数`n`指定：1～9 组图模式通过`series_amount`指定：2～9 图像格式：png

模型名称

能力支持

输入模态

输出图像规格

kling/kling-v3-image-generation

文生图
参考图生图：仅单图输入。

文本、图像

图像分辨率：1k、2k

宽高比：16:9、9:16、1:1

图像张数：通过参数n指定（1～9）

图像格式：png

kling/kling-v3-omni-image-generation

文生图
参考图生图：支持多图输入，支持生成分镜组图。

文本、图像

图像分辨率：1k、2k、4k

宽高比：16:9、9:16、1:1

图像张数：

单图模式通过参数n指定：1～9
组图模式通过series_amount指定：2～9

图像格式：png

前提条件

开通服务：前往阿里云百炼控制台，搜索“可灵”，找到可灵AI模型卡片，单击立即开通，在弹窗内确认开通及授权。
配置API Key：选择地域并获取与配置 API Key，再配置API Key到环境变量。

HTTP调用

图像生成任务有一定耗时（通常为1-2分钟），API采用异步调用。整个流程包含 "创建任务 -> 轮询获取" 两个核心步骤，具体如下：

步骤一：提交图像生成任务

北京地域：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求参数

请求头（Headers）

Content-Typestring（必选）请求内容类型。此参数必须设置为application/json。Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。X-DashScope-Asyncstring（必选）异步处理配置参数。HTTP请求只支持异步，必须设置为enable。

缺少此请求头将报错：“current user api does not support synchronous calls”。

请求体（Request Body）

model string （必选）模型名称。可选值：

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

input object （必选）输入参数对象，包含以下字段：

属性

messages array （必选）请求内容数组。当前仅支持单轮对话，因此数组内有且只有一个对象，该对象包含role和content两个属性。

属性

rolestring （可选）消息的角色。此参数必须设置为user。contentarray （必选）消息内容，包含文本提示词（text）和可选的参考图像（image，支持多张）。

属性

textstring（条件必选）正向提示词，用于描述期望生成的图像内容、风格和构图。支持中英文，长度不超过2500个字符，每个汉字、字母、数字或符号计为一个字符，超过将返回错误。示例值：一只坐着的橘黄色的猫，表情愉悦，活泼可爱，逼真准确。注意：仅支持传入一个text，不传或传入多个将报错。image string （可选）参考图像的URL。

支持 HTTP 或 HTTPS 协议。
示例值：https://xxx/xxx.png。

图像限制：

格式：JPEG、JPG、PNG（不支持透明通道）。
分辨率：宽和高的范围为[300, 8000]像素。
宽高比：在1:2.5 ~ 2.5:1之间。
文件大小：不超过10MB。
数量限制：参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。

element_list array （可选）主体列表，用于指定需要保持的主体。

属性

element_id integer （条件必填）传element_list时必填，表示主体ID。请在可灵-主体ID列表获取主体ID。数量限制：参考图片数量和参考主体数量（element_list数组长度）之和不得超过10。

parameters object （可选）控制图像生成，比如图像张数、宽高比等。

属性

n integer （可选）生成的图像张数。

kling/kling-v3-image-generation：取值范围为1～9。默认值为1。
kling/kling-v3-omni-image-generation：
- 当且仅当result_type=single时生效。
- 取值范围为1～9。默认值为1。

result_type string （可选）支持模型：kling/kling-v3-omni-image-generation。生成图像的类型。

single（默认值）：单图。批量生成时仅风格相似，无分镜关联。
series：组图。生成具有叙事/视觉连续性的分镜系列图像。

series_amount integer （可选）支持模型：kling/kling-v3-omni-image-generation。组图模式下的输出张数。取值范围为2～9，默认值为4。生效条件：当且仅当result_type=series时生效。aspect_ratio string （可选）输出图像的宽高比。

16:9：默认值。
9:16
1:1

示例值：16:9。resolution string （可选）输出图像分辨率。

kling/kling-v3-image-generation：可选值为1k、2k，默认值为1k。
kling/kling-v3-omni-image-generation：可选值为1k、2k、4k，默认值为1k。

示例值：1k。watermark bool （可选）是否同时生成含水印的图像。水印位于图像右下角，文案固定为”可灵AI”。

false：默认值，不生成含水印的图像。
true：同时生成含水印的图像。

示例值：false。

文生图
图生图（组图模式）

支持模型：kling/kling-v3-omni-image-generation、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": "一间有着精致窗户的花店,漂亮的木质门,摆放着花朵"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "n": 2,
        "aspect_ratio": "1:1",
        "resolution": "1k"
    }
}'

支持模型：kling/kling-v3-omni-image-generation。支持以下模式：

单图（result_type=single）：独立生成，批量时仅风格相似。
组图（result_type=series）：分镜序列生成，保持角色/场景/叙事连续性。

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": "参考图1的风格和图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"
    }
}'

响应参数

output object任务输出信息。

属性

task_id string任务ID。查询有效期24小时。task_status string任务状态。

枚举值

PENDING：任务排队中
RUNNING：任务处理中
SUCCEEDED：任务执行成功
FAILED：任务执行失败
CANCELED：任务已取消
UNKNOWN：任务不存在或状态未知

request_idstring请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数，详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误码。

成功响应
异常响应

请保存 task_id，用于查询任务状态与结果。

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

步骤二：查询任务结果

北京地域：GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} 调用时请将{WorkspaceId}替换为真实的业务空间ID。

轮询建议：图像生成过程约需数分钟，建议采用轮询机制，并设置合理的查询间隔（如 5 秒）来获取结果。
任务状态流转：PENDING（排队中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。
task_id 有效期：24小时，超时后将无法查询结果，接口将返回任务状态为UNKNOWN。
RPS 限制：查询接口默认RPS为20。如需更高频查询或事件通知，建议配置异步任务回调。
更多操作：如需批量查询、取消任务等操作，请参见管理异步任务。

请求参数

请求头（Headers）

Authorizationstring（必选）请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值：Bearer sk-xxxx。

URL路径参数（Path parameters）

task_id string（必选）任务ID。

查询任务结果

将{task_id}完整替换为上一步接口返回的task_id的值。task_id查询有效期为24小时，并请将{WorkspaceId}替换为真实的业务空间ID。

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

响应参数

output object任务输出信息。

属性

choices array模型生成的输出内容。此数组仅包含一个元素。

属性

finish_reason string任务停止原因，自然停止时为stop。message object模型返回的消息。

属性

rolestring消息的角色，固定为assistant。contentarray

属性

type string输出内容的类型。固定为image。image string生成图像的 URL，图像格式为PNG。链接有效期为30天，请及时下载并保存图像。

usage object输出信息统计。只对成功的结果计数。

属性

image_count integer生成图像的数量。size string生成图片的分辨率，格式为宽*高。示例值：1360*768。SR string生成图像的分辨率档位。示例值：1080。

任务执行成功
任务执行异常

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

如果因为某种原因导致任务执行失败，将返回相关信息，可以通过code和message字段明确指示错误原因。请参见错误码进行解决。

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

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

​模型概览

​前提条件

​HTTP调用

​步骤一：提交图像生成任务

请求参数

请求头（Headers）

请求体（Request Body）

响应参数

​步骤二：查询任务结果

请求参数

请求头（Headers）

URL路径参数（Path parameters）

响应参数

​错误码

模型概览

前提条件

HTTP调用

步骤一：提交图像生成任务

步骤二：查询任务结果

错误码