API de Kling: guía de integración oficial y mediante agregadores (2026)

Una solicitud de vídeo a Kling no se resuelve con una única llamada API universal. El modelo de generación de vídeo de Kuaishou está disponible tanto en la Open Platform oficial como a través de agregadores como WaveSpeedAI, KIE y fal. Cada vía tiene sus propias credenciales, IDs de modelo, formatos de petición y facturación. Lo que sí se mantiene es el flujo asíncrono: envías un trabajo, guardas su ID, esperas un estado final y recuperas el resultado sin lanzar reintentos sin control.

Elige la vía de acceso antes que el SDK

Kling mantiene una Open Platform oficial, pero al buscar “Kling API” también aparecen pasarelas independientes. No decidas solo por el nombre del modelo: valora qué proveedor te da acceso, con qué rapidez puedes integrarlo y cómo controla la facturación.

Para consultar precios por resolución, revisa la guía de precios de Kling 3 API ya publicada. En este artículo, considera el precio, los multiplicadores de audio, la concurrencia y la facturación de tareas fallidas como configuración específica de cada proveedor.

Flujo oficial de Kling

Opta por la Open Platform oficial si tu proceso de compra exige una relación directa con Kuaishou o necesitas disponibilidad de modelos de primera parte. La documentación oficial actual separa la configuración de credenciales, la creación de tareas, los callbacks, las reglas de concurrencia y los códigos de error. Sigue ese recorrido en lugar de adaptar el payload de un agregador:

1. Crea o recupera la credencial oficial en la guía de autenticación y conserva el token exclusivamente en el servidor.
2. Envía la tarea asíncrona de vídeo documentada usando el endpoint específico del modelo y los campos de solicitud de la referencia oficial.
3. Añade callback_url si quieres recibir actualizaciones de estado. Los estados de callback documentados incluyen submitted, processing, succeed y failed; guarda task_status_msg cuando haya errores.
4. Haz cumplir localmente la asignación de concurrencia vigente de tu cuenta. La guía oficial de concurrencia describe la sobrecarga como HTTP 429 con código de negocio 1303, no como trabajo que Kling vaya a encolar necesariamente por ti.
5. Utiliza la referencia oficial de códigos de error para distinguir entre credenciales incorrectas, parámetros no válidos, recursos agotados, bloqueos de políticas y fallos de servidor que admiten reintento.

La página oficial de autenticación se renderiza en cliente en la versión accesible de la documentación, por lo que esta guía no reproduce un fragmento de generación de tokens sin verificar. Copia el formato de credencial actual de esa página en vez de asumir que sirve una cabecera de WaveSpeed, KIE o fal.

Aun así, puedes normalizar el ciclo de vida oficial sin adivinar el payload exacto:

official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)

Es un esquema del ciclo de vida, no un endpoint listo para copiar y pegar. Consulta la referencia oficial enlazada para conocer el token, la ruta, los campos de petición y el formato de respuesta exactos.

Cuándo conviene usar un agregador

Los agregadores agilizan los prototipos que necesitan acceso de pago por uso, una sola cuenta para varios modelos o un SDK del proveedor. A cambio, ellos controlan la clave, el esquema, la cola, la URL de salida y, en algunos casos, la retención. Antes de reintentar, identifica qué capa ha fallado.

El contrato de la API de Kling que sí puedes unificar

En producción, conviene ocultar las particularidades de cada proveedor detrás de una única función interna. Independientemente de la vía elegida, tu aplicación debe seguir estos pasos:

1. Validar el prompt y las URL de medios antes de gastar créditos.
2. Enviar una tarea de generación de vídeo con un ID de modelo específico del proveedor.
3. Persistir de inmediato el ID de tarea o predicción recibido.
4. Recibir un callback o consultar un endpoint de resultados hasta que el trabajo alcance un estado final.
5. Guardar la URL de salida, el proveedor, el modelo, los parámetros y los metadatos de coste.
6. Dejar de reintentar cuando el proveedor informe de fallo, cancelación, timeout o eliminación.

La abstracción debería devolver un objeto normalizado propio, por ejemplo:

{
  "provider": "wavespeed",
  "job_id": "provider-job-id",
  "status": "queued",
  "output_url": null,
  "error": null
}

Parámetros que suelen ser equivalentes

Los conceptos se parecen; los nombres de campo, no. generate_audio, sound y generate_audio: true pueden expresar comportamientos relacionados en servicios distintos. Trata el esquema de cada proveedor como un adaptador independiente.

Parámetros que no son intercambiables

Los IDs de modelo son la primera trampa. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video y kwaivgi/kling-v3.0-std/text-to-video identifican rutas API distintas; no son valores sustituibles entre sí.

