Kling 3.0

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口

POST /jobs/createTask

完整 URL: https://ai.modelfold.online/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

使用 Kling 3.0 AI 模型生成具有高级多镜头功能和元素引用的高质量视频。

概述

Kling 3.0 是一个先进的视频生成模型，支持单镜头和多镜头视频创作，并支持元素引用功能。它提供三档模式：std、pro、4K，以及不同的分辨率选项，并支持音效以增强视频输出。

主要特性

多种生成模式：可在 std（标准分辨率）、pro（更高分辨率）和 4K（超高分辨率）模式之间选择
多镜头支持：创建包含多个镜头的视频，每个镜头都有自己的提示词和时长
元素引用：使用 @element_name 语法在提示词中引用图像/视频/音频元素
原生音频：对白、音效、环境声
灵活的宽高比：支持 16:9、9:16 和 1:1 宽高比
可配置时长：视频时长从 3 到 15 秒

TIP

std、pro 模式下开启声音价格更高。多镜头模式按各镜头时长之和计费。当前价格见 ai.modelfold.online/pricing。

分辨率映射

分辨率取决于 mode 和 aspect_ratio 参数：

标准模式 (std)

宽高比	分辨率
16:9	1280×720
9:16	720×1280
1:1	720×720

专业模式 (pro)

宽高比	分辨率
16:9	1920×1080
9:16	1080×1920
1:1	1440×1440

4K模式 (4K)

宽高比	分辨率
16:9	3840×2160
9:16	2160×3840
1:1	2160×2160

INFO

4K模式提供更高分辨率的输出，但可能需要更长的生成时间并消耗更多积分。

单镜头与多镜头模式

单镜头模式 (`multi_shots: false`)

使用主 prompt 字段进行视频生成
通过 image_urls 支持首帧和尾帧图像
音效为可选

多镜头模式 (`multi_shots: true`)

使用 multi_prompt 数组定义多个镜头
每个镜头有自己的提示词和时长（1-12 秒）
仅支持首帧图像（通过 image_urls[0]）
每个镜头最大字符数为500

元素引用

您可以使用 @element_name 语法在提示词中引用元素。在 kling_elements 数组中定义元素：

图像元素：2-4 个图像 URL（JPG/PNG，每个最大 10MB）
视频元素：最多上传 1个视频 URL（MP4/MOV，视频时长需大于等于 3 秒，有效片段长度需保持在 3-8 秒）
音频参考：最多上传 1 个音频 URL（音频时长必须为 5-30 秒）

INFO

使用描述性的元素名称，并确保 kling_elements 中的元素名称与提示词中使用的名称匹配（不带 @ 符号）。单个任务最多引用3个元素，且每个@element占37个字符。

文件上传要求

在使用元素引用之前，请上传您的图像：

1. 上传文件

使用文件上传 API 上传您的源图像。

文件上传 API

了解如何上传文件并获取文件 URL，请参阅文件上传 API 快速入门。

2. 获取文件 URL

上传后，您将收到可用于 element_input_urls 和 element_input_audio_urls 的文件 URL。 ::: caution

格式：
- 图片（JPG、PNG，每个文件最大 10MB，每个元素 2-4 个文件）
- 视频（MP4、MOV，视频时长需大于等于 3 秒，有效片段长度需保持在 3-8 秒）
- 音频（音频时长必须为 5-30 秒）
确保文件 URL 可访问且未过期 :::

使用示例

带元素引用的单镜头视频

json

{
  "model": "kling-3.0/video",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window@element_dog",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": false,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "multi_shots": false,
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ]
      }
    ]
  }
}

多镜头视频

json

{
  "model": "kling-3.0/video",
  "input": {
    "multi_shots": true,
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": false,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "multi_prompt": [
      {
        "prompt": "a happy dog in running @element_cat",
        "duration": 2
      },
      {
        "prompt": "a happy dog play with a cat @element_dog",
        "duration": 3
      }
    ],
    "kling_elements": [
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [
          "https://your-cdn.com/element_image.jpg",
          "https://your-cdn.com/element_image2.jpg"
        ]
      },
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ]
      }
    ]
  }
}

查询任务状态

提交任务后，使用统一查询端点检查进度并检索结果：

获取任务详情

了解如何查询任务状态和检索生成结果，请参阅获取任务详情。

TIP

对于生产环境使用，我们建议使用 callBackUrl 参数在生成完成时接收自动通知，而不是轮询状态端点。

最佳实践

