Kling 3.0 Omni Reference-To-Video

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

接口

POST /jobs/createTask

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

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

查询任务状态

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

Get Task Details — 了解如何查询任务状态及获取生成结果

TIP

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

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0-omni/reference-to-video` 模型默认值：`"kling-3.0-omni/reference-to-video"`。可选值：`kling-3.0-omni/reference-to-video`。示例：`kling-3.0-omni/reference-to-video`。
`callBackUrl`	`string`	否	接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 Webhook 校验指南了解签名验证实现方法示例：`https://your-domain.com/api/callback`。
`input`	`object	object	object`

请求示例

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-omni/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "参考图片中的角色外观，生成角色在城市街道行走的视频。",
    "image_urls": [
      "https://example.com/character-reference.png"
    ],
    "customize_multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "A wide shot of the character walking through the city.",
        "duration": 2
      },
      {
        "prompt": "A close-up of the character looking toward the camera.",
        "duration": 3
      }
    ],
    "audio": true,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "elements": []
  }
}'

json

{
  "model": "kling-3.0-omni/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "参考图片中的角色外观，生成角色在城市街道行走的视频。",
    "image_urls": [
      "https://example.com/character-reference.png"
    ],
    "customize_multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "A wide shot of the character walking through the city.",
        "duration": 2
      },
      {
        "prompt": "A close-up of the character looking toward the camera.",
        "duration": 3
      }
    ],
    "audio": true,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "elements": []
  }
}

响应

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-2.6_1765182425861"
  }
}

回调

referenceToVideoTaskCompleted

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

当 kling-3.0-omni/reference-to-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-omni/reference-to-video`。示例：`kling-3.0-omni/reference-to-video`。
`data.state`	`string`	是	任务最终状态。可选值：`success` / `fail`。示例：`success`。
`data.param`	`string`	是	包含已提交任务参数的 JSON 字符串。
`data.resultJson`	`string`	否	任务成功时包含生成视频地址等结果信息的 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_reference_to_video_001",
    "model": "kling-3.0-omni/reference-to-video",
    "state": "success",
    "param": "{\"model\":\"kling-3.0-omni/reference-to-video\",\"callBackUrl\":\"https://example.com/callback\",\"input\":{\"prompt\":\"参考图片中的角色生成视频。\",\"image_urls\":[\"https://example.com/reference-image.jpg\"],\"video_urls\":[],\"multi_shot\":false,\"audio\":false,\"resolution\":\"720p\",\"aspect_ratio\":\"16:9\",\"duration\":5,\"elements\":[]}}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-reference-video.mp4\"]}",
    "costTime": 14000,
    "completeTime": 1786694400000,
    "createTime": 1786694386000,
    "updateTime": 1786694400000,
    "creditsConsumed": 1.45
  }
}

参考素材生成视频任务失败

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_reference_to_video_001",
    "model": "kling-3.0-omni/reference-to-video",
    "state": "fail",
    "param": "{\"model\":\"kling-3.0-omni/reference-to-video\",\"input\":{\"prompt\":\"参考图片中的角色生成视频。\",\"image_urls\":[\"https://example.com/reference-image.jpg\"],\"video_urls\":[]}}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 14000,
    "creditsConsumed": 0
  }
}

Kling 3.0 Omni Reference-To-Video ​

接口 ​

查询任务状态 ​

相关资源 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — 请求成功 ​

回调 ​

referenceToVideoTaskCompleted ​

Kling 3.0 Omni Reference-To-Video

接口

查询任务状态

相关资源

请求参数

请求体 (application/json)

请求示例

响应

200 — 请求成功

回调

referenceToVideoTaskCompleted