Lo mismo ocurre con las cabeceras de autenticación, los nombres de callback, las URL de resultados, los valores de estado de tarea y las reglas de carga de archivos. Un cliente que fija un estado de un proveedor —por ejemplo, completed— puede clasificar mal la respuesta succeeded o failed de otro.

Tres formatos de solicitud reales

Estos ejemplos específicos de cada proveedor dejan claro por qué no existe un endpoint universal para Kling.

WaveSpeedAI: ID de predicción y consulta del resultado

WaveSpeedAI documenta Kling 3.0 Standard text-to-video en este endpoint:

POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video

La petición utiliza un token Bearer. El endpoint devuelve un ID de predicción y el resultado se consulta en:

GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/result

Un flujo mínimo con cURL sería:

export WAVESPEED_API_KEY="replace_me"

submit=$(curl --fail-with-body -s \
  -X POST \
  "https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cinematic sunrise over a futuristic cityscape",
    "duration": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "shot_type": "customize"
  }')

prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')

curl -s \
  "https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"

La documentación del modelo de WaveSpeedAI indica un rango de 3–15 segundos, relaciones 16:9, 9:16 y 1:1, y un valor predeterminado de 0.5 para cfg_scale. Su tabla de precios de Standard muestra $0.42 por un clip de 5 segundos sin sonido y $0.63 con sonido; tómalo como una referencia puntual de ese proveedor, no como un precio universal de Kling.

En producción, consulta el endpoint de resultados con backoff en lugar de hacer peticiones en un bucle cerrado. Detente en completed, failed, cancelled, timeout o deleted, que son los estados terminales documentados para este endpoint.

KIE: createTask con callback o consulta de tarea

KIE utiliza un endpoint compartido para crear tareas:

POST https://api.kie.ai/api/v1/jobs/createTask

El identificador de Kling 3.0 es kling-3.0/video y la autenticación emplea un token Bearer. Un payload compacto para un único plano tiene este aspecto:

{
  "model": "kling-3.0/video",
  "callBackUrl": "https://example.com/webhooks/kie",
  "input": {
    "prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "std",
    "sound": false,
    "multi_shots": false
  }
}

KIE documenta vídeos de 3–15 segundos, relaciones de salida 16:9, 9:16 y 1:1, y hasta cinco planos en modo multi-shot. Las entradas multi-shot pueden especificar entre 1 y 12 segundos cada una. Los elementos de imagen usan de 2 a 4 URL JPG o PNG, con un máximo documentado de 10 MB por imagen; los elementos de vídeo usan una URL MP4 o MOV de hasta 50 MB.

El callback es opcional, aunque KIE lo recomienda en producción. Tu webhook debe verificar la firma cuando esté disponible, confirmar la recepción rápidamente y enviar el resultado de la tarea a una cola. Mantén la consulta de tareas como vía de recuperación para callbacks perdidos.

KIE documenta códigos de respuesta diferenciados para fallos comunes, incluidos 401 para autenticación no válida, 402 para créditos insuficientes, 422 para errores de validación y 429 para límites de frecuencia. Registra siempre el código junto al mensaje: un “Kling falló” genérico no basta para decidir si es seguro reintentar.

fal: endpoint de modelo y cliente de cola

fal expone Kling 3.0 mediante IDs de endpoint específicos del modelo. Para Standard text-to-video, el ID documentado es:

fal-ai/kling-video/v3/standard/text-to-video

La API sin procesar utiliza la cabecera Authorization: Key $FAL_KEY. Los ejemplos de Python y JavaScript usan el cliente de fal compatible con colas, que suele ser más sencillo que implementar el bucle de consulta por tu cuenta.

import { fal } from "@fal-ai/client";

fal.config({ credentials: process.env.FAL_KEY });

const result = await fal.subscribe(
  "fal-ai/kling-video/v3/standard/text-to-video",
  {
    input: {
      prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
      duration: 5,
      aspect_ratio: "16:9",
      generate_audio: false,
      negative_prompt: "blur, distort, low quality",
      cfg_scale: 0.5
    },
    logs: true
  }
);

console.log(result.data.video.url);

fal documenta un rango de 3–15 segundos, tres relaciones de aspecto para text-to-video y un intervalo de cfg_scale de 0 a 1, con 0.5 como valor predeterminado. El esquema de Standard indica que prompt y multi_prompt son alternativas: proporciona uno, no ambos. El valor predeterminado documentado de generate_audio es true, así que defínelo explícitamente si tu presupuesto o flujo de posproducción presupone una salida sin sonido.