提示词编写：在提示词中具体且详细。包括关于运动、相机角度和场景构图的细节
元素使用：使用高质量的参考图像/视频/音频以获得更好的效果。确保元素与视频的风格和主题匹配
时长规划：对于多镜头视频，规划镜头时长以匹配总视频时长
模式选择：当质量重要时使用 4K 模式进行最终输出，在需要快速迭代时使用 std 模式
音效：为更具沉浸感的视频启用音效，特别是动作或动态场景

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0/video` 模型默认值：`"kling-3.0/video"`。可选值：`kling-3.0/video`。示例：`kling-3.0/video`。
`callBackUrl`	`string`	否	接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 Webhook 校验指南了解签名验证实现方法示例：`https://your-domain.com/api/callback`。
`input`	`object`	否	生成任务的输入参数
`input.prompt`	`string`	否	multi_shots 为 false 时必填，最长 2500 字符。示例：`In a bright rehearsal room, sunlight streams through the window@element_dog`。
`input.image_urls`	`array<string>`	否	首尾帧图片链接。可选。当 multi_shots 为 false 时：长度为 2 时，索引 0 为首帧，索引 1 为尾帧；长度为 1 时，数组项作为首帧。当 multi_shots 为 true 时：只支持首帧。
`input.sound`	`boolean`	是	必填。是否同时生成音频（对白、音效、环境声），影响价格。示例：`true`。
`input.duration`	`string`	是	必填。视频时长（秒），3–15（字符串，如 "5"）。多镜头模式下实际时长与计费按各镜头时长之和（3–15 秒），duration 请填同一合计值。可选值：`3` / `4` / `5` / `6` / `7` / `8` / `9` / `10` / `11` / `12` / `13` / `14` / `15`。示例：`5`。
`input.aspect_ratio`	`string`	否	传了 image_urls 时可省略（输出比例跟随首帧）。文生视频请显式传入：16:9、9:16 或 1:1。可选值：`16:9` / `9:16` / `1:1`。示例：`16:9`。
`input.mode`	`string`	是	必填。生成模式。std 为标准分辨率，pro 为高分辨率，4K 为 4K 分辨率。分辨率映射： - std 模式：16:9 (1280×720), 9:16 (720×1280), 1:1 (720×720) - pro 模式：16:9 (1920×1080), 9:16 (1080×1920), 1:1 (1080×1080) - 4K 模式：16:9 (3840×2160), 9:16 (2160×3840), 1:1 (2160×2160) 可选值：`std` / `pro` / `4K`。示例：`pro`。
`input.multi_shots`	`boolean`	是	必填。是否多镜头。true 时为多镜头，false 为单镜头。示例：`false`。
`input.multi_prompt`	`array<object>`	否	镜头提示词。multi_shots 为 true 时生效。用来描述每一段镜头的文案和时长，最多支持 5 段，每段时长 1-12 秒，如果需要使用 element，则需加在 prompt 后。
`input.multi_prompt[].prompt`	`string`	是	该镜头的提示词文本，单个镜头最多500字符，每个@element会占37个字符。示例：`a happy dog in running@element_cat`。
`input.multi_prompt[].duration`	`integer`	是	该镜头的时长（单位：秒）。范围：1-12。示例：`3`。
`input.kling_elements`	`array<object>`	否	引用元素。prompt 中引用元素的详细信息。单个任务最多引用三个元素。
`input.kling_elements[].name`	`string`	是	元素名称，在 prompt 中使用 @ 前缀引用（如 @element_dog）示例：`element_dog`。
`input.kling_elements[].description`	`string`	是	元素描述示例：`dog`。
`input.kling_elements[].element_input_urls`	`array<string>`	是	2–4 张图片（JPG/PNG，单张不超过 10MB），或 1 个视频（MP4/MOV）。
`input.kling_elements[].element_input_audio_urls`	`array<string>`	否	可选。角色音频素材 URL 列表。音频时长必须为 5-30 秒
`input.kling_elements[].start_time`	`integer`	否	视频角色素材截取开始时间，单位毫秒。仅 element_input_urls 上传视频时生效。未传时默认 0。默认值：`0`。示例：`0`。
`input.kling_elements[].end_time`	`integer`	否	视频角色素材截取结束时间，单位毫秒。仅 element_input_urls 上传视频时生效。必须大于 start_time，且 end_time - start_time 必须在 3000-8000ms。默认值：`8000`。示例：`8000`。

请求示例

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling-3.0/video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window@element_dog",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": true,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_shots": false,
    "multi_prompt": [
      {
        "prompt": "a happy dog in running@element_cat",
        "duration": 3
      },
      {
        "prompt": "a happy dog play with a cat@element_dog",
        "duration": 3
      }
    ],
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ]
      },
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [
          "https://your-cdn.com/element_image.mp4"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ],
        "start_time": 0,
        "end_time": 8000
      }
    ]
  }
}'

json

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window@element_dog",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1764851002741_i0lEiI8I.png"
    ],
    "sound": true,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_shots": false,
    "multi_prompt": [
      {
        "prompt": "a happy dog in running@element_cat",
        "duration": 3
      },
      {
        "prompt": "a happy dog play with a cat@element_dog",
        "duration": 3
      }
    ],
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/your-image.png",
          "https://example.com/your-image.png"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ]
      },
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [
          "https://your-cdn.com/element_image.mp4"
        ],
        "element_input_audio_urls": [
          "https://your-cdn.com/wjeoiajfosijfoi.mp3"
        ],
        "start_time": 0,
        "end_time": 8000
      }
    ]
  }
}

