ToAPIsToAPIs
Kling Image 4.0

Kling Image 4.0 长图生成

以 1K 或 2K 生成网页设计或电商商品详情长图

POST
/v1/images/generations

国内用户请注意: 中国大陆用户请使用 https://toapis.cn 作为接口地址 (Base URL).文档示例中的 https://toapis.com 请替换为 https://toapis.cn.

kling-image-4.0-long 每次异步生成一张长图. 网页设计选择 webpage, 电商商品详情选择 ecommerce.

Authorizations

Authorizationstring请求头必填

所有接口均需要使用 Bearer Token 进行认证

获取 API Key: 访问 API Key 管理页面 获取您的 API Key

使用时在请求头中添加:

Authorization: Bearer YOUR_API_KEY

Body

使用 application/json 提交请求, 以下参数均放在请求体顶层.

modelstring请求体必填默认值: kling-image-4.0-long

固定为 kling-image-4.0-long.

promptstring请求体必填

填写非空文本, 描述要生成的版式和内容.

skillstring请求体必填

webpage 生成网页设计长图, ecommerce 生成电商商品详情长图.

resolutionstring请求体默认值: 1K

支持 1K 和 2K, 不区分大小写.

ninteger请求体默认值: 1

生成图片数量, 固定为 1. 可省略此字段. 传入时只接受整数 1.

lengthstring请求体

仅用于 ecommerce. short 约 2-5 个内容模块, medium 约 6-10 个 (默认), long 约 11-18 个. 所有模块合成一张图.

image_urlsstring[]请求体

ecommerce 必须提供 1 到 3 张有序的商品参考图, 使用此字段或 reference_images. 提示词中的 @image_1, @image_2 和 @image_3 按列表顺序引用图片.

reference_imagesstring[]请求体

ecommerce 可用此字段代替 image_urls. 两个字段只传一个.

style_reference_image_urlstring请求体

仅用于 webpage, 可选. 传入一张用于指导画面风格的参考图 URL.

subject_reference_image_urlstring请求体

仅用于 webpage, 可选. 传入一张用于提供画面主体的参考图 URL.

callback_urlstring请求体

可选的任务结束通知地址. 使用已配置的 Token 任务 Webhook 时, 保持默认地址的协议、主机和端口一致. 省略时使用该 Token 已启用的默认地址.

参考图须使用服务可访问的 HTTP(S) URL. 可通过上传图片 API为本地文件获取 URL.

参数限制

webpage 必须省略 length, image_urls 和 reference_images, 这些字段即使传空数组或 null 也会被拒绝. 两个角色参考图字段均省略时, 按纯文本生成. ecommerce 必须省略 style_reference_image_url 和 subject_reference_image_url.

请省略 size, aspect_ratio, ratio, series_amount, result_type, contents, options 和 settings.

查询任务

收到 id 后, 用同一个 API Key 查询图片任务. queued 和 in_progress 表示任务尚未结束. completed 时从 result.data[0].url 读取图片地址, failed 时查看 error.

curl "https://toapis.com/v1/images/generations/TASK_ID" \
  -H "Authorization: Bearer $TOAPIS_API_KEY"

计费

基础费用按次收取, 取决于计费区域, skill 和 resolution. ecommerce 的价格还取决于 length. 使用同一 API Key 查询 GET /v1/pricing?model=kling-image-4.0-long. 国内区目录追加 &region=cn, 国际区目录追加 &region=global. 省略时返回 global 目录, 接口域名不会改变这个默认值.

匹配的价格条目有 input_image_unit_price 时, 超出 free_input_image_count 的参考图按张加收费用. 确认后的实际费用见任务的 billing. 详见实际费用和任务用量.

Response

idstring

任务唯一标识符, 用于查询任务状态

objectstring

对象类型, 固定为 generation.task

modelstring

使用的模型名称

statusstring

提交成功时为 queued.

progressinteger

任务进度百分比(0-100)

created_atinteger

任务创建时间戳(Unix 时间戳)

metadataobject

任务元数据

result.data[].urlstring

任务完成后返回的单张图片 URL.

执行示例前设置 TOAPIS_API_KEY 环境变量. 参考图示例中的 example.com 是占位地址, 请替换为可访问的图片 URL.

请求示例

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "kling-image-4.0-long",
  "prompt": "为一家陶艺工作室设计长版落地页. 沿用风格参考图的视觉风格, 以主体参考图中的手工马克杯为主角, 加入课程时间表和预约区.",
  "skill": "webpage",
  "n": 1,
  "resolution": "1K",
  "style_reference_image_url": "https://example.com/pottery-style.png",
  "subject_reference_image_url": "https://example.com/handmade-mug.png"
}'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "kling-image-4.0-long",
  "prompt": "为 @image_1 中的台灯生成商品详情长图. 用 @image_2 展示控制按钮的特写, 加入亮度档位, 产品尺寸和包装清单.",
  "skill": "ecommerce",
  "n": 1,
  "resolution": "2K",
  "length": "medium",
  "image_urls": [
    "https://example.com/desk-lamp.png",
    "https://example.com/lamp-controls.png"
  ]
}'

响应示例

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "kling-image-4.0-long",
  "status": "queued",
  "progress": 0,
  "created_at": 1794960000,
  "metadata": {}
}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "kling-image-4.0-long",
  "status": "completed",
  "progress": 100,
  "created_at": 1794960000,
  "metadata": {},
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://example.com/generated/kling-image-4.0-long.png"
      }
    ]
  }
}