可灵 AI 视频生成 · 概述#
原版接口对应可灵官方 /v1 系列接口：模型通过请求体 model_name 指定，每类能力有各自的创建与查询地址。请求与响应格式与可灵官方一致，原样透传。原版与新版接口的区别#
| 对比项 | 原版接口（本目录） | 新版接口 |
|---|
| 创建路径 | /kling/v1/videos/{能力}，如 /kling/v1/videos/text2video | /kling/{能力}/{模型}，如 /kling/text-to-video/kling-3.0 |
| 指定模型 | 请求体 model_name，如 kling-v3 | URL 路径段，如 kling-3.0 |
| 请求体 | 平铺字段（prompt、image、mode、sound 等） | contents + settings + options |
| 查询任务 | 各能力单独查询 GET /kling/v1/videos/{能力}/{task_id}，另有列表查询 | 统一 GET /kling/tasks?task_ids=...，支持批量 |
| 成功状态值 | succeed | succeeded |
| 覆盖能力 | 文生、图生、Omni、动作控制，以及多图参考、视频编辑、对口型、音频等 | 文生视频、图生视频、Omni 视频生成、动作控制 |
两套接口并行提供、互不影响。已接入原版或需要新版未覆盖的能力时用原版；新接入且只需要文生、图生、Omni、动作控制时，可直接使用新版。能力简介#
| 能力 | 接口路径 | 说明 |
|---|
| 文生视频 | POST /kling/v1/videos/text2video | 根据文本提示词生成视频 |
| 图生视频 | POST /kling/v1/videos/image2video | 以首帧 / 尾帧图片生成视频 |
| 视频 Omni | POST /kling/v1/videos/omni-video | 结合主体、图片、视频等多种输入生成视频 |
| 多图参考生视频 | POST /kling/v1/videos/multi-image2video | 多张参考图片生成视频 |
| 动作控制 | POST /kling/v1/videos/motion-control | 参考视频驱动图片中的人物动作 |
| 多模态视频编辑 | POST /kling/v1/videos/multi-elements | 对视频中的元素进行增加、替换、删除 |
| 视频延长 | POST /kling/v1/videos/video-extend | 延长已有视频时长 |
| 对口型 | POST /kling/v1/videos/advanced-lip-sync | 音频驱动视频中的人物口型 |
| 数字人 | POST /kling/v1/videos/avatar/image2video | 图片 + 音频生成数字人视频 |
| 文生音效 | POST /kling/v1/audio/text-to-audio | 根据文本描述生成音效 |
| 视频配音效 | POST /kling/v1/audio/video-to-audio | 为视频生成音效与配乐 |
| 语音合成 | POST /kling/v1/audio/tts | 文本转语音 |
| 音色克隆 | POST /kling/v1/general/custom-voices | 创建与查询自定义音色 |
| 图像识别 | POST /kling/v1/videos/image-recognize | 识别图片中的主体、人脸、服装 |
| 主体管理 | POST /kling/v1/general/advanced-custom-elements | 创建、查询、删除自定义主体 |
文生视频、图生视频、视频 Omni、动作控制须通过 model_name 指定模型；不传时请求会被拒绝（model_price_error）。| 模型 | 可用于 |
|---|
kling-v3 | 文生视频、图生视频、动作控制 |
kling-v3-omni | 视频 Omni |
kling-video-o1 | 视频 Omni |
kling-v2-6 | 文生视频、图生视频、动作控制 |
kling-v2-5-turbo | 文生视频、图生视频 |
kling-v2-1 | 文生视频、图生视频 |
调用流程#
视频生成是异步任务：创建后返回 task_id，再轮询对应的查询接口直到 succeed 或 failed。成功后从 task_result.videos[].url 下载视频，链接 30 天后失效，请及时转存。创建任务 POST /kling/v1/videos/{能力} -> 返回 task_id，task_status = submitted
查询任务 GET /kling/v1/videos/{能力}/{task_id} -> 轮询直到 succeed / failed
下载视频 task_result.videos[].url
multi-elements/*-selection）、删除主体为同步接口，结果直接在响应中返回，无需轮询。接口地址与鉴权#
地址规则：平台域名 + /kling + 可灵官方原始路径。例如官方 /v1/videos/text2video 对应 https://platform.shuyanai.com/kling/v1/videos/text2video。| 请求头 | 必填 | 说明 |
|---|
Authorization | 是 | Bearer sk-xxx，在控制台「模型 API Key」页面创建 |
Content-Type | 是 | application/json |
任务状态#
| 状态 | 含义 |
|---|
submitted | 已提交 |
processing | 处理中 |
succeed | 生成成功 |
failed | 生成失败 |
列表查询#
各能力的查询接 口不带 task_id 时返回任务列表，只包含通过本平台提交的任务：| 查询参数 | 默认值 | 说明 |
|---|
pageNum | 1 | 页码，取值 1~1000 |
pageSize | 30 | 每页数量，取值 1~500 |
列表接口返回的 task_status 取值与单个查询不同（成功为 success、失败为 failure），判断任务结果请以单个查询为准。
响应格式#
{
"code": 0,
"message": "SUCCEED",
"request_id": "string",
"data": {}
}
| 字段 | 类型 | 说明 |
|---|
code | Int | 错误码，0 表示成功 |
message | String | 错误信息 |
request_id | String | 请求 ID，用于跟踪、排查问题 |
data | Object / Array | 业务数据；列表查询为数组 |
回调通知#
创建任务时可传 callback_url。设置后，任务状态变化时会以 POST 方式向该地址发送通知。
