跳到主要内容

Kling v3 视频生成接口文档

本文档描述视频生成接口的对外接入方式，支持文生视频、图生视频和音画同出。

1. 基本信息​

项目内容
Base URLhttps://api.openfde.work
接口路径/v1/videos
模型名称kling-v3
请求格式application/json
鉴权方式Bearer Token
支持能力文生视频、图生视频、音画同出

2. 鉴权方式​

所有接口请求都需要在 Header 中携带访问令牌：

Authorization: Bearer sk-xxx
Content-Type: application/json

说明：

  • sk-xxx 为平台分配的 API Token。
  • API Token 应由服务端保管，不建议暴露在浏览器、客户端 App 或小程序中。

3. 创建视频生成任务​

接口说明​

POST /v1/videos

用于创建 Kling v3 视频生成任务。

  • 不传 image：文生视频。
  • 传入 image：图生视频。

请求参数​

参数类型必填说明
modelstring是模型名称，固定传 kling-v3
promptstring是视频生成提示词
sizestring否视频分辨率档位，支持 720P、1080P、2K、4K
secondsstring否视频时长，单位为秒，例如 "5"
imagestring否图生视频输入图，支持 http(s) 图片 URL 或 base64；不传则为文生视频
metadataobject否视频生成扩展参数
metadata.generate_audioboolean否是否生成同步音频：true 开启音画同出，false 生成无声视频；建议显式传值

文生视频请求体示例​

{
  "model": "kling-v3",
  "prompt": "一只猫在草原上奔跑，伴随风声和轻快背景音乐，电影感镜头",
  "size": "720P",
  "seconds": "5",
  "metadata": {
    "generate_audio": true
  }
}

图生视频请求体示例​

{
  "model": "kling-v3",
  "prompt": "让画面动起来",
  "size": "720P",
  "seconds": "5",
  "image": "https://example.com/input.jpg",
  "metadata": {
    "generate_audio": true
  }
}

音频参数说明​

  • metadata.generate_audio: true：请求生成与画面同步的 AI 原生音频。
  • metadata.generate_audio: false：明确请求生成无声视频。
  • 音频会直接合成到生成的视频文件中，查询接口的响应字段结构不变，仍从 metadata.url 获取最终视频。

成功响应​

HTTP 状态码：200

{
  "id": "1391445290-AigcVideoTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "1391445290-AigcVideoTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0,
  "created_at": 1785161953
}

响应字段说明​

字段类型说明
idstring视频任务 ID
task_idstring视频任务 ID，通常与 id 一致
objectstring对象类型，固定为 video
modelstring模型名称
statusstring当前任务状态
progressnumber当前任务进度
created_atnumber创建时间，Unix 秒级时间戳

4. 查询视频生成任务​

接口说明​

GET /v1/videos/{task_id}

用于查询视频生成任务的当前状态和生成结果。

路径参数​

参数类型必填说明
task_idstring是创建任务时返回的 id 或 task_id

处理中响应示例​

{
  "id": "1391445290-AigcVideoTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "kling-v3",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1785161953
}

完成响应示例​

{
  "id": "1391445290-AigcVideoTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "kling-v3",
  "status": "completed",
  "progress": 100,
  "created_at": 1785161953,
  "completed_at": 1785162007,
  "seconds": "5.042",
  "metadata": {
    "url": "https://example.com/video/output.mp4"
  }
}

完成响应字段说明​

字段类型说明
statusstringcompleted 表示视频生成完成
progressnumber完成时通常为 100
completed_atnumber完成时间，Unix 秒级时间戳
secondsstring生成视频实际时长
metadata.urlstring生成后的视频文件地址

5. 任务状态说明​

状态是否终态说明
queued否任务已创建，等待调度
unknown否任务状态暂未同步，可继续查询
in_progress否视频正在生成中
completed是视频生成成功
failed是视频生成失败

建议处理方式：

  • 创建任务成功后，使用返回的 id 或 task_id 查询任务状态。
  • 建议每 5 秒查询一次任务状态。
  • 建议最长等待时间为 600 秒。
  • unknown 不代表任务失败，建议继续查询。
  • progress 仅表示参考进度，不保证线性增长。

6. 失败响应​

当任务生成失败时，查询接口可能返回：

{
  "id": "1391445290-AigcVideoTask-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "kling-v3",
  "status": "failed",
  "progress": 0,
  "error": {
    "code": "ERROR_CODE",
    "message": "失败原因"
  }
}

失败字段说明​

字段类型说明
error.codestring错误码
error.messagestring错误描述

7. 接入流程​

flowchart TD
  A["提交视频生成请求"] --> B["获取 task_id"]
  B --> C["定时查询任务状态"]
  C --> D{"是否终态"}
  D -- "否" --> C
  D -- "completed" --> E["读取 metadata.url"]
  D -- "failed" --> F["读取 error 信息"]

8. 接入注意事项​

  • metadata.url 为生成后的视频地址，有效期一天，建议业务侧按需转存。
  • metadata.generate_audio 的实际能力取决于 kling-v3 当前配置的生成渠道；若显式传入 true 后结果仍为无声视频，请联系平台管理员确认渠道是否支持音画同出。