Справочник 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 общедоступных изображений. Одно изображение закрепляет референс (лицо, продукт или стиль). Два изображения задают первый и последний кадры, только в режиме Pro. |
Правила проверки
API отклоняет несовместимые сочетания с ошибкой 400 INVALID_INPUT:
audio: trueтребуетmode: "pro".- Два
imageUrls(управление последним кадром) требуютmode: "pro". audio: trueнельзя использовать вместе с двумя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);
}