La API de generación de video de Kling usa tareas asíncronas. El primer paso para integrarla no es escribir una solicitud, sino obtener la credencial, colocarla en el lugar correcto y limitar sus permisos. Muchos errores 401 y 403 no vienen del código: la clave se copió mal, la variable de entorno no se aplicó o la cuenta no tiene habilitado el modelo correspondiente.

Este artículo explica, en el orden "crear, configurar, diagnosticar y rotar", las formas de credencial y las prácticas de seguridad más comunes en la plataforma abierta de Kling en 2026. Los detalles de la interfaz cambian con rapidez; para la operación real, consulta la consola y la documentación oficiales.

Nota: Kling, Kuaishou y sus marcas asociadas son propiedad de sus respectivos titulares. Este artículo solo ofrece información técnica y no implica afiliación ni representación con las empresas mencionadas.

1. Primero, confirma qué credencial necesitas

Kling maneja actualmente dos formas de autenticación:

  • API Key: se crea en la consola de desarrolladores y se envía en Authorization: Bearer <API_KEY>. Las interfaces nuevas identifican el modelo en la ruta, y se recomienda dar prioridad a este método.
  • AccessKey + SecretKey: se usa principalmente en las interfaces antiguas. En cada solicitud, el SecretKey firma un JWT y el JWT se coloca en el encabezado Bearer. El AccessKey va en la declaración iss.

Los requisitos de seguridad son distintos: una API Key es una credencial de larga duración y, si se filtra, puede usarse directamente; en AccessKey/SecretKey, el SecretKey es la clave de firma y, si se filtra, un atacante puede emitir tokens por su cuenta. En ninguno de los dos casos la credencial debe ir en el código del frontend, en el paquete de una app móvil ni en un repositorio público.

2. Pasos para crear una API Key de Kling

La consola internacional está en https://kling.ai/dev/api-key; después de iniciar sesión con una cuenta de Kling puedes gestionar las claves. La entrada para China continental y los modelos disponibles dependen de la página oficial; no armes dominios copiando tutoriales de terceros.

  1. Inicia sesión en la consola de desarrolladores y abre la página de gestión de API Keys.
  2. Haz clic en "+ Create a new API Key" y nómbrala según proyecto, entorno y uso, por ejemplo video-prod-cn o video-test.
  3. Copia y guarda la clave de inmediato. La página suele mostrarla una sola vez y, al cerrarla, ya no se puede ver completa.
  4. Guarda la clave en un gestor de contraseñas o en un servicio de gestión de secretos en la nube; registra también quién la creó, para qué sirve y cuándo debe rotarse.
  5. Verifica la autenticación con una tarea de costo mínimo y anota el request_id devuelto para facilitar el diagnóstico posterior.
  6. Confirma que la cuenta tenga un paquete de recursos comprado o pago por uso habilitado antes de pasar a la integración formal.

Nombrar bien las claves no es un formalismo. Cuando aparezca una llamada anómala, el nombre te permitirá ubicar rápidamente qué servicio y qué entorno están implicados, sin detener todo el negocio a la vez.

3. AccessKey/SecretKey y JWT en las interfaces antiguas

Las interfaces antiguas indican el modelo con model_name en el cuerpo de la solicitud y requieren generar el JWT por cuenta propia. La regla de la documentación oficial es firma HS256, iss con el AccessKey, exp igual a la hora actual más 1800 segundos y nbf igual a la hora actual menos 5 segundos.

import os
import time
import jwt  # PyJWT

access_key = os.environ["KLING_ACCESS_KEY"]
secret_key = os.environ["KLING_SECRET_KEY"]

token = jwt.encode(
    {
        "iss": access_key,
        "exp": int(time.time()) + 1800,
        "nbf": int(time.time()) - 5,
    },
    secret_key,
    algorithm="HS256",
    headers={"alg": "HS256", "typ": "JWT"},
)
print(token)

