> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Instrucciones de integración de la API de generación de videos Kling > Kling video generation API guide - Ace Data Cloud Este documento presentará una guía de integración de la API de generación de videos Kling, que permite generar videos oficiales de Kling mediante la entrada de parámetros personalizados. ## Proceso de solicitud Para utilizar la API de generación de videos Kling, primero dirígete a [la consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu token de API, que debes guardar para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual. **Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.** La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en [la consola](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [API de generación de videos Kling →](https://platform.acedata.cloud/documents/kling-videos) ## Uso básico Primero, es importante entender la forma básica de uso, que consiste en ingresar la palabra clave `prompt`, la acción de generación `action`, la imagen de referencia del primer fotograma `start_image_url` y el modelo `model`, para obtener el resultado procesado. Primero, necesitas pasar un campo `action`, cuyo valor es `text2video`, que incluye principalmente tres acciones: video a partir de texto (`text2video`), video a partir de imagen (`image2video`), y video extendido (`extend`). Luego, también necesitamos ingresar el modelo `model`, que actualmente incluye principalmente los modelos `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-o1`, cuyos detalles son los siguientes:

Aquí podemos ver que hemos configurado los encabezados de la solicitud, que incluyen: * `accept`: el formato de respuesta que deseas recibir, aquí se establece como `application/json`, es decir, en formato JSON. * `authorization`: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla. Además, se ha configurado el cuerpo de la solicitud, que incluye: * `model`: el modelo para generar el video, que incluye principalmente `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-o1`. * `mode`: el modo de generación de video, con valores opcionales como modo estándar `std`, modo rápido `pro` y modo nativo 4K `4k`. El `4k` solo es compatible con `kling-v3` y `kling-v3-omni`, y no es compatible con `camera_control` (control de cámara). * `action`: la acción de la tarea de generación de video, que incluye principalmente tres acciones: video a partir de texto (`text2video`), video a partir de imagen (`image2video`), y video extendido (`extend`). * `start_image_url`: cuando se elige la acción de video a partir de imagen `image2video`, es necesario subir el enlace de la imagen de referencia del primer fotograma. * `end_image_url`: opcional al generar video a partir de imagen, especifica el fotograma final. * `duration`: duración del video, en segundos. `kling-v3` y `kling-v3-omni` admiten duraciones enteras de 3 a 15 segundos; `kling-o1` solo admite 5 segundos; otros modelos admiten 5 o 10 segundos. * `generate_audio`: si se debe generar audio de forma sincronizada, opcional, valor booleano. Admite `kling-v3`, `kling-v3-omni` y `kling-v2-6` (solo en modo pro). Por defecto es `false`. * `aspect_ratio`: relación de aspecto del video, opcional, admite `16:9`, `9:16`, `1:1`, por defecto `16:9`. * `cfg_scale`: intensidad de correlación, rango \[0,1], cuanto mayor, más se ajusta a la palabra clave. * `camera_control`: opcional, parámetros para controlar el movimiento de la cámara, admite configuraciones predefinidas type/simple y horizontal, vertical, pan, tilt, roll, zoom, etc. * `negative_prompt`: opcional, palabras clave inversas que no deseas que aparezcan, máximo 200 caracteres. * `image_list`: lista de imágenes de referencia Omni, aplicable a los modelos `kling-o1` y `kling-v3-omni`, consulta el uso en la sección "Referencia Omni". * `video_list`: lista de videos de referencia Omni (admite edición de video), aplicable a los modelos `kling-o1` y `kling-v3-omni`, consulta el uso en la sección "Referencia Omni". * `prompt`: palabra clave. * `callback_url`: URL para recibir el resultado de la llamada. * `async`: opcional, si se establece en `true`, la interfaz devuelve inmediatamente `task_id`, sin necesidad de proporcionar `callback_url`, y luego se puede consultar el resultado mediante la interfaz de consulta de tareas correspondiente. Después de seleccionar, puedes ver que también se ha generado el código correspondiente a la derecha, como se muestra en la imagen:

