Kling-v3-omni 传入参考视频

魔芋平台调用 kling-v3-omni 时如何正确传入「参考视频」。

核心结论

参考视频必须放进 metadata，字段名用 videos（数组），且必须关闭音频（generateAudio: false）。

❌ 放在请求顶层的 video / videos 会被 TaskSubmitReq 反序列化静默丢弃——任务能提交成功，但上游收到的是纯文生视频，参考视频不生效。

❌ metadata.video（单数）上游会忽略，参考视频同样不生效。

❌ 带参考视频却开着音频，上游直接报错：
AudioGeneration Enabled is not supported when video reference is provided for model Kling 3.0-Omni

✅ metadata.videos（数组）+ generateAudio: false：实测参考视频真正生效。

原理见：

TaskSubmitReq 无 video/videos 顶层字段 → relay/common/relay_info.go:645

custom 适配器把 metadata.* 整体展开进上游请求体 → relay/channel/task/custom/adaptor.go:235-239

kling-v3 字段白名单保留 videos → relay/channel/task/custom/adaptor.go:291-298

接口地址

用途	方法	地址
提交任务	POST	`https://www.moyu.info/v1/video/generations`
查询结果	GET	`https://www.moyu.info/v1/videos/{task_id}`

提交任务

请求：

响应：

{
  "id": "1426424353-AigcVideoTask-af806fe15e7290261135f670b70f9eb9t",
  "task_id": "1426424353-AigcVideoTask-af806fe15e7290261135f670b70f9eb9t",
  "object": "video",
  "model": "kling-v3-omni",
  "status": "PENDING",
  "progress": 0,
  "created_at": 0
}

查询结果

用返回的 task_id 轮询（建议每 3-5 秒一次，整体耗时约 2-4 分钟）：

处理中：

{
  "id": "1426424353-AigcVideoTask-af806fe15e7290261135f670b70f9eb9t",
  "object": "video",
  "model": "",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1785979449
}

成功（视频地址在 metadata.url）：

{
  "id": "1426424353-AigcVideoTask-af806fe15e7290261135f670b70f9eb9t",
  "object": "video",
  "model": "",
  "status": "completed",
  "progress": 100,
  "created_at": 1785979449,
  "completed_at": 1785979685,
  "metadata": {
    "url": "http://store.vod-qcloud.com/1a168d62vodcq251000800/22fa3fa35001834814737318717/aigcVideoGenFile.mp4"
  }
}

状态流转：PENDING → in_progress → completed。生成视频 URL 取 metadata.url。

参数说明

参数	位置	类型	说明
model	顶层	string	固定 `kling-v3-omni`（参考视频仅该模型支持）
prompt	顶层	string	提示词
metadata.videos	metadata	array	参考视频数组，每项 `{"url": "..."}`
metadata.generateAudio	metadata	bool	传参考视频时必须为 `false`

图生视频（传入参考图片）

kling-v3-omni 传入参考图片（Image to Video / Motion Control）。与参考视频不同，图片顶层 images 字段有代码专门支持，推荐直接放顶层。

核心结论

图片有两条可用路径，均实测成功：

✅ 推荐：顶层 images 传字符串数组（["https://..."]）。custom 适配器会自动转成上游要求的对象数组格式。

✅ 备选：metadata.images 传对象数组（[{"url": "..."}]），走 metadata 展开。

顶层字符串数组更简洁，且是代码显式支持的路径（参考视频没有顶层字段所以只能走 metadata，图片不同）。

原理：custom 适配器把顶层 images 字符串数组经 convertImagesToKlingV3Format 转成 [{"url":"..."}] → relay/channel/task/custom/adaptor.go:191-202。

提交任务（推荐：顶层 images 字符串数组）

请求：

响应：

{
  "id": "1426424353-AigcVideoTask-a469431797dd2698015ab5d05dab1c19t",
  "task_id": "1426424353-AigcVideoTask-a469431797dd2698015ab5d05dab1c19t",
  "object": "video",
  "model": "kling-v3-omni",
  "status": "PENDING",
  "progress": 0,
  "created_at": 0
}

成功查询响应（视频地址在 metadata.url）：

{
  "id": "1426424353-AigcVideoTask-a469431797dd2698015ab5d05dab1c19t",
  "object": "video",
  "model": "",
  "status": "completed",
  "progress": 100,
  "created_at": 1785980306,
  "completed_at": 1785980427,
  "metadata": {
    "url": "http://store.vod-qcloud.com/1a168d62vodcq251000800/f5d55dd15001834814734270512/aigcVideoGenFile.mp4"
  }
}

备选：metadata.images 对象数组

图片参数说明

上游 images 为 []object，单图用于图生视频 / 运动控制，多图用于 Multi-Image to Video。支持格式：jpg、jpeg、png。

参数	位置	类型	说明
images	顶层	array<string>	推荐。图片 URL 字符串数组，适配器自动转对象数组
metadata.images	metadata	array<object>	备选。每项 `{"url": "..."}` 或 `{"b64_json": "...", "mime_type": "image/png"}`

Base64 图片：b64_json 为纯 base64（不带 data: 前缀），需同时提供 mime_type。

kling-v3-传入参考视频

Kling-v3-omni 传入参考视频#

核心结论#

接口地址#

提交任务#

查询结果#

参数说明#

图生视频（传入参考图片）#

核心结论#

提交任务（推荐：顶层 images 字符串数组）#

备选：metadata.images 对象数组#

图片参数说明#

Kling-v3-omni 传入参考视频

核心结论

接口地址

提交任务

查询结果

参数说明

图生视频（传入参考图片）

核心结论

提交任务（推荐：顶层 images 字符串数组）

备选：metadata.images 对象数组

图片参数说明