Guía de integración de Kling Videos Generation API

Este artículo presentará una guía de integración de Kling Videos Generation API, que permite generar los videos oficiales de Kling mediante la introducción de parámetros personalizados.

Proceso de solicitud

Para usar Kling Videos Generation API, primero obtenga su API Token en la consola de Ace Data Cloud y resérvelo para uso posterior.

Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; una vez completado, volverá automáticamente a la página actual. Un API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud otorgará una cuota gratuita para probarlo sin costo; cuando la cuota sea insuficiente, puede recargar saldo general en la consola.

📘 Documentación completa: Kling Videos Generation API →

Uso básico

Primero comprendamos el método básico de uso: introduciendo el texto de indicación prompt, la acción de generación action, la imagen de referencia del primer fotograma start_image_url y el modelo model, se puede obtener el resultado procesado. Primero se debe pasar simplemente un campo action, cuyo valor es text2video; incluye principalmente tres acciones: texto a video (text2video), imagen a video (image2video) y extender video (extend). Luego también necesitamos introducir el modelo model; actualmente los modelos principales son 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; el contenido específico es el siguiente:

Se puede ver que aquí configuramos los Request Headers, incluyendo:

accept: qué formato de resultado de respuesta se desea recibir; aquí se completa como application/json, es decir, formato JSON.
authorization: la clave para invocar la API, que se puede seleccionar directamente desde la lista desplegable después de solicitarla.

Además, configuramos el Request Body, incluyendo:

model: el modelo para generar videos; los modelos principales son 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 para generar videos; los valores opcionales son modo estándar std, modo ultrarrápido pro y modo nativo 4K 4k. Entre ellos, 4k solo es compatible con kling-v3 y kling-v3-omni, y no es compatible con camera_control (control de movimiento de cámara).
action: la acción de esta tarea de generación de video; incluye principalmente tres acciones, que son: texto a video (text2video), imagen a video (image2video) y extender video (extend).
start_image_url: el enlace de la imagen de referencia del primer fotograma que debe cargarse al seleccionar la acción de imagen a video image2video.
end_image_url: opcional al usar imagen a video, 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; los demás modelos admiten 5 o 10 segundos.
generate_audio: si se genera audio de forma sincronizada, opcional, valor booleano. Compatible con kling-v3, kling-v3-omni y kling-v2-6 (solo modo pro). El valor predeterminado es false.
aspect_ratio: relación de aspecto del video, opcional, admite 16:9, 9:16, 1:1, el valor predeterminado es 16:9.
cfg_scale: intensidad de relevancia, rango [0,1]; cuanto mayor sea, más se ajustará al texto de indicación.
camera_control: opcional, parámetro de objeto que controla el movimiento de la cámara, admite preajustes type/simple y configuraciones como horizontal, vertical, pan, tilt, roll, zoom, entre otras.
negative_prompt: opcional, texto de indicación negativo que no se desea que aparezca, con un máximo de 200 caracteres.
image_list: lista de imágenes de referencia Omni, aplicable a los modelos kling-o1 y kling-v3-omni; consulte «Referencia universal Omni» más abajo para el uso.
video_list: lista de videos de referencia Omni (admite edición de video), aplicable a los modelos kling-o1 y kling-v3-omni; consulte «Referencia universal Omni» más abajo para el uso.
prompt: texto de indicación.
callback_url: URL donde se requiere recibir el resultado de la devolución de llamada.
async: opcional; cuando se establece en true, la interfaz devuelve inmediatamente task_id, sin necesidad de proporcionar callback_url; posteriormente, obtenga el resultado mediante sondeo a través de la interfaz de consulta de tareas correspondiente.

Después de seleccionar, se puede descubrir que también se genera el código correspondiente en el lado derecho, como se muestra en la imagen:

Haga clic en el botón «Try» para realizar una prueba; como se muestra en la imagen anterior, aquí obtuvimos el siguiente resultado:

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

El resultado devuelto tiene múltiples campos, que se presentan a continuación:

success, la situación del estado de la tarea de generación de video en este momento.
task_id, el ID de la tarea de generación de video en este momento.
video_id, el ID del video de la tarea de generación de video en este momento.
video_url, el enlace del video de la tarea de generación de video en este momento.
duration, la duración del enlace del video de la tarea de generación de video en este momento.
state, el estado de la tarea de generación de video en este momento.