fal también documenta IDs independientes para image-to-video y motion-control. No deduzcas esos IDs cambiando text-to-video en una cadena sin comprobar antes la referencia actual del modelo.

Cuotas, tiempos de cola y protección de créditos

No existe una cuota pública única de Kling aplicable a la plataforma oficial, WaveSpeedAI, KIE y fal. La concurrencia, los límites de frecuencia, los saldos de crédito, la facturación de tareas fallidas y la retención de resultados dependen de la vía elegida. Guarda esos valores como configuración del proveedor, no como constantes llamadas KLING_LIMIT.

Un usuario resumió el riesgo operativo con más precisión que una recomendación genérica de reintentos:

“Kling cobra por generación y tiene latencia real de cola. Lo primero que conectaría es un límite de coste/concurrencia; de lo contrario, un agente que reintenta por un fotograma defectuoso puede quemar tus créditos durante la noche sin que te enteres.” — @ukrroot on X

Protecciones de presupuesto y concurrencia

Implementa estos controles antes de permitir que un agente o proceso por lotes llame a Kling:

1. Máximo de trabajos en curso: Establece un límite específico por proveedor en vez de iniciar un trabajo por cada prompt.
2. Presupuesto por trabajo: Estima duración, nivel, audio y cantidad de resultados antes del envío.
3. Presupuesto de reintentos: Reintenta los errores de transporte de forma selectiva; no reintentes errores de validación, autenticación o créditos insuficientes.
4. Registro de trabajos: Guarda el ID de trabajo del proveedor antes de cualquier solicitud posterior para que un reinicio del worker no envíe una generación duplicada.
5. Política de estados terminales: Marca como finalizados los trabajos fallidos, cancelados, agotados por tiempo o eliminados, salvo que el proveedor indique expresamente que es seguro reenviarlos.
6. Alarma de crédito: Detén la cola cuando el saldo o el gasto previsto supere un umbral.
7. Seguridad de claves y resultados: Mantén las claves en el servidor, rota de inmediato cualquier clave expuesta y copia los vídeos finalizados a un almacenamiento duradero.

Una prueba Standard de cinco segundos puede resultar barata frente a un trabajo Pro de 15 segundos o con audio, pero “barato” depende del proveedor. Lee la página actual del modelo antes de elegir un nivel predeterminado.

Métricas que debes medir antes de producción

Registra estos campos en cada solicitud:

Considera que la latencia y las cuotas son específicas de cada endpoint; las fuentes públicas no ofrecen un SLA único entre proveedores.

Preguntas frecuentes sobre la API de Kling

¿Kling tiene una API oficial?

Sí. Kling mantiene un área de documentación para desarrolladores de su Open Platform oficial. La vía oficial y las pasarelas de terceros son servicios distintos, así que verifica las credenciales, cuotas y precios actuales en la documentación de Kling Open Platform.

¿Existe un endpoint universal para la API de Kling?

No. La plataforma oficial, WaveSpeedAI, KIE y fal usan rutas de endpoint, IDs de modelo, cabeceras de autenticación y formatos de respuesta diferentes. Crea un adaptador por proveedor en vez de asumir que kling-3.0 es válido en todas partes.

¿Conviene usar polling o webhooks?

En producción, usa un callback o webhook cuando el proveedor lo admita, pero conserva el polling para pruebas locales y para recuperarte de callbacks perdidos. Añade backoff exponencial, un límite total de espera e idempotencia para que un callback tardío no cree un registro duplicado.

¿Qué duraciones y relaciones de aspecto son compatibles?

Varios documentos actuales de agregadores para Kling 3.0 indican clips de 3–15 segundos y relaciones 16:9, 9:16 y 1:1. Los endpoints individuales pueden variar, así que valida siempre en la página del modelo elegido en lugar de tratar esos valores como un contrato universal de primera parte.

¿Activar el audio cambia el coste?

Normalmente puede cambiarlo. WaveSpeedAI documenta un multiplicador de sonido de 1.5× para su endpoint Kling 3.0 Standard, mientras que fal y KIE exponen audio o sonido como parámetros de solicitud. Consulta la página de facturación actual del endpoint elegido y define la opción explícitamente.

¿Por qué un reintento generó cargos adicionales?

Un reintento puede crear una segunda generación aunque el primer trabajo siga en cola. Conserva el ID del trabajo, aplica un límite de concurrencia, reintenta solo fallos transitorios y reconcilia la facturación del proveedor antes de reenviar una solicitud ambigua.

Para la primera prueba similar a producción, ejecuta un único trabajo Standard silencioso de 5 segundos, registra todo el ciclo de vida y añade Pro, audio, multi-shot o concurrencia solo después de que la gestión de workers duplicados funcione correctamente.