Kling 4.0 关键帧生成视频

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

接口

POST /jobs/createTask

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

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

使用 Kling 4.0，根据首帧、中间帧和尾帧图片生成视频。在提示词中用 @first_frame、@keyframe_1、@last_frame 引用对应帧。

查询任务状态

提交任务后，可通过统一查询接口查看进度并获取结果：

获取任务详情 — 了解如何查询任务状态及获取生成结果

TIP

生产环境建议使用 callBackUrl 参数接收生成完成的自动通知，而非轮询状态接口。

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-4.0/keyframe-to-video` 模型默认值：`"kling-4.0/keyframe-to-video"`。可选值：`kling-4.0/keyframe-to-video`。示例：`kling-4.0/keyframe-to-video`。
`callBackUrl`	`string`	否	接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 Webhook 校验指南了解签名验证实现方法示例：`https://your-domain.com/api/callback`。
`input`	`object`	是	生成任务的输入参数。
`input.prompt`	`string`	是	视频描述，必填，最多 8000 个字符。用 `@first_frame`、`@keyframe_1`、`@keyframe_2`…、`@last_frame` 引用本次请求已传入的帧，只能引用实际提供的帧。每个 `@` 引用都必须能匹配到本次请求已传入的素材，否则请求会被拒绝。引用按已声明名称做最长匹配；若匹配到的名称以字母、数字或下划线结尾，紧跟的下一个字符不能再是字母、数字或下划线。示例：`@first_frame 里的女孩出门，经过 @keyframe_1 的街道，最后到达 @last_frame 的晚会`。
`input.duration`	`integer`	否	输出视频时长（秒），3–30 的整数，默认 `5`。同时限制总帧数（首帧 + 中间帧 + 尾帧）： - 3 秒 → 4 帧 - 4 秒 → 5 帧 - 5 秒 → 6 帧 - 6 秒 → 7 帧 - 7 秒 → 8 帧 - 8 秒 → 9 帧 - 9 秒及以上 → 10 帧默认值：`5`。示例：`5`。
`input.resolution`	`string`	否	输出分辨率：`720p` 或 `1080p`，默认 `720p`。默认值：`"720p"`。可选值：`720p` / `1080p`。示例：`720p`。
`input.aspect_ratio`	`string`	否	输出画面比例。只在一帧都不传时生效（纯文生视频），默认 `16:9`；传了任意帧时跟随首帧比例。可选值：`auto` / `16:9` / `9:16` / `1:1` / `21:9`。示例：`auto`。
`input.first_frame_url`	`string`	否	首帧图片地址。提示词里用 `@first_frame` 引用。
`input.keyframe_urls`	`array<string>`	否	中间帧图片地址，按时间顺序，最多 8 张（同时受 `duration` 限制）。提示词里用 `@keyframe_1`、`@keyframe_2`… 引用。默认值：`[]`。
`input.last_frame_url`	`string`	否	尾帧图片地址。提示词里用 `@last_frame` 引用。

请求示例

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-4.0/keyframe-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "@first_frame 里的女孩出门，经过 @keyframe_1 的街道，最后到达 @last_frame 的晚会",
    "duration": 10,
    "resolution": "720p",
    "first_frame_url": "https://example.com/first.png",
    "keyframe_urls": [
      "https://example.com/street.png"
    ],
    "last_frame_url": "https://example.com/party.png"
  }
}'

json

{
  "model": "kling-4.0/keyframe-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "@first_frame 里的女孩出门，经过 @keyframe_1 的街道，最后到达 @last_frame 的晚会",
    "duration": 10,
    "resolution": "720p",
    "first_frame_url": "https://example.com/first.png",
    "keyframe_urls": [
      "https://example.com/street.png"
    ],
    "last_frame_url": "https://example.com/party.png"
  }
}

响应

200 — 请求成功

参数	类型	必填	说明
`code`	`integer`	否	响应状态码 - 200: 成功 - 请求已处理完成 - 401: 未授权 - 身份验证凭据缺失或无效 - 402: 积分不足 - 账户余额不足以执行该操作 - 404: 未找到 - 请求的资源或接口不存在 - 422: 参数验证错误 - 请求参数未通过校验 - 429: 调用频率超限 - 已超出该资源的请求限制 - 433: 子密钥使用超限 - 455: 服务不可用 - 系统正在维护中 - 500: 服务器内部错误 - 处理请求时发生意外故障 - 501: 生成失败 - 内容生成任务执行失败 - 505: 功能禁用 - 当前请求的功能已被禁用可选值：`200` / `401` / `402` / `404` / `422` / `429` / `433` / `455` / `500` / `501` / `505`。示例：`200`。
`msg`	`string`	否	响应消息，请求失败时返回错误描述示例：`success`。
`data`	`object`	是	—
`data.taskId`	`string`	是	任务 ID，可结合「获取任务详情」接口查询任务状态

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_kling-4.0-keyframe-to-video_abc123"
  }
}

