> ## Documentation Index > Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling 3.0 Turbo Los parámetros y la forma de uso están alineados con los oficiales. Para los parámetros detallados, consulte directamente la documentación oficial. ## 1. Resumen Este documento explica cómo utilizar las capacidades de texto a vídeo y de imagen a vídeo mediante el protocolo original de Kling 3.0 Turbo. Turbo utiliza el mismo protocolo original que el Kling 3.0 estándar; las estructuras de solicitud y respuesta son idénticas, y solo difieren en el alcance de las capacidades, los niveles de resolución y la facturación. Ambas capacidades utilizan un modo de tareas asíncronas: 1. Llame a la interfaz de creación correspondiente. 2. Guarde el `data.id` de la respuesta de creación. 3. Utilice la misma API Key con la que creó la tarea para consultar el estado de la tarea. 4. Una vez que la tarea se completa correctamente, obtenga y guarde el vídeo generado desde `outputs`. ### 1.1 Dirección de la API | Capacidad | Crear tarea | Consultar tarea | | - | - | - | | Texto a vídeo | `POST /v3/kling/text-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | | Imagen a vídeo | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | La dirección completa en los ejemplos de este documento es `https://{api_domain}` más la ruta de la interfaz de la tabla, donde `{api_domain}` es el dominio de API que usted utiliza. Turbo solo ofrece texto a vídeo e imagen a vídeo; no admite vídeo Omni ni control de movimiento. ### 1.2 Autenticación Todas las solicitudes deben incluir una API Key. Las solicitudes POST también deben especificar el tipo de contenido JSON: ``` Authorization: Bearer Content-Type: application/json ``` ### 1.3 Estructura de la respuesta En la respuesta de creación, `data` es un objeto. Los campos habituales son `id` (el ID de tarea generado por el sistema de Kling, que se utiliza para consultas posteriores), `external_id` (el eco de `options.external_task_id`, que puede no devolverse si no se ha establecido) y `status` (el estado de la tarea después de la creación, normalmente `submitted`). En la respuesta de consulta, `data` es una matriz. Cada tarea contiene `id`, `external_id`, `status` (`submitted`, `processing`, `succeeded` o `failed`), `message`, `create_time`, `update_time` y `outputs`. Los campos habituales de los resultados de vídeo en `outputs` son `type`, `id`, `url`, `watermark_url` y `duration`, donde `url` es la dirección de resultados sin marca de agua, `watermark_url` es la dirección de resultados con marca de agua y `duration` es la duración del vídeo (en segundos). ## 2. Texto a vídeo ### 2.1 Crear tarea ``` POST https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo ``` Campos de la solicitud: | Campo | Tipo | Obligatorio | Valor predeterminado / Rango de valores | Descripción | | - | - | - | - | - | | `prompt` | string | Sí | | Prompt de texto que puede incluir descripciones positivas y negativas; límite de 3072 caracteres, se recomienda no superar los 2500 caracteres | | `settings.resolution` | string | No | Predeterminado `720p`; `720p`, `1080p` | Resolución del vídeo generado | | `settings.aspect_ratio` | string | No | Predeterminado `16:9`; `16:9`, `9:16`, `1:1` | Relación de aspecto del vídeo generado (ancho:alto) | | `settings.duration` | int | No | Predeterminado 5; entero entre 3 y 15 | Duración del vídeo generado, en segundos | | `options.callback_url` | string | No | | Dirección que recibe las notificaciones de devolución de llamada cuando cambia el estado de la tarea | | `options.external_task_id` | string | No | | ID de tarea personalizado; no sobrescribe el ID de tarea del sistema, se puede utilizar para consultas, debe ser único para cada usuario | | `options.watermark_info.enabled` | boolean | No | Predeterminado `false` | Indica si se genera un resultado con marca de agua | El vídeo de múltiples planos se implementa mediante un formato fijo en `prompt`: "Plano n, m, words; Plano n, m, words;" (separados por símbolos de ancho medio). Donde n es el número de orden del plano (máximo 6, mínimo 1), m es la duración del plano (cada uno no menor que 1, y la suma de todas las duraciones de los planos es igual a la duración total del vídeo), y words es el prompt del plano (máximo 512 caracteres). ### 2.2 Ejemplo de creación ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A cinematic tracking shot of a red sports car driving along a coastal road at sunset", "settings": { "resolution": "1080p", "aspect_ratio": "16:9", "duration": 5 }, "options": { "external_task_id": "turbo-text-20260826-0001" } }' ``` Si la creación se realiza correctamente, se devuelve el ID de tarea: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-text-task-id", "external_id": "turbo-text-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` Guarde `data.id`. Si no se envía `options.external_task_id`, es posible que `data.external_id` no se devuelva. ### 2.3 Consultar tarea ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Utilice la misma API Key con la que creó la tarea. También puede utilizar `external_task_ids` para consultar el ID de tarea personalizado. En cada consulta debe rellenarse solo uno de `task_ids` o `external_task_ids`. Ambos admiten de 1 a 50 IDs separados por comas en inglés. En la respuesta, `data` es un array y conserva el orden de los IDs de la solicitud. ### 2.4 Ejemplo de consulta ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-text-task-id' \ -H 'Authorization: Bearer ' ``` Cuando la tarea se completa correctamente, se devuelve: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-text-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-text.mp4", "duration": 5 } ] } ] } ``` `status=processing` indica que la tarea todavía está en ejecución; se recomienda consultar cada 10 a 30 segundos. `status=failed` indica que la tarea ha fallado y no debe seguir consultando. Cuando la tarea se completa correctamente, guarde rápidamente el archivo correspondiente a `outputs[type=video].url`; la dirección de descarga puede tener una validez limitada. ### 2.5 Facturación ``` 任务费用 = 对应分辨率的每秒单价 × settings.duration ``` El nivel de precio viene determinado únicamente por `settings.resolution` (`720p` o `1080p`). Si no se envía `duration`, la facturación se realiza por los 5 segundos predeterminados. Al crear la tarea, se cobra según la duración solicitada; si la creación de la tarea falla o la generación final falla, el cargo se reembolsa automáticamente. El precio unitario específico se rige por la página de precios del servicio que utilice. ## 3. Imagen a vídeo ### 3.1 Crear tarea ``` POST https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo ``` Campos de la solicitud: | Campo | Tipo | Obligatorio | Valor predeterminado / Rango de valores | Descripción | | - | - | - | - | - | | `contents` | array | Sí | | Colección de materiales de referencia; debe contener al menos un elemento | | `contents[].type` | string | Sí | `prompt`, `first_frame` | Tipo de material: prompt o primer fotograma | | `contents[].text` | string | No | | Prompt de texto cuando `type=prompt`; máximo 2500 caracteres | | `contents[].url` | string | No | | Imagen del primer fotograma cuando `type=first_frame`; admite URL o Base64 | | `settings.resolution` | string | No | Predeterminado `720p`; `720p`, `1080p` | Resolución del vídeo generado | | `settings.duration` | int | No | Predeterminado 5; entero entre 3 y 15 | Duración del vídeo generado, en segundos | | `options.external_task_id` | string | No | | ID de tarea personalizado; no sobrescribe el ID de tarea del sistema, se puede utilizar para consultas, debe ser único para cada usuario | | `options.watermark_info.enabled` | boolean | No | Predeterminado `false` | Indica si se genera un resultado con marca de agua | Las imágenes admiten `.jpg`, `.jpeg` y `.png`. El archivo no debe superar los 50 MB, el ancho y la altura no deben ser inferiores a 300 píxeles, y la relación de aspecto debe estar entre 1:2.5 y 2.5:1. La función de imagen a vídeo solo admite el primer fotograma; por ahora no se admiten "primer fotograma + último fotograma" ni "solo último fotograma". `options.callback_url` también se puede enviar; su uso es igual que en texto a vídeo. Los múltiples planos también se realizan mediante el formato fijo del `prompt`. ### 3.2 Ejemplo de creación ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ { "type": "prompt", "text": "The subject turns toward the camera while the wind moves naturally through the scene" }, { "type": "first_frame", "url": "https://your-cdn.example.com/first-frame.png" } ], "settings": { "resolution": "1080p", "duration": 5 }, "options": { "external_task_id": "turbo-image-20260826-0001" } }' ``` Si la creación se realiza correctamente, devuelve: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-image-task-id", "external_id": "turbo-image-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` ### 3.3 Consultar tarea Consulte la tarea utilizando `data.id` de la respuesta de creación: ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` Al consultar mediante `task_ids`, utilice la misma API Key con la que creó la tarea. También puede consultar el `options.external_task_id` enviado en la creación mediante `external_task_ids`. El parámetro de consulta admite de 1 a 50 IDs separados por comas en inglés. ### 3.4 Ejemplo de consulta ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-image-task-id' \ -H 'Authorization: Bearer ' ``` Cuando la tarea se completa correctamente, la dirección del vídeo se encuentra en `outputs[type=video].url`: ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-image-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-image.mp4", "duration": 5 } ] } ] } ``` Cuando `status=processing`, se recomienda seguir consultando cada 10 a 30 segundos; cuando `status=failed`, detenga las consultas y corrija los datos de entrada según el mensaje de error. ### 3.5 Facturación ``` 任务费用 = 对应分辨率的每秒单价 × settings.duration ``` El nivel de precio viene determinado únicamente por `settings.resolution` (`720p` o `1080p`). Si no se envía `duration`, la facturación se realiza por los 5 segundos predeterminados. Al crear la tarea, se cobra según la duración solicitada; si la creación de la tarea falla o la generación final falla, el cargo se reembolsa automáticamente. El precio unitario específico se rige por la página de precios del servicio que utilice. ## 4. Errores comunes y notas Los errores de la interfaz utilizan la siguiente estructura: ```json theme={null} { "code": 1203, "message": "task not found (trace_id: platform-trace-id)", "request_id": "", "data": null } ``` Códigos de estado habituales: 400/1200 (los parámetros o el tipo de contenido no son válidos; corríjalos según `message`), 401/1000 (la API Key falta o no es válida), 403/1103 (sin permiso para realizar la operación), 404/1203 (la tarea no existe o no tiene permiso para consultarla), 429/1302 (demasiadas solicitudes; reduzca la frecuencia y aplique retroceso exponencial), 500/5000, 503/5001, 504/5002 (servicio anómalo o tiempo de espera superado; reintente más tarde y evite enviar solicitudes duplicadas sin control). Si `message` contiene `trace_id`, facilítelo también cuando contacte con el soporte técnico. Otras notas: * El cuerpo de la solicitud no necesita añadir `model` ni `model_name`; la versión del modelo ya está incluida en la URL. * Después de crear la tarea, persista `data.id`; no utilice `request_id` como ID de tarea. * El cuerpo de una sola solicitud tiene un máximo de 64 MB; para imágenes grandes, se recomienda utilizar una URL pública de Kling que sea accesible desde Internet. * Las URL de los materiales de entrada deben ser accesibles públicamente para Kling; no deben depender de redes internas, cookies ni estados de inicio de sesión temporales. * Utilice un intervalo de sondeo de 10 a 30 segundos y establezca un tiempo de espera general y retroceso exponencial. * Un tiempo de espera agotado en una solicitud POST no significa necesariamente que la tarea no se haya creado; consulte primero con `external_task_id` y después decida si reintentar. * Una vez recibido el estado de éxito, guarde inmediatamente el archivo correspondiente a `outputs[type=video].url`; la URL de los resultados puede caducar. ## 5. Ejemplo de llamada en Python El siguiente ejemplo utiliza la librería estándar `requests` y muestra la creación y consulta de texto a vídeo. Para imagen a vídeo, solo necesita sustituir la interfaz de creación y el cuerpo de la solicitud. ```python theme={null} import os import time import requests api_domain = os.environ["API_DOMAIN"] api_key = os.environ["PLATFORM_API_KEY"] ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.