Puntos que suelen causar problemas:

  • exp se expresa en segundos Unix, no en milisegundos; si usas milisegundos obtendrás un token que expira muy lejos pero que la plataforma puede rechazar.
  • El reloj del servidor debe estar sincronizado. Con una desviación grande, la validación de nbf falla y aparece el mensaje de que el token aún no es válido.
  • El JWT solo dura 30 minutos; durante el sondeo de tareas largas hay que regenerarlo, no usar el mismo token hasta el final.
  • No mezcles JWT con API Key. Las interfaces nuevas usan API Key; solo las antiguas usan firma AK/SK. Consulta siempre la documentación de la interfaz correspondiente.

4. Permisos, paquetes de recursos y límites de concurrencia

En la documentación de Kling, el error de permisos más habitual es el código de negocio 1103 (HTTP 403), que significa "sin permiso para solicitar esa API o modelo". Normalmente se relaciona con el estado de la cuenta, la habilitación del modelo o el paquete de recursos, no con una clave inválida.

Conviene distinguir tres tipos de límites:

  • Estado de la cuenta: 1100 indica estado anómalo; 1101, deuda en pago por uso; 1102, paquete de prepago agotado o vencido.
  • Permisos de modelo: 1103 indica que la cuenta actual no puede llamar a esa interfaz o modelo.
  • Cuota de concurrencia: las tareas de video usan ranuras de concurrencia según el paquete de recursos y, al excederlas, devuelven 1303. La documentación oficial aclara que todas las API Keys de una misma cuenta comparten el mismo pool de concurrencia.

Esto significa que "crear varias claves" no aporta más concurrencia ni aísla de verdad el tráfico de producción del de pruebas. Si necesitas aislamiento estricto, usa cuentas independientes o paquetes de recursos independientes y añade una cola de tareas en la arquitectura. Por ahora, la documentación de Kling no ofrece ámbitos granulares por interfaz, como solo lectura o generación; los permisos dependen de la cuenta y de las capacidades contratadas. Si la consola incorpora más adelante autorizaciones detalladas, prevalecerá lo que muestre la consola.

5. Claves en variables de entorno y gestión de secretos

El mínimo es usar variables de entorno; en producción conviene recurrir a Secrets Manager del proveedor de nube, Kubernetes Secret o un servicio similar. No confirmes claves en Git ni imprimas el valor completo en los registros.

Nombres recomendados para las variables:

KLING_API_KEY=...
KLING_ACCESS_KEY=...
KLING_SECRET_KEY=...
KLING_BASE_URL=https://api-singapore.klingai.com

En el repositorio deja solo .env.example con marcadores de posición. Al arrancar, la aplicación debe comprobar que las variables existen y fallar si faltan, en lugar de enviar solicitudes con una cadena vacía. En los registros, guarda como máximo los primeros 4 y los últimos 4 caracteres de la clave, y conserva el request_id. El navegador y las apps móviles no deben poseer la clave; todas las tareas de video deben enviarse mediante un proxy en el backend.

6. Tabla de diagnóstico de errores 401

Código de negocio HTTP Significado Causa habitual Qué hacer
1000 401 Falló la autenticación Formato incorrecto del encabezado Comprueba que Authorization exista
1001 401 Encabezado de autenticación vacío Variable de entorno vacía, proxy que elimina el encabezado Imprime la longitud de la variable y revisa el reenvío del gateway
1002 401 Credencial no válida Clave copiada incompleta, revocada o de otro entorno Vuelve a crear la clave y actualízala
1003 401 Token aún no válido Reloj del servidor desviado, nbf mal configurado Sincroniza NTP y revisa la unidad de tiempo
1004 401 Token expirado JWT antiguo con más de 30 minutos Genera un JWT nuevo

Se recomienda diagnosticar de fuera hacia dentro: primero confirma que la solicitud lleva realmente el encabezado, después que la clave pertenece al entorno actual y solo al final sospecha de la plataforma. Si usas un proxy inverso o una plataforma serverless, verifica si filtra el encabezado Authorization.

7. ¿Conexión directa o gateway de API?

La conexión directa a la plataforma abierta de Kling mantiene la cuenta, los paquetes de recursos, los registros de llamadas y la facturación bajo tu control; es adecuada para equipos con capacidad de compra y operación. Con un gateway de API puedes reunir varios modelos de video bajo una sola clave y una sola factura, y reducir el costo de integración.

Al elegir un gateway, confirma cuatro cosas: si ya tiene habilitado el canal de video de Kling, si admite las tareas asíncronas y external_task_id sin alterarlos, si puede reenviar la URL de callback y cómo se entregan las URL de resultados. Un gateway que solo admite interfaces de texto compatibles con OpenAI no sirve directamente para tareas de video. Puedes consultar modelos y precios y registrarte para probar; valida primero con la tarea más pequeña y luego decide si migras el tráfico de producción.

8. Rotación y respuesta ante filtraciones

La rotación debe ser una operación rutinaria, no una reacción de emergencia. Se recomienda rotar cada 90 días y hacerlo de inmediato cuando alguien deja el equipo o se transfiere un proyecto.

  1. Crea una clave nueva en la consola con la fecha en el nombre, por ejemplo video-prod-20261019.
  2. Guárdala en el servicio de gestión de secretos, actualiza el entorno de pruebas y ejecuta una tarea mínima de principio a fin.
  3. Actualiza producción de forma gradual y observa los errores 401, 403 y la tasa de éxito de las tareas.
  4. Cuando la nueva clave sea estable, revoca la anterior.
  5. Registra la fecha de rotación, quién la ejecutó y qué servicios se vieron afectados.

Si sospechas una filtración, revoca primero la clave antigua, revisa después el historial de llamadas y la facturación, y solo entonces investiga cómo se filtró. Cambiar el código sin revocar la credencial deja el riesgo intacto. El Webhook Secret es otra credencial; la plataforma admite que el secreto antiguo y el nuevo coexistan durante un periodo de gracia de 7 días, de modo que puede rotarse por separado de la API Key.

Preguntas frecuentes

¿Cuál es la diferencia entre la API Key de Kling y AccessKey/SecretKey?

La API Key es una credencial única que se envía en el encabezado Bearer; AccessKey/SecretKey es el mecanismo de firma antiguo y requiere generar un JWT. En las interfaces nuevas se prefiere la API Key; en las antiguas se usa JWT según la documentación.

¿Se pueden crear varias API Keys en una cuenta? ¿Se suman las concurrencias?

Sí, puedes crear varias claves por entorno y proyecto, pero la documentación oficial indica que todas comparten el pool de concurrencia de la cuenta; crear más claves no aumenta la concurrencia. Para aislamiento estricto, usa cuentas o paquetes de recursos independientes.

El error 401 dice que la credencial no es válida, pero la clave parece correcta. ¿Qué hago?

Comprueba primero si copiaste la cadena completa, si hay espacios o saltos de línea, si la solicitud va a la región correcta y si un proxy reescribió o eliminó el encabezado Authorization. Si persiste, crea una clave nueva y haz una prueba de comparación.

¿Caduca la API Key de Kling?

Por lo general, la API Key no caduca por un plazo fijo, pero puede dejar de funcionar por revocación, cambios en el estado de la cuenta o cambios de permisos. El JWT antiguo dura 30 minutos. La política concreta depende de la consola y la documentación oficial.

¿Necesito una cuenta de Kling si uso un gateway de API?

No necesariamente. El gateway suele alojar la cuenta upstream y la facturación, pero los modelos disponibles, la concurrencia, los callbacks y la política de retención de datos dependen del gateway. Antes de integrarte, confirma si el canal de video está habilitado y lee sus términos de servicio.

Lecturas relacionadas: