00-概述
可灵 AI 视频生成（新版接口）· 概述
contents（素材）、settings（输出配置）、options（通用配置）三部分，所有任务通过 GET /kling/tasks 统一查询。请求与响应格式与可灵官方一致，原样透传。新版与原版 接口的区别
| 对比项 | 新版接口（本目录） | 原版接口 |
|---|---|---|
| 创建路径 | /kling/{能力}/{模型}，如 /kling/text-to-video/kling-3.0 | /kling/v1/videos/{能力}，如 /kling/v1/videos/text2video |
| 指定模型 | URL 路径段，如 kling-3.0 | 请求体 model_name，如 kling-v3 |
| 请求体 | contents + settings + options | 平铺字段（prompt、image、mode、sound 等） |
| 查询任务 | 统一 GET /kling/tasks?task_ids=...，支持批量 | 各能力单独查询 GET /kling/v1/videos/{能力}/{task_id} |
| 成功状态值 | succeeded | succeed |
| 覆盖能力 | 文生视频、图生视频、Omni 视频生成、动作控制 | 以上四类，以及多图参考、视频编辑、对口型、音频等 |
能力与模型
| 能力 | 接口路径 | 支持模型 |
|---|---|---|
| 文生视频 | POST /kling/text-to-video/{model} | kling-3.0、kling-2.6、kling-2.5-turbo |
| 图生视频 | POST /kling/image-to-video/{model} | kling-3.0、kling-2.6、kling-2.5-turbo |
| Omni 视频生成 | POST /kling/omni-video/{model} | kling-3.0-omni、kling-o1 |
| 动作控制 | POST /kling/motion-control/{model} | kling-3.0、kling-2.6 |
| 查询任务 | GET /kling/tasks | — |
| URL 段名 | 模型广场名称 | 说明 |
|---|---|---|
kling-3.0 | kling-v3 | 支持多镜头、原生音频，最高 4K |
kling-3.0-omni | kling-v3-omni | 多模态输入（图片、视频、主体），支持多镜头、原生音频，最高 4K |
kling-o1 | kling-video-o1 | 多模态输入，支持参考视频 |
kling-2.6 | kling-v2-6 | 支持原生音频与指定音色 |
kling-2.5-turbo | kling-v2-5-turbo | 不支持音频 |
调用流程
id，再轮询查询接口直到 succeeded 或 failed。成功后从 outputs[].url 下载视频，链接 30 天后失效，请及时转存。创建任务 POST /kling/{能力}/{model} -> 返回 data.id，status = submitted
查询任务 GET /kling/tasks?task_ids={id} -> 轮询直到 succeeded / failed
下载视频 outputs[].url接口地址与鉴权
/kling + 可灵官方新版路径（新版路径没有 /v1）。例如官方 /text-to-video/kling-3.0 对应 https://platform.shuyanai.com/kling/text-to-video/kling-3.0。| 请求头 | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer sk-xxx，在控制台「模型 API Key」页面创建 |
Content-Type | 是 | application/json |
通用默认值
settings 中的字段时按以下默认值处理：| 参数 | 默认值 |
|---|---|
settings.resolution | 720p |
settings.duration | 5（秒） |
settings.audio | off（动作控制默认 original） |
settings.aspect_ratio | 16:9 |
任务状态
| 状态 | 含义 |
|---|---|
submitted | 已提交 |
processing | 处理中 |
succeeded | 生成成功 |
failed | 生成失败 |
响应格式
{
"code": 0,
"message": "SUCCEED",
"request_id": "string",
"data": {}
}| 字段 | 类型 | 说明 |
|---|---|---|
code | Int | 错误码，0 表示成功 |
message | String | 错误信息 |
request_id | String | 请求 ID，用于跟踪、排查问题 |
data | Object / Array | 业务数据；查询任务接口为数组 |
回调通知
options.callback_url。设置后，任务状态变化时会以 POST 方式向该地址发送通知。