Haz clic en el botón "Try" para realizar una prueba, como se muestra en la imagen anterior, y obtendrás el siguiente resultado: ```json theme={null} { "success": true, "video_id": "900798310464749610", "video_url": "https://platform2.cdn.acedata.cloud/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5.mp4", "duration": "5.041", "state": "succeed", "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5" } ``` El resultado devuelto contiene varios campos, que se describen a continuación: * `success`, el estado de la tarea de generación de video en ese momento. * `task_id`, el ID de la tarea de generación de video en ese momento. * `video_id`, el ID del video de la tarea de generación de video en ese momento. * `video_url`, el enlace del video de la tarea de generación de video en ese momento. * `duration`, la duración del video de la tarea de generación de video en ese momento. * `state`, el estado de la tarea de generación de video en ese momento. Como puedes ver, hemos obtenido información satisfactoria sobre el video, y solo necesitamos acceder al enlace del video generado en `data` para obtener el video de Kling. Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código de CURL es el siguiente: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-v3", "prompt": "Taza de café de cerámica blanca sobre una encimera de mármol brillante con luz de ventana de la mañana. La cámara rota lentamente 360 grados alrededor de la taza, deteniéndose brevemente en el asa." }' ``` ## Matriz de capacidades del modelo El soporte de parámetros varía significativamente entre diferentes modelos. La siguiente matriz se ha organizado a partir de la [documentación oficial de modelos de video de Kling](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels), asegúrate de verificar si la combinación actual de `model` / `mode` / `duration` admite las funciones que necesitas, de lo contrario, el sistema devolverá errores como `model/mode/duration(...) is not supported with image_tail`. | Modelo | Modo | `end_image_url` (fotograma final) | `generate_audio` (audio) | `camera_control` (control de cámara) | Notas | | ------------------- | -------------- | --------------------------------- | ------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `kling-v1` | std / pro | ✅ solo `duration=5` | ❌ | ✅ solo `duration=5` | `extend` no soporta `negative_prompt` y `cfg_scale` | | `kling-v1-6` | std | ❌ | ❌ | ❌ | Generación de video a partir de múltiples imágenes, `extend` disponible en todos los modos | | `kling-v1-6` | pro | ✅ | ❌ | ❌ | | | `kling-v2-master` | — | ❌ | ❌ | ❌ | Modo único, solo `duration=5/10` | | `kling-v2-1-master` | — | ❌ | ❌ | ❌ | Modo único, solo `duration=5/10` | | `kling-v2-5-turbo` | std | ❌ | ❌ | ❌ | | | `kling-v2-5-turbo` | pro | ✅ | ❌ | ❌ | | | `kling-v2-6` | std | ❌ | ❌ | ❌ | | | `kling-v2-6` | pro | ✅ | ✅ | ❌ | Único modelo no v3 que soporta audio simultáneamente | | `kling-v3` | std / pro | ✅ | ✅ | ✅ | Rango de `duration` de 3 a 15 segundos | | `kling-v3` | 4k | ✅ | ✅ | ❌ | Modo 4K no compatible con control de cámara | | `kling-v3-omni` | std / pro / 4k | ✅ | ✅ | ❌ | | | `kling-o1` | std / pro | ✅ | ❌ | ❌ | Solo soporta `duration=5` | Notas: * `mode=4k` solo es soportado por `kling-v3` y `kling-v3-omni`; y es excluyente con `camera_control` (control de cámara). * `end_image_url` solo puede usarse con `action=image2video` junto con `start_image_url`. Solo enviar `end_image_url` (sin `start_image_url`) será rechazado. * `kling-v3` / `kling-v3-omni` aceptan cualquier `duration` entero de 3 a 15 segundos; `kling-o1` solo acepta 5; los demás modelos solo aceptan 5 o 10. * `generate_audio` por defecto es `false`. Solo `kling-v3`, `kling-v3-omni` y `kling-v2-6` (modo pro) lo soportan. ## Función de extensión de video Si deseas continuar generando un video Kling que ya ha sido creado, puedes establecer el parámetro `action` como `extend`, e ingresar el ID del video que deseas continuar generando. El ID del video se obtiene según el uso básico, como se muestra en la imagen a continuación:

