Kling 4.0Documentación de kling-4.ai
Kling 4.0Documentación de kling-4.ai
Inicio

Primeros pasos

Introducción

Referencia de la API

Introducción a la APIAutenticaciónGenerar un videoConsultar y listar tareasModelosErrores y cuotas
X
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/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"]
    }
  }'

Campos del cuerpo

CampoTipoObligatorioDescripción
modelstringNoIdentificador del modelo. El valor predeterminado es kling-v2-6; consulta Modelos.
promptstringSíDescribe qué quieres generar, entre 1 y 2500 caracteres. Una buena estructura funciona mejor que acumular adjetivos; consulta la guía de prompts.
parametersobjectNoAjustes de generación, descritos a continuación.

parameters

CampoTipoValor predeterminadoDescripción
mode"std" | "pro""std"pro habilita el audio y el control del fotograma final, con mayor calidad de renderizado.
duration5 | 105Duración del clip en segundos.
aspectRatio"16:9" | "9:16" | "1:1""16:9"Relación de aspecto de salida.
audiobooleanfalseGenera audio nativo junto con el clip. Solo en modo Pro.
negativePromptstring—Describe lo que debe evitarse, hasta 1000 caracteres.
imageUrlsstring[]—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: true requiere mode: "pro".
  • Dos imageUrls (control del fotograma final) requieren mode: "pro".
  • audio: true no se puede combinar con dos imageUrls.

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

EstadoCódigoSignificado
400INVALID_INPUTSe incumple el esquema o una regla de validación; el mensaje indica el campo afectado.
429DAILY_QUOTA_USEDSe ha agotado la generación gratuita de hoy; vuelve a intentarlo después de la próxima medianoche UTC.
502CREATE_JOB_FAILEDEl 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);
}

Autenticación

Solicita acceso a la API y autentica tus peticiones con la cabecera x-api-key.

Consultar y listar tareas

Obtén una tarea, lista las recientes o actualiza todas las activas; conoce el recorrido de una tarea desde la cola hasta su finalización.

Índice

Solicitud
Campos del cuerpo
parameters
Reglas de validación
Respuesta
Errores que debes gestionar
Ejemplo completo (Node.js)