Se puede ver que obtuvimos información satisfactoria del video; solo necesitamos obtener el video Kling generado según la dirección del enlace de video de data en el resultado. Además, si desea generar el código de integración correspondiente, puede copiarlo directamente; por ejemplo, el código CURL es el siguiente:

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": "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

Los distintos modelos difieren considerablemente en su compatibilidad con los parámetros. La siguiente matriz está recopilada de la documentación oficial de Kling sobre video models; antes de invocar, verifique primero si la combinación actual de model / mode / duration admite la función que necesita; de lo contrario, se devolverán errores como model/mode/duration(...) is not supported with image_tail.

Modelo	Modo	`end_image_url` (fotogramas inicial y final)	`generate_audio` (audio de acompañamiento)	`camera_control` (movimiento de cámara)	Notas
`kling-v1`	std / pro	✅ Solo `duration=5`	❌	✅ Solo `duration=5`	`extend` no admite `negative_prompt` ni `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	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	✅	✅	❌	El único modelo no v3 que admite audio de acompañamiento simultáneamente
`kling-v3`	std / pro	✅	✅	✅	Rango de `duration` de 3–15 segundos
`kling-v3`	4k	✅	✅	❌	El modo 4K es incompatible con el movimiento de cámara
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-o1`	std / pro	✅	❌	❌	Solo admite `duration=5`

Consideraciones:

mode=4k solo es compatible con kling-v3 y kling-v3-omni; además, es mutuamente excluyente con camera_control (movimiento de cámara).
end_image_url solo puede utilizarse junto con start_image_url cuando action=image2video. Enviar solo end_image_url (sin start_image_url) será rechazado.
kling-v3 / kling-v3-omni aceptan cualquier duration entero de 3–15 segundos; kling-o1 solo acepta 5; los demás modelos solo aceptan 5 o 10.
generate_audio es false de forma predeterminada. Solo kling-v3, kling-v3-omni y kling-v2-6 (modo pro) son compatibles.

Función de extensión de video

Si desea continuar generando un video Kling ya generado, puede establecer el parámetro action como extend e introducir el ID del video que necesita continuar generándose. La obtención del ID del video se basa en el uso básico, como se muestra en la siguiente imagen:

En este momento puede ver que el ID del video es:

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

Tenga en cuenta que aquí el video_id en el video es el ID del video generado. Si no sabe cómo generar un video, puede consultar el uso básico anterior para generar un video.

A continuación, debemos completar las palabras clave que se necesitan extender en el siguiente paso para personalizar el video generado, y se puede especificar el siguiente contenido:

model: el modelo para generar el video, principalmente los modelos kling-v1, kling-v1-5 y kling-v1-6.
mode: el modo para generar el video, los valores opcionales son el modo estándar std, el modo ultrarrápido pro y el modo 4K nativo 4k (solo compatible con kling-v3 y kling-v3-omni, incompatible con el control de movimiento de cámara).
duration: la duración del video de esta tarea de generación de video, que incluye principalmente 5s y 10s.
start_image_url: al elegir el comportamiento de generación de video a partir de imagen image2video, se debe proporcionar el enlace de la imagen de referencia del fotograma inicial que se necesita cargar.
prompt: palabras clave.

El ejemplo de llenado es el siguiente:

Después de completar, se genera automáticamente el siguiente código:

El código Python correspondiente:

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": "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)

Haga clic en ejecutar y podrá observar que se obtiene un resultado, como se muestra a continuación:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Se puede observar que el contenido del resultado es consistente con el anterior, logrando así la función de extensión de video.

Referencia integral 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 compatibles con la capacidad de «referencia integral». Sobre la base de video a partir de texto (action=text2video), se pueden introducir adicionalmente imágenes de referencia o videos de referencia, para lograr referencia de múltiples imágenes, videos de referencia y edición directa de videos existentes. Convención principal: los materiales de referencia deben citar los materiales en las posiciones correspondientes de image_list / video_list en el prompt en la forma <<<image_1>>>, <<<video_1>>> (la numeración comienza en 1), para que el modelo aplique estas referencias. Si solo se envían materiales sin citarlos en las palabras clave, los materiales serán ignorados.