En este momento, puedes ver que el ID del video es: ``` "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c" ``` > Nota: el `video_id` aquí es el ID del video generado. Si no sabes cómo generar un video, puedes consultar el uso básico mencionado anteriormente. A continuación, debemos completar los siguientes pasos con las palabras clave que necesitamos para personalizar la generación del video, especificando el siguiente contenido: * `model`: el modelo para generar el video, principalmente `kling-v1`, `kling-v1-5` y `kling-v1-6`. * `mode`: el modo para generar el video, los valores opcionales son modo estándar `std`, modo rápido `pro` y modo nativo 4K `4k` (solo soportado por `kling-v3` y `kling-v3-omni`, no compatible con control de cámara). * `duration`: la duración del video para esta tarea de generación, principalmente 5s y 10s. * `start_image_url`: cuando se elige la acción de imagen a video `image2video`, es necesario subir el enlace de la imagen de referencia del primer fotograma. * `prompt`: palabras clave. Ejemplo de llenado:

Una vez completado, se generará automáticamente el siguiente código:

Código correspondiente en Python: ```python theme={null} import requests url = "https://api.acedata.cloud/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": "Taza de café de cerámica blanca sobre una encimera de mármol brillante con luz de ventana de la mañana. La cámara rota lentamente 360 grados alrededor de la taza, deteniéndose brevemente en el asa.", "duration": 10 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Al hacer clic en ejecutar, se puede observar que se obtiene un resultado como el siguiente: ```json theme={null} { "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" } ``` Se puede ver que el contenido del resultado es consistente con lo mencionado anteriormente, lo que también logra la función de extensión de video. ## Referencia Omni (edición de video / video de referencia / referencia de múltiples imágenes) `kling-o1` y `kling-v3-omni` son dos modelos independientes, ambos soportan la capacidad de "referencia omnidireccional". En la generación de video a partir de texto (`action=text2video`), se pueden pasar imágenes de referencia o videos de referencia adicionales, logrando **referencia de múltiples imágenes, video de referencia y edición directa de videos existentes**. **Convenio central**: El material de referencia debe ser citado en `prompt` en la forma `<<>>`, `<<>>` (numeración comenzando desde 1) para que el modelo aplique estas referencias. Si solo se envía el material sin citarlo en las palabras clave, el material será ignorado. > Nota de seguridad: La API actual no abre `element_list`. El ID de la biblioteca de elementos de Kling pertenece al espacio de nombres de la cuenta del proveedor, y antes de proporcionar la API de gestión de elementos con aislamiento de inquilinos, los clientes deben usar `image_list` para pasar la imagen de referencia principal. Las solicitudes Omni no soportan `negative_prompt`, `cfg_scale` o `camera_control`, y no se puede usar `mode=4k`. Cuando se incluye un video de referencia, `generate_audio` debe ser `false`. ### Video de referencia y edición de video (`video_list`) `video_list` se utiliza para pasar videos de referencia, es el escenario más común de esta capacidad, los campos de los elementos del arreglo son los siguientes: * `video_url`: enlace del video de referencia, no puede estar vacío. Requisitos: formato MP4/MOV; resolución 720px–2160px; duración 3–10 segundos; tasa de cuadros 24–60fps; tamaño del archivo ≤200MB; máximo 1 video. * `refer_type`: tipo de referencia, puede ser `base` (por defecto, **video base a editar**, es decir, "editar directamente el video", se pueden agregar/eliminar/modificar elementos, cambiar la composición, cambiar el estilo, cambiar el color, cambiar el clima, etc.) o `feature` (**referencia de características**, referencia de su estilo / movimiento de cámara / continuación de la siguiente toma). * `keep_original_sound`: si se debe conservar el audio original del video, puede ser `yes` (conservar) o `no` (eliminar). > Nota: Si hay un video de referencia, `generate_audio` debe ser `false`. Los videos con `refer_type=base` no pueden especificar el primer cuadro / último cuadro. Ejemplo de CURL para editar un video existente (cambiar el estilo del video a anime): ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Cambia <<>> a un estilo de anime de nivel cinematográfico, conservando el movimiento y la composición originales", "video_list": [ { "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4", "refer_type": "base", "keep_original_sound": "no" } ] }' ``` ### Referencia de múltiples imágenes (`image_list`) `image_list` se utiliza para pasar imágenes de referencia (elementos / escenas / estilos, etc.), los campos de los elementos del arreglo son los siguientes: * `image_url`: enlace de la imagen de referencia, no puede estar vacío. Requisitos: formato .jpg/.jpeg/.png; tamaño del archivo ≤10MB; lado más corto ≥300px; relación de aspecto 1:2.5 \~ 2.5:1. * `type`: opcional. Si no se pasa, se considera como imagen de referencia pura; si se pasa `first_frame` / `end_frame`, se considera como primer cuadro / último cuadro (equivalente a `start_image_url` / `end_image_url`). Al usarlo, se debe referenciar en `prompt` como `<<>>`, `<<>>`. Límite de cantidad: si no hay video de referencia, las imágenes de referencia ≤ 7; si hay video de referencia, las imágenes de referencia ≤ 4. Si solo se pasan el primer / último cuadro, también se puede usar directamente `start_image_url` / `end_image_url`, pero el último cuadro debe usarse junto con el primer cuadro. > Nota: Si se pasan simultáneamente `start_image_url` / `end_image_url` y `image_list`, el primer / último cuadro se colocará antes de `image_list`, lo que puede afectar la relación de correspondencia de los números de `<<>>`. Se recomienda elegir uno: si se necesitan el primer / último cuadro, se debe especificar directamente en `image_list` usando `type`, no mezclar con `start_image_url` / `end_image_url`. Ejemplo de CURL para generar un video con referencia de múltiples imágenes: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Haz que los personajes de <<>> estén en la escena de <<>>, con iluminación cinematográfica", "image_list": [ { "image_url": "https://cdn.acedata.cloud/subject.png" }, { "image_url": "https://cdn.acedata.cloud/scene.png" } ] }' ``` ## Callback asíncrono Debido a que el tiempo de generación de la API de Kling Videos es relativamente largo, aproximadamente 1-2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión, lo que provocará un consumo adicional de recursos del sistema, por lo que esta API también ofrece soporte para callbacks asíncronos. El flujo general es: cuando el cliente inicia la solicitud, se especifica un campo adicional `callback_url`, después de que el cliente inicia la solicitud de API, la API devolverá inmediatamente un resultado que incluye un campo `task_id`, que representa el ID de la tarea actual. Cuando la tarea se complete, el resultado del video generado se enviará a la `callback_url` especificada por el cliente en formato JSON POST, que también incluirá el campo `task_id`, de modo que el resultado de la tarea se pueda asociar mediante el ID. A continuación, entenderemos cómo operar específicamente a través de un ejemplo. Primero, el callback de Webhook es un servicio que puede recibir solicitudes HTTP, el desarrollador debe reemplazarlo con la URL de su propio servidor HTTP. Aquí, para facilitar la demostración, se utiliza un sitio de muestra de Webhook público [https://webhook.site/](https://webhook.site/), al abrir este sitio se obtiene una URL de Webhook, como se muestra en la imagen: ![](https://cdn.acedata.cloud/tbcnai.png) Copie esta URL y podrá usarla como Webhook, el ejemplo aquí es `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`. A continuación, podemos establecer el campo `callback_url` como la URL de Webhook anterior, al mismo tiempo que llenamos los parámetros correspondientes, el contenido específico se muestra en la imagen:

Al hacer clic en ejecutar, se puede observar que se obtiene inmediatamente un resultado, como se muestra a continuación: ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` Después de un momento, podemos observar el resultado del video generado en `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`, como se muestra en la imagen: ![](https://cdn.acedata.cloud/zv5u2q.png) El contenido es el siguiente: ```json theme={null} { "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" } ``` Se puede ver que en el resultado hay un campo `task_id`, los otros campos son similares a los mencionados anteriormente, a través de este campo se puede realizar la asociación de la tarea. ## Manejo de errores Al llamar a la API, si se encuentra un error, la API devolverá el código de error correspondiente y la información. Por ejemplo: * `400 token_mismatched`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos. * `400 api_not_implemented`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos. * `401 invalid_token`: No autorizado, token de autorización inválido o faltante. * `429 too_many_requests`: Demasiadas solicitudes, ha superado el límite de tasa. * `500 api_error`: Error interno del servidor, algo salió mal en el servidor. ### Ejemplo de respuesta de error ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "la recuperación falló" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusión A través de este documento, usted ha aprendido cómo utilizar la API de Generación de Videos de Kling, que permite generar videos mediante la entrada de palabras clave y una imagen de referencia del primer fotograma. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.