响应

200 — 请求成功

参数	类型	必填	说明
`code`	`integer`	是	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200` / `401` / `402` / `404` / `422` / `429` / `433` / `455` / `500` / `501` / `505`。示例：`200`。
`msg`	`string`	是	响应消息，失败时的错误描述
`data`	`object`	是	—
`data.taskId`	`string`	是	可以使用任务 ID 与“获取任务详细信息”端点一起查询任务状态。

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_kling-3.0_1765187774173"
  }
}

回调

videoTaskCompleted

回调地址：{request.body#/callBackUrl}（即请求体里的 callBackUrl）。

当 kling-3.0/video 任务成功或失败时，系统会发送此回调。

回调体参数

参数	类型	必填	说明
`code`	`integer`	是	统一回调状态码：成功为 200，失败为 501。可选值：`200` / `501`。示例：`200`。
`msg`	`string`	是	统一回调消息。可选值：`Playground task completed successfully.` / `Playground task failed.`。示例：`Playground task completed successfully.`。
`data`	`object`	是	—
`data.taskId`	`string`	是	任务唯一标识符。
`data.model`	`string`	是	任务使用的模型。可选值：`kling-3.0/video`。示例：`kling-3.0/video`。
`data.state`	`string`	是	任务最终状态。可选值：`success` / `fail`。示例：`success`。
`data.param`	`string`	是	包含已提交任务参数的 JSON 字符串。
`data.resultJson`	`string`	否	任务成功时，包含 resultUrls、firstFrameUrl、lastFrameUrl 或 resultObject 的 JSON 字符串。仅在 state 为 success 时出现。
`data.failCode`	`string`	否	失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。
`data.failMsg`	`string`	否	失败原因，仅在 state 为 fail 时出现。
`data.costTime`	`integer`	否	处理耗时（秒），成功和失败回调都会返回。
`data.completeTime`	`integer`	否	任务完成时间戳。
`data.createTime`	`integer`	否	任务创建时间戳。
`data.updateTime`	`integer`	否	完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。
`data.creditsConsumed`	`number`	否	本任务消耗的积分；失败任务为 0。

任务成功完成

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "kling-3.0/video",
    "state": "success",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"In a bright rehearsal room, sunlight streams through the window @element_dog\\\",\\\"image_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"sound\\\":true,\\\"duration\\\":\\\"5\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"mode\\\":\\\"pro\\\",\\\"multi_shots\\\":false,\\\"multi_prompt\\\":[{\\\"prompt\\\":\\\"a happy dog in running @element_cat\\\",\\\"duration\\\":3}],\\\"kling_elements\\\":[{\\\"name\\\":\\\"element_dog\\\",\\\"description\\\":\\\"dog\\\",\\\"element_input_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"element_input_audio_urls\\\":[\\\"https://example.com/input-audio.mp3\\\"]}]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"kling-3.0/video\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

任务失败

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "kling-3.0/video",
    "state": "fail",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"In a bright rehearsal room, sunlight streams through the window @element_dog\\\",\\\"image_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"sound\\\":true,\\\"duration\\\":\\\"5\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"mode\\\":\\\"pro\\\",\\\"multi_shots\\\":false,\\\"multi_prompt\\\":[{\\\"prompt\\\":\\\"a happy dog in running @element_cat\\\",\\\"duration\\\":3}],\\\"kling_elements\\\":[{\\\"name\\\":\\\"element_dog\\\",\\\"description\\\":\\\"dog\\\",\\\"element_input_urls\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"element_input_audio_urls\\\":[\\\"https://example.com/input-audio.mp3\\\"]}]}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"kling-3.0/video\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

Kling 3.0 ​

接口 ​

概述 ​

主要特性 ​

分辨率映射 ​

标准模式 (std) ​

专业模式 (pro) ​

4K模式 (4K) ​

单镜头与多镜头模式 ​

单镜头模式 (multi_shots: false) ​

多镜头模式 (multi_shots: true) ​

元素引用 ​

文件上传要求 ​

1. 上传文件 ​

2. 获取文件 URL ​

使用示例 ​

带元素引用的单镜头视频 ​

多镜头视频 ​

查询任务状态 ​

最佳实践 ​

相关资源 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — 请求成功 ​

回调 ​

videoTaskCompleted ​

Kling 3.0

接口

概述

主要特性

分辨率映射

标准模式 (std)

专业模式 (pro)

4K模式 (4K)

单镜头与多镜头模式

单镜头模式 (`multi_shots: false`)

多镜头模式 (`multi_shots: true`)

元素引用

文件上传要求

1. 上传文件

2. 获取文件 URL

使用示例

带元素引用的单镜头视频

多镜头视频

查询任务状态

最佳实践

相关资源

请求参数

请求体 (application/json)

请求示例

响应

200 — 请求成功

回调

videoTaskCompleted