Nota de seguridad: la API actual no ofrece element_list. Los ID de Kling Element Library no están aislados por inquilino; antes de proporcionar una Element Management API con aislamiento por inquilino, utilice image_list para enviar imágenes de referencia del sujeto.

Las solicitudes Omni no admiten negative_prompt, cfg_scale ni camera_control, y tampoco pueden utilizar mode=4k. Cuando se incluyen videos de referencia, generate_audio debe ser false. video_list se utiliza para pasar videos de referencia y es el escenario más común de esta capacidad; los campos de los elementos del array son los siguientes:

video_url: enlace del video de referencia, no puede estar vacío. Como máximo 1 video MP4/MOV, tamaño de archivo ≤200MB, tasa de fotogramas 24–60fps. kling-o1 requiere una duración de 3–10 segundos, y ancho y alto de 700–2160px cada uno; kling-v3-omni requiere una duración de 3–15.5 segundos, ancho y alto de 700–4553px cada uno, píxeles totales ≤8,294,400 y relación de aspecto 0.4–2.
refer_type: tipo de referencia, puede ser base (predeterminado, video base que se va a editar, es decir, “editar directamente el video”, permite añadir/eliminar/modificar elementos, cambiar la composición, cambiar el estilo, cambiar los colores, cambiar el clima, etc.) o feature (referencia de características, consulta su estilo / movimiento de cámara / continuación de la siguiente toma).
keep_original_sound: si se conserva el audio del video original; puede ser yes (conservar) o no (eliminar).

Nota: cuando existe un video de referencia, generate_audio debe ser false. No se pueden especificar fotograma inicial / fotograma final para el video con refer_type=base.

El ejemplo de CURL para editar un video existente (cambiar el video a estilo anime) es el siguiente:

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": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "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 array son los siguientes:

image_url: enlace de la imagen de referencia, no puede estar vacío. Requisitos: formato .jpg/.jpeg/.png; tamaño de archivo ≤10MB; lado más corto ≥300px; relación de aspecto 1:2.5 ~ 2.5:1.
type: opcional. Si no se proporciona, se utiliza como imagen de referencia pura; cuando se proporciona first_frame / end_frame, se utiliza respectivamente como fotograma inicial / fotograma final (equivalente a start_image_url / end_image_url).

Al utilizarlo, se debe hacer referencia en prompt con <<<image_1>>>, <<<image_2>>>. Límite de cantidad: cuando no existe un video de referencia, las imágenes de referencia ≤ 7; cuando existe un video de referencia, las imágenes de referencia ≤ 4. Cuando solo se pasan fotogramas inicial / final, también se puede utilizar directamente start_image_url / end_image_url, pero el fotograma final debe utilizarse junto con el fotograma inicial.

Nota: si se pasan simultáneamente start_image_url / end_image_url e image_list, los fotogramas inicial / final se colocarán antes de image_list, lo que puede afectar la correspondencia de numeración de <<<image_N>>>. Se recomienda elegir uno de los dos: cuando se necesiten fotogramas inicial / final, especifíquelos directamente mediante type en image_list, y no los mezcle con start_image_url / end_image_url.

Ejemplo de CURL para generar un video con referencia de múltiples imágenes:

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": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

Devolución de llamada asíncrona

Dado que la API de Kling Videos Generation tarda relativamente mucho tiempo en generar resultados, aproximadamente 1-2 minutos, si la API no responde durante mucho tiempo, la solicitud HTTP mantendrá la conexión abierta continuamente, lo que provocará un consumo adicional de recursos del sistema; por lo tanto, esta API también ofrece soporte para devoluciones de llamada asíncronas. El flujo general es: cuando el cliente inicia una solicitud, especifica adicionalmente un campo 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, el cual representa el ID de la tarea actual. Cuando la tarea se complete, el resultado del video generado se enviará mediante POST JSON a la callback_url especificada por el cliente, incluyendo también el campo task_id, de modo que el resultado de la tarea pueda asociarse mediante el ID. A continuación, veamos mediante un ejemplo cómo operar específicamente. Primero, la devolución de llamada Webhook es un servicio que puede recibir solicitudes HTTP; el desarrollador debe reemplazarla con la URL de un servidor HTTP creado por sí mismo. Para facilitar la demostración, aquí se utiliza un sitio web público de ejemplo de Webhook, https://webhook.site/; al abrir este sitio web se puede obtener una URL de Webhook, como se muestra en la imagen:

