ModelFold Docs

简体中文

English

简体中文

English

Appearance

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，根据参考图、参考视频、主体和声音生成视频。在提示词中用 @image_1、@video_1 或自定义 @名称 引用素材。

素材与引用 ​

四类素材均可不传，全部为空时等同于纯文生视频。传入后在 prompt 中按下表引用：

素材引用写法数量上限
参考图 images@image_1、@image_2…10 张
参考视频 videos@video_1、@video_2…5 个，单个 2–30 秒
主体 elements@主体名7 个，其中视频主体最多 3 个
声音 voices@声音名3 个
  • 参考视频与视频主体合计最多 5 个，四类素材合计最多 15 个。
  • 图片主体需 2–4 张图，第 1 张为主图；视频主体需 1 段 3–8 秒的单镜头人物视频。
  • 自定义名称为 1–20 位中文、字母、数字或下划线，忽略大小写后不可重复，且不能占用 image_N、video_N、first_frame、last_frame 等保留名。
  • 引用了未声明的素材会直接返回参数错误，任务不会创建。

TIP

未指定 aspect_ratio 时，有任意参考素材则按素材自适应，无素材则使用 16:9。传入 videos 时由 keep_original_sound 决定是否保留原声，未传 videos 时原生音频默认开启。

查询任务状态 ​

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

TIP

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

相关资源 ​

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 该接口必须使用 kling-4.0/reference-to-video 模型 默认值："kling-4.0/reference-to-video"。 可选值：kling-4.0/reference-to-video。 示例：kling-4.0/reference-to-video。
callBackUrlstring否接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。
- 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果
- 回调内容包含生成内容的 URL 及任务相关信息
- 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体
- 也可选择调用任务详情接口，主动轮询任务状态
- 为确保回调安全性，请参阅 Webhook 校验指南 了解签名验证实现方法 示例：https://your-domain.com/api/callback。
inputobject是生成任务的输入参数。
  input.promptstring是视频描述，必填，最多 8000个字符。
用 @ 引用本次请求里已上传的素材：
- @image_1、@image_2… 按顺序对应 image_urls（从 1 开始）
- @video_1、@video_2… 对应 video_urls
- @名称 对应 elements 或 voices 中的 name
每个 @ 引用都必须能匹配到本次请求已传入的素材，否则请求会被拒绝。引用按已声明名称做最长匹配；若匹配到的名称以字母、数字或下划线结尾，紧跟的下一个字符不能再是字母、数字或下划线。 示例：@Hero 坐在 @video_1 的桌前，拿起 @image_1 里的玩偶，用 @Narrator 的声音打招呼。
  input.durationinteger否输出视频时长（秒），3–30 的整数，默认 5。 默认值：5。 示例：5。
  input.resolutionstring否输出分辨率：720p 或 1080p，默认 720p。 默认值："720p"。 可选值：720p / 1080p。 示例：720p。
  input.aspect_ratiostring否输出画面比例，可选。
