> ## 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.
# Instrucciones para la integración de la API Kling Videos Generation
> Kling video generation 集成指南 - XHuoAPI
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](https://api.xhuoapi.ai/documents/3b921a16-a411-4557-8335-53f21d3f9e46). 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](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z)).
* `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:
```json theme={null}
{
"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:
```shell theme={null}
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](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels). 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`.
| Modelo | Mode | `end_image_url` | `generate_audio` | `camera_control` | Notas |
| ------------------- | -------------- | ------------------- | ---------------- | ------------------- | ---------------------------------------------------- |
| `kling-v1` | std / pro | ✅ solo `duration=5` | ❌ | ✅ solo `duration=5` | `extend` no soporta `negative_prompt` ni `cfg_scale` |
| `kling-v1-6` | std | ❌ | ❌ | ❌ | compatible con multi-imagen y modo `extend` |
| `kling-v1-6` | pro | ✅ | ❌ | ❌ | |
| `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-turbo` | std | ❌ | ❌ | ❌ | |
| `kling-v2-5-turbo` | pro | ✅ | ❌ | ❌ | |
| `kling-v2-6` | std | ❌ | ❌ | ❌ | |
| `kling-v2-6` | pro | ✅ | ✅ | ❌ | único modelo no v3 que soporta audio simultáneo |
| `kling-v3` | std / pro | ✅ | ✅ | ✅ | `duration` de 3–15 segundos |
| `kling-v3` | 4k | ✅ | ✅ | ❌ | modo 4K no compatible con control de cámara |
| `kling-v3-omni` | std / pro / 4k | ✅ | ✅ | ❌ | |
| `kling-video-o1` | std / 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:
```python theme={null}
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:
```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"
}
```
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/](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:
```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"
}
```
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:
```json theme={null}
{
"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.