API 参考
生成视频
POST /api/ai-video/jobs:通过文本提示词创建生成任务,支持参考图、音频和尾帧控制。
请求
POST /api/ai-video/jobscurl -X POST 'https://kling-4.ai/api/ai-video/jobs' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "kling-v2-6",
"prompt": "Handheld close-up of a barista pouring latte art, warm morning window light, shallow depth of field",
"parameters": {
"mode": "pro",
"duration": 10,
"aspectRatio": "16:9",
"audio": true,
"negativePrompt": "beauty smoothing, plastic skin",
"imageUrls": ["https://example.com/reference.jpg"]
}
}'请求体字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | 模型标识,默认为 kling-v2-6。参见模型。 |
prompt | string | 是 | 描述要生成的内容,长度为 1–2500 个字符。清晰的结构比堆砌形容词更有效,参见提示词指南。 |
parameters | object | 否 | 生成参数,见下表。 |
parameters
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | "std" | "pro" | "std" | pro 支持音频和尾帧控制,并提供更高的渲染质量。 |
duration | 5 | 10 | 5 | 视频时长,单位为秒。 |
aspectRatio | "16:9" | "9:16" | "1:1" | "16:9" | 输出画面比例。 |
audio | boolean | false | 为视频生成原生音频。仅限 Pro 模式。 |
negativePrompt | string | — | 描述不希望出现的内容,最多 1000 个字符。 |
imageUrls | string[] | — | 最多 2 个公开可访问的图片 URL。1 张图片用于锁定参考特征(面孔、产品、风格);2 张图片用于首尾帧控制,仅限 Pro 模式。 |
校验规则
参数组合冲突时,API 会返回 400 INVALID_INPUT:
audio: true要求mode: "pro"。- 传入 2 个
imageUrls(尾帧控制)要求mode: "pro"。 audio: true不能与 2 个imageUrls同时使用。
响应
200 OK 表示任务已被接受并加入队列:
{
"job": {
"id": "0b6c2f6e-6d5f-4a4e-9d3e-7c9a1f2b8d41",
"model": "kling-v2-6",
"prompt": "Handheld close-up of a barista…",
"status": "queued",
"progress": 0,
"parameters": {
"mode": "pro",
"duration": 10,
"aspectRatio": "16:9",
"audio": true
},
"resultUrl": null,
"resultExpiresAt": null,
"thumbnailUrl": null,
"errorMessage": null,
"createdAt": "2026-07-09T03:12:45.000Z",
"updatedAt": "2026-07-09T03:12:46.000Z",
"completedAt": null
}
}视频生成是异步过程。请保存 job.id,轮询 GET /api/ai-video/jobs/{id},直到 status 为 completed 或 failed。
需要处理的错误
| 状态码 | 错误代码 | 含义 |
|---|---|---|
400 | INVALID_INPUT | 请求不符合数据结构或校验规则;错误消息会指出相应字段。 |
429 | DAILY_QUOTA_USED | 今日免费生成次数已用完,请在下一个 UTC 零点后重试。 |
502 | CREATE_JOB_FAILED | 渲染服务拒绝了任务;可采用退避策略重试。 |
完整的错误格式见错误处理。
完整示例(Node.js)
const BASE = 'https://kling-4.ai';
const headers = {
'x-api-key': process.env.KLING_API_KEY!,
'Content-Type': 'application/json',
};
// 1. Create the job
const createRes = await fetch(`${BASE}/api/ai-video/jobs`, {
method: 'POST',
headers,
body: JSON.stringify({
prompt: 'A tiny astronaut discovering a glowing garden inside a glass terrarium, macro lens, soft volumetric light',
parameters: { duration: 5, aspectRatio: '16:9' },
}),
});
if (!createRes.ok) throw new Error((await createRes.json()).error.message);
let { job } = await createRes.json();
// 2. Poll until it finishes
while (job.status === 'queued' || job.status === 'processing') {
await new Promise((r) => setTimeout(r, 15_000));
const pollRes = await fetch(`${BASE}/api/ai-video/jobs/${job.id}`, { headers });
({ job } = await pollRes.json());
console.log(`${job.status} ${job.progress}%`);
}
// 3. Download the result — resultUrl expires, so store your own copy
if (job.status === 'completed') {
console.log('video:', job.resultUrl);
} else {
console.error('failed:', job.errorMessage);
}