🎬 Kling-v3 系列视频接口

Kling-v3 和 Kling-v3-omni 视频生成接口文档。

接口地址

提交任务

POST https://www.moyu.info/v1/video/generations

查询结果

GET https://www.moyu.info/v1/videos/{task_id}

获取视频内容

GET https://www.moyu.info/v1/videos/{task_id}/content

模型说明

可用模型

kling-v3：Kling 第三代视频生成模型，支持文生视频、图生视频

kling-v3-omni：Kling 第三代多模态模型，支持文生视频、图生视频、视频参考（运动控制）

模式选择

Kling-v3 系列支持三种生成模式，通过 mode 参数指定：

模式	说明	适用场景
std	标准模式	成本较低，生成速度快，适合快速预览和批量生成
pro	专业模式（默认）	质量更高，细节更丰富，适合正式作品
4k	4K 超清模式	最高画质，适合高端制作需求

请求示例

1. 文生视频 (Text-to-Video)

基础示例

带完整参数的示例

2. 图生视频 (Image-to-Video)

使用公网 URL

使用 Base64 编码图片

重要提示：

图片以字符串形式放入 images 数组，支持两种写法：公网 URL（https://...），或带前缀的 Base64 Data URI（如 data:image/png;base64,xxx）

使用 Base64 时请保留 data:image/png;base64, 前缀，平台会自动解析出图片类型；前缀里的 image/png 即图片格式，无需单独传 mime_type

3. 视频参考 / 运动控制（仅 kling-v3-omni）

Kling-v3-omni 支持使用参考视频来控制生成视频的运动方式。

单个参考视频

多个参考视频

请求参数详解

核心参数

参数	类型	必填	说明
model	string	是	模型名称：`kling-v3` 或 `kling-v3-omni`
prompt	string	是	描述提示词，详细描述想要生成的视频内容
mode	string	否	生成模式：`std`（标准）、`pro`（专业，默认）、`4k`（超清）
duration	integer	否	视频时长（秒），支持 3 到 15，默认为 5
aspect_ratio	string	是	视频宽高比：`16:9`（横屏）、`9:16`（竖屏）、`1:1`（方形），只有在进行“视频编辑”或“提供了首帧图片”的情况下，才可以省略该参数，模型会自动采用输入素材的比例
generateAudio	boolean	否	是否生成带音频的视频，默认 `false`

图生视频参数

参数	类型	必填	说明
images	array	图生视频时必填	输入图片数组，每个元素为字符串：公网 URL 或带前缀的 Base64 Data URI（如 `data:image/png;base64,xxx`）

视频参考参数（仅 kling-v3-omni）

以下参数需放入顶层 metadata 对象中传入，键名保持驼峰写法。

参数	类型	必填	说明
metadata.video	object	运动控制时可选	单个参考视频对象，含 `url` 字段
metadata.videos	array	运动控制时可选	多个参考视频数组，每个元素含 `url` 字段

高级参数

以下参数需放入顶层 metadata 对象中传入，键名保持驼峰写法。

参数	类型	必填	说明
metadata.negativePrompt	string	否	负面提示词，描述不希望出现的内容
metadata.cfgScale	number	否	CFG Scale（提示词相关性），范围 0.1-1.0，默认 0.6
metadata.firstFrame	object	否	首帧图片对象
metadata.lastFrame	object	否	尾帧图片对象
metadata.callbackUrl	string	否	任务完成后的回调 URL

提交任务响应格式

成功响应

{
  "id": "848244325094924334",
  "task_id": "848244325094924334",
  "object": "video",
  "model": "kling-v3",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1770265725
}

响应字段说明

字段	类型	说明
id	string	任务唯一标识符
task_id	string	任务 ID，用于查询生成结果
object	string	对象类型，固定为 `video`
model	string	使用的模型名称
status	string	任务状态：`PENDING`（待处理）
progress	integer	进度百分比（0-100）
created_at	integer	创建时间戳（Unix 时间）

重要：Kling-v3 为异步接口，提交后返回 task_id，需要使用该 ID 轮询查询生成结果。

查询任务结果

使用返回的 task_id 查询视频生成进度和结果。

查询请求

查询响应示例

任务排队中

{
  "id": "848244325094924334",
  "object": "video",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0,
  "created_at": 1770265725
}

任务处理中

{
  "id": "848244325094924334",
  "object": "video",
  "model": "kling-v3",
  "status": "processing",
  "progress": 45,
  "created_at": 1770265725
}

任务成功

{
  "id": "848244325094924334",
  "object": "video",
  "model": "kling-v3",
  "status": "succeeded",
  "progress": 100,
  "video_url": "https://example.com/output_video.mp4",
  "created_at": 1770265725,
  "completed_at": 1770265850
}

任务失败

{
  "id": "848244325094924334",
  "object": "video",
  "model": "kling-v3",
  "status": "failed",
  "progress": 0,
  "error": {
    "code": "invalid_parameters",
    "message": "Invalid aspect ratio parameter"
  },
  "created_at": 1770265725,
  "completed_at": 1770265780
}

状态码说明

状态	说明
`queued`	任务已进入队列，等待处理
`processing`	任务正在生成中
`succeeded`	任务已成功完成
`failed`	任务失败
`cancelled`	任务已取消

获取视频内容

当任务状态为 succeeded 时，可以通过以下方式下载视频文件。

方式一：直接使用 video_url

从查询结果中获取 video_url 字段，直接下载：

方式二：使用内容接口

差异化计费说明

Kling-v3 系列采用多维度差异化计费，计费维度包括：

计费维度

模式（mode）

std：标准模式价格