回调

videoTaskCompleted

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

当 kling-4.0/keyframe-to-video 任务成功或失败时，系统会向 callBackUrl 发送此 POST 回调。

回调体参数

参数	类型	必填	说明
`code`	`integer`	是	统一回调状态码：成功为 `200`，失败为 `501`。可选值：`200` / `501`。示例：`200`。
`msg`	`string`	是	统一回调消息。可选值：`Playground task completed successfully.` / `Playground task failed.`。示例：`Playground task completed successfully.`。
`data`	`object`	是	任务结果。成功时 `resultJson` 包含 `resultUrls`；失败时返回 `failCode`、`failMsg`，不含 `resultJson`。
`data.completeTime`	`integer`	否	任务完成时间戳（毫秒）。完成时间请以该字段为准。
`data.costTime`	`integer`	否	处理耗时（秒）。成功和失败回调都会返回。
`data.createTime`	`integer`	否	任务创建时间戳（毫秒）。
`data.creditsConsumed`	`number`	否	本任务消耗的积分。失败任务为 `0`。
`data.model`	`string`	是	任务使用的模型。可选值：`kling-4.0/keyframe-to-video`。示例：`kling-4.0/keyframe-to-video`。
`data.param`	`string`	是	已提交任务的 JSON 字符串，包含 `model`、`callBackUrl` 和 `input`。`input` 对应该接口参数（`prompt`、`duration`、`resolution`、`aspect_ratio`、`first_frame_url`、`keyframe_urls`、`last_frame_url`）。
`data.resultJson`	`string`	否	生成结果的 JSON 字符串。仅在 `state` 为 `success` 时出现。该模型里包含 `resultUrls`，即 `.mp4` 地址数组。
`data.state`	`string`	是	任务最终状态。可选值：`success` / `fail`。示例：`success`。
`data.taskId`	`string`	是	任务唯一标识符，与创建任务接口返回的 `data.taskId` 一致。
`data.updateTime`	`integer`	否	任务更新时间戳（毫秒）。可能与 `createTime` 相同；完成时间请以 `completeTime` 为准。
`data.failCode`	`string`	否	失败码，数字字符串，如 `"400"`、`"500"`。仅在 `state` 为 `fail` 时出现。
`data.failMsg`	`string`	否	失败原因，仅在 `state` 为 `fail` 时出现。该模型可能是总帧数超过 `duration` 上限（`duration 5s allows at most 6 frames (first + keyframes + last), got 7`）、未传 `first_frame_url`、prompt 引用了未提供的 `@first_frame` / `@keyframe_N` / `@last_frame`，或图片拉取/审核/尺寸相关的上游原文。

任务成功完成

json

{
  "code": 200,
  "data": {
    "completeTime": 1792670085074,
    "costTime": 718,
    "createTime": 1792669367000,
    "creditsConsumed": 285,
    "model": "kling-4.0/keyframe-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"keyframe_urls\\\":[],\\\"prompt\\\":\\\"女孩出门\\\",\\\"resolution\\\":\\\"720p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/keyframe-to-video\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/k/ce115adfa78260a99009eebddac1d187_1_1792670083_1582.mp4\"]}",
    "state": "success",
    "taskId": "ce115adfa78260a99009eebddac1d187",
    "updateTime": 1792669367000
  },
  "msg": "Playground task completed successfully."
}

任务失败

json

{
  "code": 501,
  "data": {
    "completeTime": 1792670085074,
    "costTime": 718,
    "createTime": 1792669367000,
    "creditsConsumed": 0,
    "failCode": "400",
    "failMsg": "duration 5s allows at most 6 frames (first + keyframes + last), got 7",
    "model": "kling-4.0/keyframe-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":5,\\\"first_frame_url\\\":\\\"https://example.com/first.png\\\",\\\"keyframe_urls\\\":[\\\"https://example.com/k1.png\\\",\\\"https://example.com/k2.png\\\",\\\"https://example.com/k3.png\\\",\\\"https://example.com/k4.png\\\",\\\"https://example.com/k5.png\\\"],\\\"last_frame_url\\\":\\\"https://example.com/last.png\\\",\\\"prompt\\\":\\\"女孩出门\\\",\\\"resolution\\\":\\\"720p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/keyframe-to-video\"}",
    "state": "fail",
    "taskId": "ce115adfa78260a99009eebddac1d187",
    "updateTime": 1792669367000
  },
  "msg": "Playground task failed."
}

Kling 4.0 关键帧生成视频 ​

接口 ​

查询任务状态 ​

相关资源 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — 请求成功 ​

回调 ​

videoTaskCompleted ​

Kling 4.0 关键帧生成视频

接口

查询任务状态

相关资源

请求参数

请求体 (application/json)

请求示例

响应

200 — 请求成功

回调

videoTaskCompleted