- 不传且提供了任意参考素材时，使用 auto
- 不传且没有任何参考素材时，使用 16:9 可选值：auto / 16:9 / 9:16 / 1:1 / 21:9。 示例：auto。
  input.image_urlsarray&lt;string&gt;否参考图，最多 10 张，需公网可访问。提示词里按数组顺序用 @image_1、@image_2… 引用。每边 300–65536 像素，宽高比 0.4–2.5。 默认值：[]。
  input.video_urlsarray&lt;string&gt;否参考视频，最多 5 个，每个 2–30 秒。提示词里用 @video_1、@video_2… 引用。参考视频与 elements 中的视频主体合计不超过 5 个。 默认值：[]。
  input.keep_original_soundboolean否是否保留参考视频的原声。只在传了 video_urls 时生效，默认 false。不传参考视频时固定生成原生音频。 默认值：false。 示例：false。
  input.elementsarray&lt;object&gt;否仅本次任务使用的主体，最多 7 个，其中视频主体最多 3 个。提示词里用 @名称 引用。image_urls、video_urls、elements、voices 四类按条数合计不超过 15。 默认值：[]。
    input.elements[].namestring是提示词里 @名称 引用用的名字。1–20 个字符，仅限中文、字母、数字、下划线。与 elements、voices 中的其它名称不能重复（不区分大小写）。不能使用保留名（不区分大小写，N 为数字）：image_N、video_N、keyframe_N、object_N、audio_N、first_frame、last_frame。 示例：Hero。
    input.elements[].image_urlsarray&lt;string&gt;否图片主体用的 2–4 张公网可访问图片，不能与 video_url 同时传。第 1 张是主图（正脸或主视角），其余是副图。
    input.elements[].video_urlstring否视频主体用的人物视频地址，不能与 image_urls 同时传。1 个视频，3–8 秒，单镜头连续画面（不能有剪切），最短边不小于 700 像素。
    input.elements[].tagstring否主体分类。图片主体可选，不传时按主图自动识别；视频主体固定为 character，传其它值会被拒绝。 可选值：character / animal / prop / costume / scene / effect / others。 示例：character。
    input.elements[].descriptionstring否可选的主体描述，最多 100 个字符。
    input.elements[].voice_urlstring否可选，绑定在该主体上的参考音频。不能单独用 @ 引用，也不占 voices 名额。只有人物主体能绑定：图片主体的 tag 须为 character 或不传；视频主体不传时，若视频里有人声则自动使用。
  input.voicesarray&lt;object&gt;否仅本次任务使用的独立声音参考，最多 3 个。提示词里用 @名称 引用。主体上通过 voice_url 绑定的声音与此无关，不占名额。 默认值：[]。
    input.voices[].namestring是提示词里 @名称 引用用的名字。1–20 个字符，仅限中文、字母、数字、下划线。与 elements、voices 中的其它名称不能重复（不区分大小写）。不能使用保留名（不区分大小写，N 为数字）：image_N、video_N、keyframe_N、object_N、audio_N、first_frame、last_frame。 示例：Narrator。
    input.voices[].audio_urlstring是公网可访问的参考音频地址，必填。识别不到可用声音时任务失败。

请求示例 ​

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/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "@Hero 坐在 @video_1 的桌前，拿起 @image_1 里的玩偶，用 @Narrator 的声音打招呼",
    "duration": 10,
    "resolution": "1080p",
    "image_urls": [
      "https://example.com/doll.png"
    ],
    "video_urls": [
      "https://example.com/room.mp4"
    ],
    "keep_original_sound": false,
    "elements": [
      {
        "name": "Hero",
        "image_urls": [
          "https://example.com/hero-front.jpg",
          "https://example.com/hero-side.jpg"
        ],
        "tag": "character",
        "description": "穿红夹克的年轻男人"
      }
    ],
    "voices": [
      {
        "name": "Narrator",
        "audio_url": "https://example.com/narrator.mp3"
      }
    ]
  }
}'
json
{
  "model": "kling-4.0/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "@Hero 坐在 @video_1 的桌前，拿起 @image_1 里的玩偶，用 @Narrator 的声音打招呼",
    "duration": 10,
    "resolution": "1080p",
    "image_urls": [
      "https://example.com/doll.png"
    ],
    "video_urls": [
      "https://example.com/room.mp4"
    ],
    "keep_original_sound": false,
    "elements": [
      {
        "name": "Hero",
        "image_urls": [
          "https://example.com/hero-front.jpg",
          "https://example.com/hero-side.jpg"
        ],
        "tag": "character",
        "description": "穿红夹克的年轻男人"
      }
    ],
    "voices": [
      {
        "name": "Narrator",
        "audio_url": "https://example.com/narrator.mp3"
      }
    ]
  }
}

响应 ​

200 — 请求成功 ​

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

回调 ​

videoTaskCompleted ​

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

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

回调体参数

