Kling Image 4.0
可灵的图片模型。每个任务根据文字、最多 10 张参考图和命名元素生成或编辑 1–9 张图片,支持 2K、4K 和 8K。
- 异步调用:创建请求会立即返回任务 ID,任务成功后即可取得图片。
- 一个任务用
n生成 1–9 张图片,每张按resolution档位计费。 - 支持文生图,也可以用公网 HTTPS 链接传入参考图和命名
elements(合计最多 10 个)进行编辑与合成。 - 在提示词里引用输入:
images按顺序写作@image_1、@image_2…,元素写作@加元素名。 - 按
resolution(2K、4K 或 8K)逐张计价,每张参考图和每个元素另收固定费用。任务失败不收费。
在调试窗口里打开本模型,填入你的 BeatAPI API 密钥即可创建任务。调用是真实的,费用从你自己的余额中扣除。
接口与鉴权
POST https://api.beatapi.io/v1/images/tasks
Authorization
string
必需
你的 BeatAPI API 密钥,以 Bearer <BEATAPI_API_KEY> 形式发送。在控制台创建密钥。密钥只能保存在你的服务端,不要放进浏览器或移动端应用。
请求体使用 JSON,并设置 Content-Type: application/json。Idempotency-Key 为可选:每个逻辑请求发送一个唯一值(最长 255 个字符),仅在重试完全相同的请求体时复用。24 小时内,用相同的键和请求体重试会再次返回第一次的响应,并带上 Idempotent-Replayed: true;相同的键搭配不同的请求体则返回 409 idempotency_conflict。非 2xx 的响应不会被保存,因此 400 或 402 之后的重试会重新执行。
请求流程
等待任务完成
调用 GET /v1/tasks/{task_id},两次调用之间等待 data.poll_after_seconds 秒(图片 5 秒,视频 8 秒),直到 status 为 succeeded 或 failed。也可以为 task.succeeded 和 task.failed 注册 Webhook;仍需保留轮询作为兜底,因为因处理超时而终止的任务不会发送事件。
输入模式
请求参数
model
string
必需
要调用的模型。
取值:kling-image-v4
取值有误时
- 未传:
"model" is required - 模型 ID 不存在:
"model" kling-image-v9 is not catalogued - 把视频模型发到了这个端点:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
prompt
string
必需
要画什么,或要在参考图上改什么:主体、风格、光线、构图以及必须出现在图中的文字,并用 @ 引用逐一指明各个输入。
长度:1–20000 个字符
- 长度按字符计(一个中日韩文字算一个字符)。
- 引用方式:
images按列表顺序写作@image_1、@image_2…,元素写作@加它的name。 - 每个
@image_N都必须对应同一请求中的一张图。只传两张图却写了@image_3,会在创建任务时被拒绝。
取值有误时
- 未传:
"prompt" is required - 为空或超过长度上限:
"prompt" has an unsupported length - 引用了请求中没有的图片:
the prompt names @image_3, which this request does not send
images
string[]
可选
要编辑或合成的参考图。在提示词中按列表顺序写作 @image_1、@image_2 …。
数量:1–10
每一项都必须是公网 https:// 链接。本地文件请先上传(POST /v1/files),再传入返回的 data.url。
- 每一项都必须是指向 JPEG 或 PNG 文件的公网
https://链接。创建任务时,BeatAPI 会读取每个链接;不是这类图片或超出下方限制的,会按位置指出并拒绝(images[0]是第一个链接)。 images与elements合计最多 10 个。- 每个链接都会给任务加一笔固定费用(见计费)。
取值有误时
- 超过上限:
"images" accepts at most 10 items - 空数组:
"images" requires at least 1 item - 不是 https:// 链接:
"images[0]" must be a public HTTPS URL - 链接不是 JPEG 或 PNG 文件(此例为 WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - 链接返回错误:
"images[0]" could not be downloaded: the URL returned HTTP 404 - 图片与元素合计超过 10 个:
Kling Image 4.0 takes at most 10 images and elements together
示例
elements
object[]
可选
命名主体,例如角色、动物、道具、服装或场景。每个元素用 2–4 张图片表示,在提示词中写作 @ 加它的 name。
数量:≤ 10
- 对象数组。每个对象只接受以下键:
elements[].name(字符串,必填):1–20 个字母、数字、下划线或汉字,同一请求内不区分大小写不得重复;不能是image_N、video_N、voice_N、keyframe_N、object_N、audio_N、first_frame或last_frame。elements[].element_input_urls(字符串数组,必填):2–4 个指向该元素图片的公网 HTTPS 链接,第一张是主视图。elements[].tag(字符串,可选):元素的类别。elements[].description(字符串,可选):元素说明,最多 100 个字符。- 元素只能由图片组成:本模型不接受视频元素和带声音的元素。
images与elements合计最多 10 个。每个元素给任务加一笔固定费用,与它包含几张图无关。
取值有误时
- 多于 10 个元素:
"elements" accepts at most 10 items - 元素不是对象:
"elements[0]" must be an object - 元素缺少
name:"name" is required in "elements[0]" - 元素缺少
element_input_urls:"element_input_urls" is required in "elements[0]" name为空或超过 20 个字符:"elements[0].name" has an unsupported lengthname含其他字符,或是保留名:elements[0].name "image_1" is not a name Kling V4 accepts- 同一个
name出现两次(不区分大小写):elements[1].name "Hero" is used twice - 图片少于两张:
"elements[0].element_input_urls" requires at least 2 item - 图片多于四张:
"elements[0].element_input_urls" accepts at most 4 items tag不在列表中:"elements[0].tag" must be one of: [character animal prop costume scene effect others]description超过 100 个字符:"elements[0].description" has an unsupported length- 元素里有不接受的键,例如视频:
field "element_input_video_urls" is not supported in "elements[0]"
示例
aspect_ratio
string
可选默认值: auto
图片的宽高比,写作 宽:高。
可选值:auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
默认值:auto
- 不传时使用
auto:由模型根据提示词和输入图决定画幅。对画面形状有要求时请明确传比例。
取值有误时
- 取值不在列表中:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
resolution
string
可选默认值: 2K
图片的尺寸档位:2K、4K 或 8K。每档每张单独定价。
可选值:2K, 4K, 8K
默认值:2K
- 不传时使用并按
2K计费。 - 2K 和 4K 返回 PNG,8K 返回 JPEG。
- K 必须大写:
2k会被拒绝。没有 1K 档,也不接受2048x2048这样的像素尺寸。
取值有误时
- 取值不在列表中(例如
1K或2k):"resolution" must be one of: [2K 4K 8K]
n
integer
可选默认值: 1
本任务要生成的图片张数。每张都使用相同的提示词、输入、比例和档位。
默认值:1
范围:1–9
- 不传时为
1。 - 每张图按
resolution的价格计费,所以n会成倍放大图片部分的价格;参考图和元素的费用每个任务只计一次,不按张数重复计。 - 按交付的图片张数计费。
取值有误时
- 超出范围、不是整数,或以字符串传入:
"n" is outside its supported range
网关还会在创建任务之前检查以下组合:
n让一次请求生成 1–9 张图;每张图按其分辨率档计费,images里的每张图和每个元素每次请求另计一次。- 提示词中按顺序用
@image_1、@image_2… 指代images里的图,用@加元素名指代元素;每个@image_N都必须对应同一请求中的一张图。 - 一个元素是
element_input_urls里同一主体的 2–4 张图(第一张为主视图);images与elements合计最多 10 个。 - 元素名为 1–20 个字母、数字、下划线或汉字,不区分大小写不得重复,且不能是
image_N、video_N、voice_N、keyframe_N、object_N、audio_N、first_frame或last_frame。 images里的图须为 JPEG 或 PNG,不超过 20 MB,宽高比在 2:5 到 5:2 之间,每边不超过 8192 px。2K和4K返回 PNG,8K返回 JPEG;aspect_ratio: auto由模型根据提示词和输入图决定画幅。
输入素材限制
网关会在创建任务之前读取每一项输入,超出这些限制的输入会被拒绝,并返回点名该输入的 400 bad_request。不扣费。
- 网关会在创建任务前读取
images中的每个链接,超出限制的会被拒绝,报错会指出是哪一个,例如images[0] has an aspect ratio of 3.10 (width/height); this model takes 0.4 to 2.5.不收费。 - 元素图片(
element_input_urls)在创建任务前只检查是否为公网 HTTPS 链接。请使用符合同样限制的 JPEG 或 PNG 文件。 - 本地文件请先用
POST /v1/files上传,再传入返回的data.url。
提示词中的引用
每种输入都有自己的引用写法:
- 没有对应图片的
@image_N会在创建任务时被拒绝,例如the prompt names @image_2, which this request does not send。
该模型不接受的字段
图片端点支持一些其他图片模型使用的字段。在这里传入它们会被拒绝而不是被忽略,因此你不会为没有效果的设置付费:
output_format、quality、seed、background、size、enhance_prompt→field "output_format" is not supported by model kling-image-v4(其中是你传入的字段名)。- 其他任何未知字段 →
unknown field: <name>。
如果请求中有多个无效字段,报错信息只会指出其中一个;修正后再次发送即可。
请求示例
文生图
根据提示词生成一张 2K 图片。
一个任务出四张
用同一提示词生成四张 4K 图片,每张按 4K 价格计费。
编辑一张图片
把一张商品照片重新构图为宣传图。
合成多张图片
在提示词中用引用逐一指明每张参考图。
命名元素
把同一主体的多个角度做成一个元素,再按名字放进画面。
响应
创建任务(201)
任务对象。任务成功之前 output 为 null。标注“运行中”的字段会在任务结束后消失。
任务完成
GET /v1/tasks/{task_id} 返回 HTTP 200 和 status: "succeeded",结果在 data.output 中。
输出字段
任务失败
失败的任务在 GET /v1/tasks/{task_id} 上仍然是 HTTP 200:失败信息在响应体里。预扣金额会全额退回,因此不会扣费。
完整示例
创建任务,按服务端给出的轮询提示等待,然后打印结果链接。请在环境变量中设置 BEATAPI_API_KEY 并安装 requests。
计费
- 每张图按
resolution定价(见下表),再乘以n。images里的每个链接和elements里的每个元素,每个任务各加一笔固定费用。 - 创建任务时会预留这笔费用:从余额扣,如果密钥设置了额度也从额度扣。在任务创建前就被拒绝的请求不收费。
- 任务成功后按交付的图片张数计费。任务失败时预留金额全额退回:
credits_refunded等于credits_reserved,credits_charged和credits_settled为 0。
当前牌价,与价格页一致。享有协商折扣的账户实付更低;任务的 data.usage 始终显示实际扣费金额。
常见错误
HTTP 错误速查
任务生成之前的错误会以非 2xx 响应返回,不扣费。请根据 error.code 或 error.retryable 判断处理方式;message 会指出问题所在。完整列表和重试策略见错误码。
身份验证
通过 Authorization: Bearer <BEATAPI_API_KEY> 发送 API 密钥。
请求头
请求体使用 JSON,并设置 Content-Type: application/json。Idempotency-Key 为可选:每个逻辑请求发送一个唯一值(最长 255 个字符),仅在重试完全相同的请求体时复用。24 小时内,用相同的键和请求体重试会再次返回第一次的响应,并带上 Idempotent-Replayed: true;相同的键搭配不同的请求体则返回 409 idempotency_conflict。非 2xx 的响应不会被保存,因此 400 或 402 之后的重试会重新执行。
请求
要调用的模型。
取值:kling-image-v4
取值有误时
- 未传:
"model" is required - 模型 ID 不存在:
"model" kling-image-v9 is not catalogued - 把视频模型发到了这个端点:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
要画什么,或要在参考图上改什么:主体、风格、光线、构图以及必须出现在图中的文字,并用 @ 引用逐一指明各个输入。
长度:1–20000 个字符
- 长度按字符计(一个中日韩文字算一个字符)。
- 引用方式:
images按列表顺序写作@image_1、@image_2…,元素写作@加它的name。 - 每个
@image_N都必须对应同一请求中的一张图。只传两张图却写了@image_3,会在创建任务时被拒绝。
取值有误时
- 未传:
"prompt" is required - 为空或超过长度上限:
"prompt" has an unsupported length - 引用了请求中没有的图片:
the prompt names @image_3, which this request does not send
图片的宽高比,写作 宽:高。
可选值:auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
默认值:auto
- 不传时使用
auto:由模型根据提示词和输入图决定画幅。对画面形状有要求时请明确传比例。
取值有误时
- 取值不在列表中:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
命名主体,例如角色、动物、道具、服装或场景。每个元素用 2–4 张图片表示,在提示词中写作 @ 加它的 name。
数量:≤ 10
- 对象数组。每个对象只接受以下键:
elements[].name(字符串,必填):1–20 个字母、数字、下划线或汉字,同一请求内不区分大小写不得重复;不能是image_N、video_N、voice_N、keyframe_N、object_N、audio_N、first_frame或last_frame。elements[].element_input_urls(字符串数组,必填):2–4 个指向该元素图片的公网 HTTPS 链接,第一张是主视图。elements[].tag(字符串,可选):元素的类别。elements[].description(字符串,可选):元素说明,最多 100 个字符。- 元素只能由图片组成:本模型不接受视频元素和带声音的元素。
images与elements合计最多 10 个。每个元素给任务加一笔固定费用,与它包含几张图无关。
取值有误时
- 多于 10 个元素:
"elements" accepts at most 10 items - 元素不是对象:
"elements[0]" must be an object - 元素缺少
name:"name" is required in "elements[0]" - 元素缺少
element_input_urls:"element_input_urls" is required in "elements[0]" name为空或超过 20 个字符:"elements[0].name" has an unsupported lengthname含其他字符,或是保留名:elements[0].name "image_1" is not a name Kling V4 accepts- 同一个
name出现两次(不区分大小写):elements[1].name "Hero" is used twice - 图片少于两张:
"elements[0].element_input_urls" requires at least 2 item - 图片多于四张:
"elements[0].element_input_urls" accepts at most 4 items tag不在列表中:"elements[0].tag" must be one of: [character animal prop costume scene effect others]description超过 100 个字符:"elements[0].description" has an unsupported length- 元素里有不接受的键,例如视频:
field "element_input_video_urls" is not supported in "elements[0]"
示例
"elements": [
{
"name": "Bottle",
"tag": "prop",
"description": "A matte smart water bottle",
"element_input_urls": [
"https://your-cdn.example.com/bottle-front.png",
"https://your-cdn.example.com/bottle-side.png"
]
}
]
要编辑或合成的参考图。在提示词中按列表顺序写作 @image_1、@image_2 …。
数量:1–10
每一项都必须是公网 https:// 链接。本地文件请先上传(POST /v1/files),再传入返回的 data.url。
- 每一项都必须是指向 JPEG 或 PNG 文件的公网
https://链接。创建任务时,BeatAPI 会读取每个链接;不是这类图片或超出下方限制的,会按位置指出并拒绝(images[0]是第一个链接)。 images与elements合计最多 10 个。- 每个链接都会给任务加一笔固定费用(见计费)。
取值有误时
- 超过上限:
"images" accepts at most 10 items - 空数组:
"images" requires at least 1 item - 不是 https:// 链接:
"images[0]" must be a public HTTPS URL - 链接不是 JPEG 或 PNG 文件(此例为 WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - 链接返回错误:
"images[0]" could not be downloaded: the URL returned HTTP 404 - 图片与元素合计超过 10 个:
Kling Image 4.0 takes at most 10 images and elements together
示例
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
]
本任务要生成的图片张数。每张都使用相同的提示词、输入、比例和档位。
默认值:1
范围:1–9
- 不传时为
1。 - 每张图按
resolution的价格计费,所以n会成倍放大图片部分的价格;参考图和元素的费用每个任务只计一次,不按张数重复计。 - 按交付的图片张数计费。
取值有误时
- 超出范围、不是整数,或以字符串传入:
"n" is outside its supported range
图片的尺寸档位:2K、4K 或 8K。每档每张单独定价。
可选值:2K, 4K, 8K
默认值:2K
- 不传时使用并按
2K计费。 - 2K 和 4K 返回 PNG,8K 返回 JPEG。
- K 必须大写:
2k会被拒绝。没有 1K 档,也不接受2048x2048这样的像素尺寸。
取值有误时
- 取值不在列表中(例如
1K或2k):"resolution" must be one of: [2K 4K 8K]
响应
任务对象。任务成功之前 output 为 null。标注“运行中”的字段会在任务结束后消失。

