Generate a Video

POST /api/ai-video/jobs — create a generation job from a text prompt, with optional reference images, audio, and end-frame control.

Request

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"]
    }
  }'

Body fields

Field	Type	Required	Description
`model`	string	no	Model string. Defaults to `kling-v2-6` — see Models.
`prompt`	string	yes	What to generate, 1–2500 characters. Structure beats adjectives — see the prompt guide.
`parameters`	object	no	Generation settings, below.

`parameters`

Field	Type	Default	Description
`mode`	`"std"` \| `"pro"`	`"std"`	`pro` unlocks audio and end-frame control, at higher render quality.
`duration`	`5` \| `10`	`5`	Clip length in seconds.
`aspectRatio`	`"16:9"` \| `"9:16"` \| `"1:1"`	`"16:9"`	Output frame.
`audio`	boolean	`false`	Generate native audio with the clip. Pro mode only.
`negativePrompt`	string	—	What to avoid, up to 1000 characters.
`imageUrls`	string[]	—	Up to 2 public image URLs. One image = reference lock (face, product, style). Two images = first-frame + end-frame control, pro mode only.

Validation rules

The API rejects contradictory combinations with 400 INVALID_INPUT:

audio: true requires mode: "pro".
Two imageUrls (end-frame control) requires mode: "pro".
audio: true cannot be combined with two imageUrls.

Response

200 OK — the job was accepted and queued:

{
  "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
  }
}

Generation is asynchronous — hold on to job.id and poll GET /api/ai-video/jobs/{id} until status is completed or failed.

Errors you should handle

Status	Code	Meaning
`400`	`INVALID_INPUT`	Schema or validation-rule violation; the message names the field.
`429`	`DAILY_QUOTA_USED`	Today's free generation is used — retry after the next UTC midnight.
`502`	`CREATE_JOB_FAILED`	The render pipeline rejected the task; safe to retry with backoff.

The full error format is in Errors.

A complete example (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);
}

Request

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"]
    }
  }'

Body fields

Field	Type	Required	Description
`model`	string	no	Model string. Defaults to `kling-v2-6` — see Models.
`prompt`	string	yes	What to generate, 1–2500 characters. Structure beats adjectives — see the prompt guide.
`parameters`	object	no	Generation settings, below.

`parameters`

Field	Type	Default	Description
`mode`	`"std"` \| `"pro"`	`"std"`	`pro` unlocks audio and end-frame control, at higher render quality.
`duration`	`5` \| `10`	`5`	Clip length in seconds.
`aspectRatio`	`"16:9"` \| `"9:16"` \| `"1:1"`	`"16:9"`	Output frame.
`audio`	boolean	`false`	Generate native audio with the clip. Pro mode only.
`negativePrompt`	string	—	What to avoid, up to 1000 characters.
`imageUrls`	string[]	—	Up to 2 public image URLs. One image = reference lock (face, product, style). Two images = first-frame + end-frame control, pro mode only.

Validation rules

The API rejects contradictory combinations with 400 INVALID_INPUT:

audio: true requires mode: "pro".
Two imageUrls (end-frame control) requires mode: "pro".
audio: true cannot be combined with two imageUrls.

Response

200 OK — the job was accepted and queued:

{
  "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
  }
}

Generation is asynchronous — hold on to job.id and poll GET /api/ai-video/jobs/{id} until status is completed or failed.

Errors you should handle

Status	Code	Meaning
`400`	`INVALID_INPUT`	Schema or validation-rule violation; the message names the field.
`429`	`DAILY_QUOTA_USED`	Today's free generation is used — retry after the next UTC midnight.
`502`	`CREATE_JOB_FAILED`	The render pipeline rejected the task; safe to retry with backoff.

The full error format is in Errors.

A complete example (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);
}

Request

Body fields

`parameters`

Validation rules

Response

Errors you should handle

A complete example (Node.js)

Table of Contents

Generate a Video

Request

Body fields

`parameters`

Validation rules

Response

Errors you should handle

A complete example (Node.js)

Table of Contents