Referencia de la API
Generar un video
POST /api/ai-video/jobs: crea una tarea a partir de un prompt de texto, con imágenes de referencia, audio y control del fotograma final opcionales.
Solicitud
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"]
}
}'Campos del cuerpo
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
model | string | No | Identificador del modelo. El valor predeterminado es kling-v2-6; consulta Modelos. |
prompt | string | Sí | Describe qué quieres generar, entre 1 y 2500 caracteres. Una buena estructura funciona mejor que acumular adjetivos; consulta la guía de prompts. |
parameters | object | No | Ajustes de generación, descritos a continuación. |
parameters
| Campo | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
mode | "std" | "pro" | "std" | pro habilita el audio y el control del fotograma final, con mayor calidad de renderizado. |
duration | 5 | 10 | 5 | Duración del clip en segundos. |
aspectRatio | "16:9" | "9:16" | "1:1" | "16:9" | Relación de aspecto de salida. |
audio | boolean | false | Genera audio nativo junto con el clip. Solo en modo Pro. |
negativePrompt | string | — | Describe lo que debe evitarse, hasta 1000 caracteres. |
imageUrls | string[] | — | Hasta 2 URL de imágenes públicas. Una imagen fija una referencia (rostro, producto o estilo). Dos imágenes permiten controlar el primer y el último fotograma, solo en modo Pro. |
Reglas de validación
La API rechaza las combinaciones incompatibles con 400 INVALID_INPUT:
audio: truerequieremode: "pro".- Dos
imageUrls(control del fotograma final) requierenmode: "pro". audio: trueno se puede combinar con dosimageUrls.
Respuesta
200 OK: la tarea se ha aceptado y añadido a la cola:
{
"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
}
}La generación es asíncrona: guarda job.id y consulta periódicamente GET /api/ai-video/jobs/{id} hasta que status sea completed o failed.
Errores que debes gestionar
| Estado | Código | Significado |
|---|---|---|
400 | INVALID_INPUT | Se incumple el esquema o una regla de validación; el mensaje indica el campo afectado. |
429 | DAILY_QUOTA_USED | Se ha agotado la generación gratuita de hoy; vuelve a intentarlo después de la próxima medianoche UTC. |
502 | CREATE_JOB_FAILED | El servicio de renderizado ha rechazado la tarea; puedes reintentar aumentando la espera entre intentos. |
Consulta el formato completo en Errores.
Ejemplo completo (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);
}