Kling 4.0kling-4.ai 帮助文档
Kling 4.0kling-4.ai 帮助文档
首页

快速开始

概览

API 参考

API 概览身份验证生成视频查询与列出任务模型错误与额度
X
API 参考

生成视频

POST /api/ai-video/jobs:通过文本提示词创建生成任务,支持参考图、音频和尾帧控制。

请求

POST /api/ai-video/jobs
curl -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"]
    }
  }'

请求体字段

字段类型必填说明
modelstring否模型标识,默认为 kling-v2-6。参见模型。
promptstring是描述要生成的内容,长度为 1–2500 个字符。清晰的结构比堆砌形容词更有效,参见提示词指南。
parametersobject否生成参数,见下表。

parameters

字段类型默认值说明
mode"std" | "pro""std"pro 支持音频和尾帧控制,并提供更高的渲染质量。
duration5 | 105视频时长,单位为秒。
aspectRatio"16:9" | "9:16" | "1:1""16:9"输出画面比例。
audiobooleanfalse为视频生成原生音频。仅限 Pro 模式。
negativePromptstring—描述不希望出现的内容,最多 1000 个字符。
imageUrlsstring[]—最多 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。

需要处理的错误

状态码错误代码含义
400INVALID_INPUT请求不符合数据结构或校验规则;错误消息会指出相应字段。
429DAILY_QUOTA_USED今日免费生成次数已用完,请在下一个 UTC 零点后重试。
502CREATE_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);
}

身份验证

申请 API 访问,并使用 x-api-key 请求头验证请求。

查询与列出任务

获取单个任务、列出近期任务或刷新全部活跃任务,并了解任务如何从排队进入完成状态。

目录

请求
请求体字段
parameters
校验规则
响应
需要处理的错误
完整示例(Node.js)