跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Kling 3.0 Omni Reference-to-Video API

POST Base URL: https://api.hiapi.ai /v1/tasks

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 kling-3.0-omni/reference-to-video
类型 视频生成（参考生视频）
接口 POST /v1/tasks
价格 见 HiAPI 定价

Kling 3.0 Omni（可灵 O3）参考生视频：以 1–7 张参考图和可选 1 段参考视频生成 3–15 秒、720p 至 4k 的视频，保留参考素材的主体、风格与运动，支持 16:9 / 9:16 / 1:1 画幅、原生音频、智能分镜与 @名称 主体素材。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

主体与风格参考

用参考图片保持主体、产品或美术风格的一致性，再用提示词描述新场景。

image_urlsprompt
运镜与动作参考

加一段参考视频，让新视频沿用它的运动节奏与镜头方式。

video_urls
多主体同框

用 elements 为多个角色分别命名，在提示词中以 @名称 安排各自的动作。

elements
带音频的多镜头短片

不传参考视频时可开启 audio 与 prefer_multi_shots，一次生成带声音的多镜头内容。

audioprefer_multi_shots

请求参数

model string 必填

固定填 kling-3.0-omni/reference-to-video。

示例 kling-3.0-omni/reference-to-video
input object 必填

业务参数对象；可灵 Kling 3.0 Omni 参考生视频的模型专属配置都放在这里。

prompt string 必填

描述想要的画面内容、主体动作与镜头运动；需要用到 elements 里的主体时，在提示词中以 @名称 引用。长度 1–3072 字符。

image_urls string[] 必填

参考图片，1–7 张；传入参考视频时最多 4 张。参考图与 elements 主体合计不超过 7 组（带参考视频时不超过 4 组）。JPG/PNG，单张不超过 50MB，最短边不小于 300px。

video_urls string[] 可选

可选参考视频，仅 1 段，为生成提供运动与运镜参考。MP4/MOV，不超过 200MB，时长 3–15.5 秒，宽高均在 700–4553px，帧率 24–60fps。传入后 audio 必须为 false、prefer_multi_shots 不可开启，且参考图最多 4 张。

示例 ["https://static.hiapi.ai/admin-assets/2026/10/13/1791861859228-2b40d774dd4b2262-kling-omni-t2v-golden.mp4"]
duration integer 可选

视频时长，单位为秒，取 3–15 之间的整数。

默认 5
resolution enum 可选

输出视频分辨率。

默认 720p 可选值: 720p1080p4k
audio boolean 可选

是否生成与画面同步的原生音频（环境声、音效）。传入参考视频时必须为 false。

默认 false 示例 true
aspect_ratio enum 可选

输出视频的画面比例。

默认 16:9 可选值: 16:99:161:1
prefer_multi_shots boolean 可选

是否开启智能分镜：开启后模型根据提示词自动规划多个镜头并切换。传入参考视频时不可开启。

默认 false 示例 true
elements object[] 可选

主体素材，最多 7 组。每组给出名称、简短描述和 2–4 张同一主体的图片，在提示词中用 @名称 引用，让角色或物品在整段视频中保持一致。与参考图合计不超过 7 组（带参考视频时不超过 4 组）。

示例 [{"name":"lin","description":"扎马尾、穿浅黄色连衣裙的小女孩","element_input_urls":["https://example.com/lin-front.jpg","https://example.com/lin-side.jpg"]}]
name string 必填

主体的唯一名称，不含空格；提示词中以 @名称 引用。

description string 必填

主体的简短描述。

element_input_urls string[] 必填

同一主体的 2–4 张图片 URL，JPG/PNG。

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

参考图 + 参考视频

一张参考图保持纸船外观，一段参考视频提供跟拍运镜；带参考视频时 audio 为 false。3 秒、720p、16:9。

请求体
{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "The same white paper boat from the reference drifts along a sunlit forest stream at golden hour, leaves floating beside it, camera tracks low alongside it with the same smooth motion as the reference video. Cinematic, shallow depth of field.",
    "image_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg"
    ],
    "video_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861859228-2b40d774dd4b2262-kling-omni-t2v-golden.mp4"
    ],
    "duration": 3,
    "resolution": "720p",
    "audio": false,
    "aspect_ratio": "16:9"
  }
}
多张参考图 + 1080p 音频

只传参考图片（不带参考视频），可开启原生音频。请把示例 URL 替换为可公开访问的参考图。

请求体
{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "参考图中的白色纸船漂在黄昏的城市雨水沟里，霓虹灯在水面倒映晃动，雨滴在船边溅起水花，镜头低角度平稳跟拍。电影感，浅景深，雨声与远处车流的环境声。",
    "image_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg",
      "https://example.com/neon-street-reference.jpg"
    ],
    "duration": 6,
    "resolution": "1080p",
    "audio": true,
    "aspect_ratio": "9:16"
  }
}
参考图 + 主体素材 + 智能分镜

参考图确定场景风格，elements 传入角色的 3 张图片并以 @lin 引用，开启智能分镜生成 10 秒多镜头短片（不带参考视频）。请把示例 URL 替换为可公开访问的图片。

请求体
{
  "model": "kling-3.0-omni/reference-to-video",
  "input": {
    "prompt": "@lin 蹲在溪边把白色纸船放进水里，纸船顺流漂走，她起身沿着溪岸慢慢跟着走；多个镜头：放船特写、起身中景、溪岸全景。金色黄昏光，电影感。",
    "image_urls": [
      "https://static.hiapi.ai/admin-assets/2026/10/13/1791861888668-6554d6167af93003-kling-omni-boat-frame.jpg"
    ],
    "elements": [
      {
        "name": "lin",
        "description": "扎马尾、穿浅黄色连衣裙的小女孩",
        "element_input_urls": [
          "https://example.com/lin-front.jpg",
          "https://example.com/lin-side.jpg",
          "https://example.com/lin-back.jpg"
        ]
      }
    ],
    "duration": 10,
    "resolution": "1080p",
    "audio": false,
    "aspect_ratio": "16:9",
    "prefer_multi_shots": true
  }
}

获取结果

  1. 提交成功后立即返回 taskId（不等待生成完成）。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output[].url 下载生成的视频。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

参考图和参考视频分别起什么作用?

参考图提供主体外观、构图与风格；参考视频提供运动节奏与运镜方式。参考视频是可选的，参考图至少 1 张。

带参考视频时为什么不能开音频和智能分镜?

参考视频模式下 audio 必须为 false、prefer_multi_shots 不可开启，参考图也最多 4 张；需要原生音频或多镜头时，请只传参考图。

参考图和 elements 主体加起来有上限吗?

有。不带参考视频时合计不超过 7 组，带参考视频时合计不超过 4 组。

输出画幅由什么决定?

由 aspect_ratio 决定，可选 16:9、9:16、1:1，默认 16:9。

如何计费?

以 HiAPI 定价页的实时价格为准。 查看价格

下一步