参数类型必填说明
codeinteger是统一回调状态码：成功为 200，失败为 501。 可选值：200 / 501。 示例：200。
msgstring是统一回调消息。 可选值：Playground task completed successfully. / Playground task failed.。 示例：Playground task completed successfully.。
dataobject是任务结果。成功时 resultJson 包含 resultUrls；失败时返回 failCode、failMsg，不含 resultJson。
  data.completeTimeinteger否任务完成时间戳（毫秒）。完成时间请以该字段为准。
  data.costTimeinteger否处理耗时（秒）。成功和失败回调都会返回。
  data.createTimeinteger否任务创建时间戳（毫秒）。
  data.creditsConsumednumber否本任务消耗的积分。失败任务为 0。
  data.modelstring是任务使用的模型。 可选值：kling-4.0/reference-to-video。 示例：kling-4.0/reference-to-video。
  data.paramstring是已提交任务的 JSON 字符串，包含 model、callBackUrl 和 input。input 对应该接口参数（prompt、duration、resolution、aspect_ratio、image_urls、video_urls、keep_original_sound、elements、voices）。
  data.resultJsonstring否生成结果的 JSON 字符串。仅在 state 为 success 时出现。该模型里包含 resultUrls，即 .mp4 地址数组。
  data.statestring是任务最终状态。 可选值：success / fail。 示例：success。
  data.taskIdstring是任务唯一标识符，与创建任务接口返回的 data.taskId 一致。
  data.updateTimeinteger否任务更新时间戳（毫秒）。可能与 createTime 相同；完成时间请以 completeTime 为准。
  data.failCodestring否失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。
  data.failMsgstring否失败原因，仅在 state 为 fail 时出现。该模型可能是参考视频时长错误（video_1 duration must be between 2 and 30 seconds, got 45）、主体/声音创建失败，或上游原文。

任务成功完成

json
{
  "code": 200,
  "data": {
    "completeTime": 1792669219001,
    "costTime": 315,
    "createTime": 1792668903000,
    "creditsConsumed": 425,
    "model": "kling-4.0/reference-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"aspect_ratio\\\":\\\"9:16\\\",\\\"keep_original_sound\\\":false,\\\"elements\\\":[],\\\"voices\\\":[],\\\"image_urls\\\":[],\\\"video_urls\\\":[],\\\"prompt\\\":\\\"sits at the desk in\\\",\\\"resolution\\\":\\\"1080p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/reference-to-video\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/k/1f0176644624b187c7f6add97986875d_1_1792669217_8488.mp4\"]}",
    "state": "success",
    "taskId": "1f0176644624b187c7f6add97986875d",
    "updateTime": 1792668903000
  },
  "msg": "Playground task completed successfully."
}

任务失败

json
{
  "code": 501,
  "data": {
    "completeTime": 1792669219001,
    "costTime": 315,
    "createTime": 1792668903000,
    "creditsConsumed": 0,
    "failCode": "400",
    "failMsg": "video_1 duration must be between 2 and 30 seconds, got 45",
    "model": "kling-4.0/reference-to-video",
    "param": "{\"input\":\"{\\\"duration\\\":10,\\\"aspect_ratio\\\":\\\"9:16\\\",\\\"keep_original_sound\\\":false,\\\"elements\\\":[],\\\"voices\\\":[],\\\"image_urls\\\":[],\\\"video_urls\\\":[\\\"https://example.com/room.mp4\\\"],\\\"prompt\\\":\\\"sits at the desk in @video_1\\\",\\\"resolution\\\":\\\"1080p\\\"}\",\"callBackUrl\":\"https://webhook.uutool.cn/bfa7de80-8dd8-4844-9e34-4032ddbbf3c1\",\"model\":\"kling-4.0/reference-to-video\"}",
    "state": "fail",
    "taskId": "1f0176644624b187c7f6add97986875d",
    "updateTime": 1792668903000
  },
  "msg": "Playground task failed."
}

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold