Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Este documento presenta una guía para integrar la API Kling Videos Generation, la cual permite generar videos oficiales de Kling mediante la entrada de parámetros personalizados.

​
Proceso de solicitud

Para usar la API, primero debe solicitar el servicio en la página correspondiente de Kling Videos Generation API. Al ingresar, haga clic en el botón «Acquire», como se muestra en la imagen: Si no ha iniciado sesión o registrado, será redirigido automáticamente a la página de login para registrarse e iniciar sesión, y luego volverá automáticamente a la página actual. En la primera solicitud, se le ofrecerá un monto gratuito para probar la API sin costo.

​
Uso básico

Primero, familiarícese con el método de uso básico: ingrese los parámetros prompt (mensaje de entrada), action (acción de generación), start_image_url (imagen de referencia para la primera frame) y model (modelo). Con esto, podrá obtener la respuesta procesada. Debe enviar un campo action con valor 'text2video', que soporta tres acciones principales: generación de video desde texto (text2video), desde imagen (image2video), y expansión de videos (extend). Además, es necesario especificar el modelo model, con modelos principales como kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1. La lista completa incluye:

En la cabecera de la solicitud, se configuran los encabezados:
  • accept: indica en qué formato desea recibir la respuesta, aquí como application/json.
  • authorization: clave para acceder a la API, disponible tras la solicitud.
En el cuerpo de la solicitud (Request Body), se incluyen:
  • model: modelo de generación de video (kling-v1, kling-v1-6, etc.).
  • mode: modo de generación, puede ser std (estándar), pro (alta velocidad) o 4k (modo 4K nativo; solo kling-v3 y kling-v3-omni, y no compatible con camera_control).
  • action: acción de generación, text2video, image2video o extend.
  • start_image_url: URL de referencia para la primera frame en image2video.
  • end_image_url: opcional para video desde imagen, señalando la última frame.
  • duration: duración del video en segundos, soportando entre 3 y 15 segundos en kling-v3 y kling-v3-omni, otros modelos soportan 5 o 10 segundos.
  • generate_audio: si se desea síntesis de audio sincronizada, booleano, soportado en kling-v3, kling-v3-omni y kling-v2-6 (solo en modo pro); por defecto false.
  • aspect_ratio: proporción de aspecto de video (16:9, 9:16, 1:1), valor predeterminado es 16:9.
  • cfg_scale: factor de relevancia (similitud) en rango [0,1].
  • camera_control: configuración para control de movimiento de la cámara, soporta presets type/simple y parámetros como horizontal, vertical, pan, tilt, roll, zoom.
  • negative_prompt: palabras o frases que no desea que aparezcan (máximo 200 caracteres).
  • element_list: lista de referencia de sujetos; exclusivo para modelo kling-video-o1 (consultar documentación oficial).
  • video_list: videos de referencia por URL, solo para kling-video-o1.
  • prompt: las instrucciones o texto de entrada.
  • callback_url: URL donde se enviará el resultado mediante callback asíncrono.
Al seleccionar los parámetros, en el lado derecho se genera automáticamente el código de ejemplo, como en la siguiente imagen:

Con un clic en “Try”, puede realizar la prueba y obtener una respuesta como la siguiente: 
{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}
Los campos principales son:
  • success: si la tarea fue exitosa.
  • task_id: ID único de la tarea.
  • video_id: ID único del video generado.
  • video_url: enlace para descargar el video.
  • duration: duración del video en segundos.
  • state: estado actual del proceso.
Para obtener el video generado, basta con acceder al video_url proporcionado. Para integrar mediante código, por ejemplo usando CURL: 
curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

​
Matriz de capacidades de modelos

Cada modelo tiene soporte diferente para los parámetros. La siguiente tabla resume la compatibilidad según la documentación oficial de modelos de video de Kling. Antes de usar, confirme que la combinación de model / mode / duration soporta la función deseada; de lo contrario, la API devolverá errores como model/mode/duration(...) is not supported with image_tail.
ModeloModeend_image_urlgenerate_audiocamera_controlNotas
kling-v1std / pro✅ solo duration=5❌✅ solo duration=5extend no soporta negative_prompt ni cfg_scale
kling-v1-6std❌❌❌compatible con multi-imagen y modo extend
kling-v1-6pro✅❌❌
kling-v2-master—❌❌❌modo único, soporta solo duration=5 o 10
kling-v2-1-master—❌❌❌modo único, soporta solo duration=5 o 10
kling-v2-5-turbostd❌❌❌
kling-v2-5-turbopro✅❌❌
kling-v2-6std❌❌❌
kling-v2-6pro✅✅❌único modelo no v3 que soporta audio simultáneo
kling-v3std / pro✅✅✅duration de 3–15 segundos
kling-v34k✅✅❌modo 4K no compatible con control de cámara
kling-v3-omnistd / pro / 4k✅✅❌
kling-video-o1std / pro✅❌❌solo soporta duration=5/10
Notas importantes:
  • mode=4k solo soporta kling-v3 y kling-v3-omni; no combina con camera_control.
  • end_image_url solo funciona en modo image2video junto con start_image_url.
  • duration: general en 3–15 segundos para modelos kling-v3 y kling-v3-omni; otros modelos solo aceptan 5 o 10.
  • generate_audio por defecto es false. Solo soportan en kling-v3, kling-v3-omni y kling-v2-6 en modo pro.

​
Función de expansión de video

Para extender un video previamente generado, configure action en 'extend' y pase video_id del video existente. La obtención del video_id es mediante el método básico explicado anteriormente, como en la imagen:

Por ejemplo, el ID del video sería: 
"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"
Nota: ese video_id corresponde al video generado previamente. Si no sabe cómo obtenerlo, consulte la sección correspondiente del método básico.
Luego, puede definir nuevas instrucciones de generación de video, por ejemplo:
  • model: modelos kling-v1, kling-v1-5 o kling-v1-6.
  • mode: modo std, pro o 4k (solo ciertos modelos).
  • duration: duración en segundos, típicamente 5 o 10.
  • start_image_url: para image2video.
  • prompt: instrucciones de entrada.
Ejemplo de envío:

El código generado automáticamente en Python sería: 
import requests

url = "https://api.xhuoapi.ai/v1/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Al correrlo, se obtiene un resultado similar: 
{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}
Este proceso permite la expansión del video previamente generado.

​
Callback asíncrono

Dado que la generación de videos puede tardar entre 1 y 2 minutos, la API soporta callbacks asíncronos para evitar mantener conexiones abiertas y evitar consumo excesivo de recursos. El método: el cliente envía la solicitud incluyendo callback_url. La API responde inmediatamente con un task_id, y cuando la generación finalice, enviará un POST JSON a esa URL con el resultado, incluyendo también task_id para relacionar el proceso. Ejemplo práctico: Primero, configure un servicio web que reciba las llamadas HTTP, por ejemplo, usando https://webhook.site/. Al ingresar, copie la URL proporcionada, como en la imagen: Luego, establezca callback_url en esa URL y envíe los parámetros necesarios. La respuesta será algo así: 
{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
Después de unos momentos, verá en la URL del webhook la respuesta de generación, por ejemplo: Y el contenido JSON similar a: 
{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
El task_id permite relacionar el resultado con la tarea original.

​
Manejo de errores

En caso de error, la API devuelve códigos y mensajes específicos, por ejemplo:
  • 400 token_mismatched: solicitud incorrecta, parámetros inválidos o faltantes.
  • 400 api_not_implemented: función no soportada o mal uso.
  • 401 invalid_token: error de autorización.
  • 429 too_many_requests: límite de velocidad alcanzado.
  • 500 api_error: error interno en el servidor.
Ejemplo de respuesta de error: 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusión

Este documento explicó cómo usar la API Kling Videos Generation para crear videos mediante instrucciones de texto y referencias visuales. Esperamos que le facilite la integración y utilización del servicio. Para cualquier duda, puede contactarnos con nuestro soporte técnico.