可灵 (Kling AI) 视频生成全量接口文档 (OpenAI & 原生格式)¶
本接口通过 new-api 提供两种调用方式：
1. OpenAI 兼容模式：适用于标准视频客户端，参数经过映射。
2. 原生转发模式：参数结构完全对齐原厂文档，适合直接集成。
1. OpenAI 兼容调用格式 (推荐)¶
- 接口地址:
POST /v1/video/generations - 认证方式:
Authorization: Bearer $API_KEY
1.0 基础调用示例（curl）¶
curl https://api-cs-al.naci-tech.com/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "kling-v2-6",
"prompt": "一只猫咪在舞台上唱歌，聚光灯打在它身上，4K 高清画质，电影感",
"size": "1280x720",
"duration": 5
}'
上面示例会被 new-api 自动映射到 Kling 文生视频接口（16:9，5s）。
1.1 基础参数映射¶
| OpenAI 字段 | 类型 | 说明 | 对应原厂逻辑 |
|---|---|---|---|
model |
string | 模型名称，如 kling-v2-6, kling-video-o1 |
自动匹配后端接口 |
prompt |
string | 正向提示词，≤2500 字符 | 映射至 prompt |
image |
string | 参考图 URL | 映射至 init_image (自动开启图生视频) |
size |
string | 尺寸，如 1280x720, 1024x1024 |
自动转为 aspect_ratio (16:9, 1:1 等) |
duration |
number | 时长 (s)，仅支持 5, 10 | 自动转为 duration_string |
1.2 高级扩展参数 (Extra Parameters)¶
所有非 OpenAI 标准的字段必须放在 metadata 对象中（或在支持自定义 JSON 的客户端中放在最外层）。
适用于 kling-v2-6 / kling-v1-6:
{
"model": "kling-v2-6",
"prompt": "猫咪在唱歌",
"metadata": {
"negative_prompt": "模糊", // 负向提示词
"mode": "pro", // 模式: std, pro
"cfg_scale": 0.5, // 自由度 [0, 1]
"sound": "on", // 是否生成声音: on, off
"callback": "https://...", // 回调地址
"params": "user_id_123", // 回调透传参数
"voice_list": [ // 引用音色
{ "voice_id": "system_v1" }
]
}
}
1.2.1 携带高级参数的完整 curl 示例¶
curl https://api-cs-al.naci-tech.com/v1/video/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "kling-v2-6",
"prompt": "一只猫咪在舞台上唱歌，聚光灯打在它身上，4K 高清画质，电影感",
"size": "1280x720",
"duration": 10,
"metadata": {
"negative_prompt": "模糊, 低清晰度",
"mode": "pro",
"cfg_scale": 0.5,
"sound": "on",
"callback": "https://example.com/kling/callback",
"params": "user_id_123",
"voice_list": [
{ "voice_id": "system_v1" }
]
}
}'
适用于 kling-video-o1 (Omni) 的特有参数:
{
"model": "kling-video-o1",
"prompt": "...",
"metadata": {
"images": [ // 参考图列表 (首尾帧)
{ "image_url": "...", "type": "first_frame" },
{ "image_url": "...", "type": "end_frame" }
],
"elements": [ // 主体参考列表
{ "element_id": "obj_123" }
],
"videos": [ // 参考视频
{ "video_url": "...", "refer_type": "base", "keep_original_sound": "yes" }
]
}
}
2. 原生转发模式 (Native API)¶
如果你希望直接使用原厂文档定义的结构，可以使用以下路径。此路径下 new-api 仅做鉴权和智能路由，不修改你的 Payload。
- 文生/图生视频:
POST /kling/v1/videos/text2video或/kling/v1/videos/image2video - 状态查询:
GET /kling/v1/videos/text2video/{task_id}
2.0 文生视频调用示例（curl）¶
curl https://api-cs-al.naci-tech.com/kling/v1/videos/text2video \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "kling-v2-6",
"prompt": "一只猫咪在舞台上唱歌，聚光灯打在它身上，4K 高清画质，电影感",
"negative_prompt": "模糊, 低清晰度",
"mode": "std",
"aspect_ratio": "16:9",
"duration_string": "5",
"cfg_scale": 0.5,
"sound": "on",
"callback": "https://example.com/kling/callback",
"params": "user_id_123"
}'
2.0.1 图生视频调用示例（curl）¶
curl https://api-cs-al.naci-tech.com/kling/v1/videos/image2video \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "kling-v2-6",
"prompt": "保持主体风格不变，让角色缓慢走向镜头",
"negative_prompt": "模糊, 低清晰度",
"init_image": "https://example.com/input-image.jpg",
"image_tail": "https://example.com/end-frame.jpg",
"mode": "pro",
"aspect_ratio": "16:9",
"duration_string": "10",
"cfg_scale": 0.6,
"sound": "on",
"callback": "https://example.com/kling/callback",
"params": "user_id_123"
}'
2.1 文生/图生全量参数 (Kling V1.6/V2.6)¶
{
"model": "kling-v2-6",
"prompt": "string",
"negative_prompt": "string",
"init_image": "url", // 仅图生视频必填
"image_tail": "url", // 可选，尾帧；使用尾帧时须 mode=pro（std 不支持，报 1201）
"mode": "std", // std, pro；有 image_tail 时须传 pro
"aspect_ratio": "16:9", // 16:9, 9:16, 1:1
"duration_string": "5", // "5", "10"
"cfg_scale": 0.5,
"sound": "on",
"voice_list": [{"voice_id": "..."}],
"callback": "url",
"params": "string"
}
参数限制 (文生/图生)¶
| 参数 | 限制 |
|---|---|
model |
枚举：kling-v2-5-turbo、kling-v2-6 |
prompt / negative_prompt |
必填 / 可选，均不超过 2500 字符 |
mode |
枚举：std、pro；V1.6 不支持 pro |
aspect_ratio |
枚举：16:9、9:16、1:1，默认 16:9 |
duration_string |
字符串枚举："5"、"10"（单位秒） |
cfg_scale |
取值范围 [0, 1]，越大与提示词越一致 |
sound |
枚举：on、off；仅 V2.6 及后续模型支持 |
voice_list |
至多 **2 个**音色；voice_id 来自音色定制接口或系统预置 |
图生 init_image / image_tail |
图生时 init_image 必填；两者**不能同时为空**。使用 image_tail 时须用 mode=pro，kling-v2-6 在 std 模式下不支持 image_tail（否则报 code 1201）。 |
2.2 Omni (O1) 模型全量参数 (Kling o1)¶
路径同上，系统检测到 model 为 o1 会自动处理。
{
"model": "kling-video-o1",
"prompt": "string",
"images": [
{ "image_url": "url", "type": "first_frame" }, // type: first_frame, end_frame, 或参考图(空)
{ "image_url": "url", "type": "end_frame" }
],
"elements": [
{ "element_id": "string" }
],
"videos": [
{
"video_url": "url",
"refer_type": "feature", // feature (特征参考), base (待编辑)
"keep_original_sound": "yes" // yes, no
}
],
"mode": "pro",
"aspect_ratio": "16:9",
"duration_string": "10",
"callback": "url",
"params": "string"
}
参数限制 (Omni)¶
| 参数 | 限制 |
|---|---|
prompt |
不超过 2500 字符，可含正/负向描述 |
images |
有参考视频时 数量 ≤4；无参考视频时 ≤7；超过 2 张时不可设尾帧；不支持仅尾帧（有尾帧必须有首帧）；首帧/首尾帧生视频时不可用视频编辑 |
| 图片格式 | .jpg / .jpeg / .png；单张 ≤10MB；宽高 ≥300px；宽高比 1:2.5～2.5:1 |
elements |
有参考视频时「参考图数量 + 主体数量」≤4；无参考视频时 ≤7 |
videos |
至多 1 段；格式 MP4/MOV；时长 3～10 秒；宽高 720～2160px；帧率 24～60fps（输出 24fps）；≤200MB；待编辑视频（base）时不可定义首尾帧 |
mode |
枚举：std（标准）、pro（专家） |
aspect_ratio |
枚举：16:9、9:16、1:1；当参考图作为首帧或使用视频编辑时，任务创建可能失败 |
duration_string |
枚举：3～10（字符串）；文生/首帧图生仅支持 "5"、"10"；有传入视频时输出与输入时长一致，本参数无效 |
3. 任务状态常量说明 (通用)¶
| 状态文本 (OpenAI) | 状态代码 (原生) | 描述 |
|---|---|---|
queued |
1 | 排队中 |
processing |
2 | 处理中 (此时会返回 progress 进度) |
succeeded |
3 | 成功 |
failed |
4, 5 | 失败 / 超时 |
关于查询接口¶
提交任务后，可以使用任务 ID 进行状态查询。
1. OpenAI 风格查询 (推荐)¶
适用于标准 OpenAI 视频响应格式。
curl https://api-cs-al.naci-tech.com/v1/video/generations/task_id_here \
-H "Authorization: Bearer $API_KEY"
2. 原生风格查询¶
返回原厂定义的原始响应结构。