Copie esta URL para poder utilizarla 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 y, al mismo tiempo, completar los parámetros correspondientes; el contenido específico se muestra en la imagen:

Haga clic en ejecutar y verá que se obtiene inmediatamente un resultado, como se muestra a continuación:

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Espere un momento; podremos observar el resultado del video generado en https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, como se muestra en la imagen:

El contenido es el siguiente:

{
  "success": true,
  "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Se puede ver que hay un campo task_id en el resultado; los demás campos son similares a los anteriores, y la asociación de tareas puede realizarse mediante este campo.

Manejo de errores

Al llamar a la API, si se encuentra un error, la API devolverá el código y la información de error correspondientes. Por ejemplo:

400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o no válidos.
400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o no válidos.
401 invalid_token: No autorizado, token de autorización no válido o faltante.
429 too_many_requests: Demasiadas solicitudes, ha excedido el límite de frecuencia.
500 api_error: Error interno del servidor, algo salió mal 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

A través de este documento, ya ha comprendido cómo usar Kling Videos Generation API para generar videos mediante la entrada de palabras clave y una imagen de referencia del primer fotograma. Esperamos que este documento pueda ayudarle a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.

Kling 3.0 Turbo

model="kling-v3-turbo" admite video a partir de texto y video a partir de una imagen del primer fotograma, con una duración entera de 3–15 segundos. mode="std" genera 720p, mode="pro" genera 1080p. Este modelo incluye audio nativo y no proporciona un interruptor para desactivarlo; omita generate_audio o establézcalo en true. Este modelo no admite el último fotograma, objetos de movimiento de cámara, indicaciones negativas independientes ni cfg_scale. Describa directamente en prompt el contenido que necesita o que desea evitar que aparezca.

Video de múltiples tomas

kling-v3 y kling-v3-omni admiten multi_shot=true. shot_type="intelligence" divide automáticamente las tomas según prompt; shot_type="customize" proporciona 1–6 tomas mediante multi_prompt, donde cada elemento incluye un index que aumenta consecutivamente desde 1, un prompt de hasta 512 caracteres y una duration entera de al menos 1 segundo. La suma de las duraciones de todas las tomas debe ser igual a la duration total. Las tomas personalizadas no utilizan el prompt global. Las múltiples tomas se cobran según el modelo seleccionado, la calidad de imagen, la configuración de audio y la duración total.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Guía de integración de Kling Videos Generation API

Proceso de solicitud

Uso básico

Matriz de capacidades de modelos

Función de extensión de video

Referencia integral Omni (edición de video / video de referencia / referencia de múltiples imágenes)

Referencia de múltiples imágenes (`image_list`)

Devolución de llamada asíncrona

Manejo de errores

Ejemplo de respuesta de error

Conclusión

Kling 3.0 Turbo

Video de múltiples tomas

​Proceso de solicitud

​Uso básico

​Matriz de capacidades de modelos

​Función de extensión de video

​Referencia integral Omni (edición de video / video de referencia / referencia de múltiples imágenes)

​Video de referencia y edición de video (video_list)

​Referencia de múltiples imágenes (image_list)

​Devolución de llamada asíncrona

​Manejo de errores

​Ejemplo de respuesta de error

​Conclusión

​Kling 3.0 Turbo

​Video de múltiples tomas

Proceso de solicitud

Uso básico

Matriz de capacidades de modelos

Función de extensión de video

Referencia integral Omni (edición de video / video de referencia / referencia de múltiples imágenes)

Video de referencia y edición de video (`video_list`)

Referencia de múltiples imágenes (`image_list`)

Devolución de llamada asíncrona

Manejo de errores

Ejemplo de respuesta de error

Conclusión

Kling 3.0 Turbo

Video de múltiples tomas