pro：专业模式价格（默认）

4k：4K 模式价格

任务类型（type）

文生视频（t2v）：仅使用 prompt

图生视频（i2v）：使用 prompt + images

运动控制（motion）：使用 prompt + video/videos（仅 kling-v3-omni）

音频（audio）

无音频：generateAudio: false 或未指定

有音频：generateAudio: true

计费示例

假设平台定价为（¥/秒）：

模式	类型	无音频	有音频
std	t2v	0.39	0.80
std	i2v	0.39	0.80
pro	t2v	0.80	1.00
pro	i2v	0.80	1.00
4k	-	1.20	3.00

计费公式：

总费用 = 单价（¥/秒）× 视频时长（秒）

示例：

生成一个 10 秒的 pro 模式文生视频（无音频）：0.80 × 10 = 8.00 元

生成一个 5 秒的 4k 模式图生视频（有音频）：3.00 × 5 = 15.00 元

最佳实践

提示词建议

详细描述：包含场景、主体、动作、光线、情绪等元素

好：夕阳下的海滩，金色的阳光洒在沙滩上，海浪轻轻拍打着岸边，几只海鸥在天空中自由飞翔
差：海滩

使用负面提示词：明确不希望出现的内容（放入 metadata）

{
  "metadata": {
    "negativePrompt": "模糊、低质量、扭曲、水印、文字、失真"
  }
}

中英文均可：系统同时支持中文和英文提示词

图片要求

格式：支持 JPEG、PNG、WebP

分辨率：建议 512x512 以上，不超过 4096x4096

传入方式：images 数组的每个元素为字符串

公网 URL：直接填 https://... 地址

Base64：填带前缀的 Data URI（如 data:image/png;base64,xxx），平台会自动解析图片类型

性能优化

异步轮询：提交任务后，建议每 3-5 秒轮询一次状态

超时处理：建议设置 60 分钟超时，长视频生成可能需要较长时间

错误重试：遇到网络错误时，可以重试；遇到参数错误时，请修改参数后重试

常见错误

错误码说明

错误码	说明	解决方案
`invalid_parameters`	参数错误	检查请求参数是否符合要求
`invalid_aspect_ratio`	宽高比无效	使用 `16:9`、`9:16` 或 `1:1`
`invalid_duration`	时长无效	使用 5 或 10 秒
`invalid_image_format`	图片格式错误	检查图片 URL 或 Base64 编码
`insufficient_quota`	配额不足	充值或联系管理员
`task_cancelled`	任务已取消	用户主动取消
`generation_failed`	生成失败	可能是提示词问题，尝试修改后重试

常见问题

Q1：为什么图生视频时提示 "invalid_image_format"？

A：请检查：

如果使用 URL，确保是公网可访问的 HTTPS 地址

如果使用 Base64，确保填的是带前缀的 Data URI（如 data:image/png;base64,xxx）

images 数组元素必须是字符串，不要传对象

Q2：为什么任务一直是 "queued" 状态？

A：高峰期可能需要排队，通常会在几分钟内开始处理。如果超过 10 分钟仍未开始，请联系技术支持。

Q3：kling-v3 和 kling-v3-omni 有什么区别？

A：

kling-v3：支持文生视频、图生视频

kling-v3-omni：在 kling-v3 基础上，额外支持视频参考（运动控制）功能

Q4：如何控制生成视频的质量？

A：

使用 mode: "pro" 或 mode: "4k" 提升质量

使用 metadata.cfgScale 参数调整提示词相关性（0.6-0.8 推荐）

提供详细的正面和负面提示词

技术支持

如有问题，请联系技术支持或查看更多文档：

邮箱：support@moyu.info

文档中心：https://www.moyu.info/docs

API 状态：https://www.moyu.info/status

接口地址#

提交任务#

查询结果#

获取视频内容#

模型说明#

可用模型#

模式选择#

请求示例#

1. 文生视频 (Text-to-Video)#

基础示例#

带完整参数的示例#

2. 图生视频 (Image-to-Video)#

使用公网 URL#

使用 Base64 编码图片#

3. 视频参考 / 运动控制（仅 kling-v3-omni）#

单个参考视频#

多个参考视频#

请求参数详解#

核心参数#

图生视频参数#

视频参考参数（仅 kling-v3-omni）#

高级参数#

提交任务响应格式#

成功响应#

响应字段说明#

查询任务结果#

查询请求#

查询响应示例#

任务排队中#

任务处理中#

任务成功#

任务失败#

状态码说明#

获取视频内容#

方式一：直接使用 video_url#

方式二：使用内容接口#

差异化计费说明#

计费维度#

计费示例#

最佳实践#

提示词建议#

图片要求#

性能优化#

常见错误#

错误码说明#

常见问题#

技术支持#

接口地址

提交任务

查询结果

获取视频内容

模型说明

可用模型

模式选择

请求示例

1. 文生视频 (Text-to-Video)

基础示例

带完整参数的示例

2. 图生视频 (Image-to-Video)

使用公网 URL

使用 Base64 编码图片

3. 视频参考 / 运动控制（仅 kling-v3-omni）

单个参考视频

多个参考视频

请求参数详解

核心参数

图生视频参数

视频参考参数（仅 kling-v3-omni）

高级参数

提交任务响应格式

成功响应

响应字段说明

查询任务结果

查询请求

查询响应示例

任务排队中

任务处理中

任务成功

任务失败

状态码说明

获取视频内容

方式一：直接使用 video_url

方式二：使用内容接口

差异化计费说明

计费维度

计费示例

最佳实践

提示词建议

图片要求

性能优化

常见错误

错误码说明

常见问题

技术支持