> ## 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 & 3.0 Omni

Los parámetros y el uso están alineados con los oficiales. Para más detalle, consulta directamente la documentación oficial.

## 1. Descripción general

Este documento explica cómo usar las capacidades de texto a video, imagen a video, video Omni y control de movimiento mediante el protocolo original de Kling 3.0.

Las cuatro capacidades utilizan el modo de tareas asíncronas:

1. Llama a la interfaz de creación correspondiente.
2. Guarda el `data.id` de la respuesta de creación.
3. Consulta el estado de la tarea usando la misma API Key que se usó al crear la tarea.
4. Cuando la tarea se complete correctamente, obtén y guarda el video generado desde `outputs`.

### 1.1 Direcciones de las interfaces

| Capacidad | Crear tarea | Consultar tarea |
| - | - | - |
| Texto a video | `POST /v3/kling/text-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Imagen a video | `POST /v3/kling/image-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Video Omni | `POST /v3/kling/omni-video/kling-3.0-omni` | `GET /v3/kling/tasks` |
| Control de movimiento | `POST /v3/kling/motion-control/kling-3.0` | `GET /v3/kling/tasks` |

En los ejemplos de este documento, la dirección completa es `https://{api_domain}` más la ruta de la interfaz que aparece en la tabla, donde `{api_domain}` es el dominio de API que utilizas.

### 1.2 Autenticación

Todas las solicitudes deben incluir la API Key. Las solicitudes POST también deben especificar el tipo de contenido JSON:

```
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

### 1.3 Estructura de la respuesta

En la respuesta de creación, `data` es un objeto con los siguientes campos habituales:

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | ID de tarea generado por el sistema Kling, utilizado para consultas posteriores |
| `external_id` | string | Eco de `options.external_task_id`; puede no devolverse si no se ha establecido |
| `status` | string | Estado de la tarea después de la creación, normalmente `submitted` |

En la respuesta de consulta, `data` es una matriz; cada tarea contiene los siguientes campos:

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | ID de tarea generado por el sistema |
| `external_id` | string | ID de tarea personalizado por el solicitante (si existe) |
| `status` | string | `submitted`, `processing`, `succeeded` o `failed` |
| `message` | string | Información del estado de la tarea; si falla, incluye el motivo del fallo (si existe) |
| `create_time` | integer | Tiempo de creación, marca de tiempo Unix en milisegundos (si existe) |
| `update_time` | integer | Tiempo de actualización, marca de tiempo Unix en milisegundos (si existe) |
| `outputs` | array | Resultados generados; una tarea exitosa normalmente incluye un resultado con `type=video` |

En `outputs`, los campos habituales del resultado de video son `type`, `id`, `url`, `watermark_url` y `duration`. `url` es la dirección del resultado sin marca de agua, `watermark_url` es la dirección con marca de agua y `duration` es la duración del video (segundos).

## 2. Texto a video

Parámetros oficiales: Text to Video

### 2.1 Crear tarea

```
POST https://{api_domain}/v3/kling/text-to-video/kling-3.0
```

Campos habituales de la solicitud:

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `prompt` | string | Sí | Prompt de generación de video, no puede estar vacío, máximo 3072 caracteres |
| `settings.multi_shot` | boolean | No | Si se genera un video multi-shot, por defecto `true` |
| `settings.resolution` | string | No | `720p`, `1080p` o `4k`, por defecto `720p` |
| `settings.aspect_ratio` | string | No | `16:9`, `9:16` o `1:1`, por defecto `16:9` |
| `settings.audio` | string | No | `off` o `native`, por defecto `off` |
| `settings.duration` | integer | No | 3–15 segundos, por defecto 5 segundos |
| `options.callback_url` | string | No | Dirección para recibir notificaciones de callback cuando cambia el estado de la tarea |
| `options.external_task_id` | string | No | ID de tarea personalizado |
| `options.watermark_info.enabled` | boolean | No | Si se genera un resultado con marca de agua, por defecto `false` |

Cuando `multi_shot=true`, puedes describir los múltiples planos en el prompt siguiendo el formato oficial de Kling; la suma de las duraciones de cada plano debe ser igual a la duración total del video.

### 2.2 Ejemplo de creación

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -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",
      "duration": 5,
      "audio": "native"
    },
    "options": {
      "external_task_id": "text-video-20260826-0001"
    }
  }'
```

Cuando la creación se completa correctamente, se devuelve el ID de tarea:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-text-task-id",
    "external_id": "text-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 2.3 Consultar tarea

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

Guarda el `data.id`. Si no se envía `options.external_task_id`, es posible que `data.external_id` no se devuelva.

Utiliza la misma API Key que se usó al crear la tarea. Si el ID de tarea no existe o no es accesible, se devolverá `task not found`.

También puedes usar `external_task_ids` para consultar IDs de tarea personalizados:

```
GET https://{api_domain}/v3/kling/tasks?external_task_ids={external_task_id}
```

`task_ids` y `external_task_ids` son mutuamente excluyentes: debes completar uno y solo uno. Ambos admiten de 1 a 50 IDs separados por comas en inglés; en la respuesta, `data` es una matriz y mantiene el orden de los IDs solicitados.

### 2.4 Ejemplo de consulta

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-text-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

Cuando la tarea se completa correctamente, se devuelve:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-text-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/text-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

`status=processing` indica que la tarea todavía se está ejecutando; se recomienda consultar cada 10–30 segundos. `status=failed` indica que la tarea falló y no se debe continuar sondeando. Una vez que la tarea se complete correctamente, guarda a tiempo el archivo correspondiente a `outputs[type=video].url`, ya que la dirección de descarga puede tener validez limitada.

### 2.5 Facturación

```
Costo de la tarea = precio por segundo del nivel de resolución y audio correspondiente × settings.duration
```

El nivel de precio lo determinan `settings.resolution` y `settings.audio`. Por ejemplo, con `1080p`, `audio=native`, `duration=5`, el costo es “precio por segundo del nivel de audio nativo 1080p × 5 segundos”. Si no se envía `duration`, se factura por los 5 segundos predeterminados.

Al crear la tarea se descuenta el costo 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 utilices.

## 3. Imagen a video

Parámetros oficiales: Image to Video

### 3.1 Crear tarea

```
POST https://{api_domain}/v3/kling/image-to-video/kling-3.0
```

Campos habituales de la solicitud:

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `contents` | array | Sí | Lista de contenido multimodal, al menos un elemento |
| `contents[].type` | string | Sí | `prompt`, `first_frame`, `last_frame` o `element` |
| `settings.resolution` | string | No | `720p`, `1080p` o `4k`, por defecto `720p` |
| `settings.multi_shot` | boolean | No | Si se genera un video multi-shot, por defecto `true` |
| `settings.audio` | string | No | `off` o `native`, por defecto `off` |
| `settings.duration` | integer | No | 3–15 segundos, por defecto 5 segundos |
| `options.callback_url` | string | No | Dirección para recibir notificaciones de callback cuando cambia el estado de la tarea |
| `options.external_task_id` | string | No | ID de tarea personalizado |
| `options.watermark_info.enabled` | boolean | No | Si se genera un resultado con marca de agua, por defecto `false` |

Campos de los subelementos de `contents`:

| type | Campos obligatorios | Descripción |
| - | - | - |
| `prompt` | `text` | Prompt de texto, máximo 3072 caracteres |
| `first_frame` | `url` | Imagen del primer fotograma; admite URL o Base64; es obligatoria |
| `last_frame` | `url` | Imagen del último fotograma; admite URL o Base64; no se admite solo el último fotograma, debe proporcionarse también el primero |
| `element` | `element_id`, `id` | ID del sujeto e ID de índice con el que se referencia al sujeto en el prompt; dentro de la misma tarea, `id` no debe repetirse; se admite especificar como máximo 3 sujetos |

Las imágenes admiten `.jpg`, `.jpeg` y `.png`, con un tamaño máximo de 50 MB, ancho y alto de al menos 300 píxeles y una relación de aspecto entre 1:2.5 y 2.5:1.

### 3.2 Ejemplo de creación

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -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,
      "audio": "off"
    },
    "options": {
      "external_task_id": "image-video-20260826-0001"
    }
  }'
```

Cuando la creación se completa correctamente, `data.id` es el ID de tarea que se usará en consultas posteriores:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-image-task-id",
    "external_id": "image-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 3.3 Consultar tarea

Consulta la tarea usando el `data.id` de la respuesta de creación:

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

Al consultar mediante `task_ids`, utiliza la misma API Key que se usó al crear la tarea. También puedes consultar mediante `external_task_ids` el `options.external_task_id` enviado en la creación. 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-image-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

Cuando la tarea se completa correctamente, la dirección del video se encuentra en `outputs[type=video].url`:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-image-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/image-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

Si `status=processing`, se recomienda seguir consultando cada 10–30 segundos; si `status=failed`, detén el sondeo y corrige la entrada según el mensaje de error.

### 3.5 Facturación

```
Costo de la tarea = precio por segundo del nivel de resolución y audio correspondiente × settings.duration
```

El nivel de precio lo determinan `settings.resolution` y `settings.audio`. Si no se envía `duration`, se factura por los 5 segundos predeterminados. Al crear la tarea se descuenta el costo 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 utilices.

## 4. Video Omni

Parámetros oficiales: Omni Video

### 4.1 Crear tarea

```
POST https://{api_domain}/v3/kling/omni-video/kling-3.0-omni
```

Campos habituales de la solicitud:

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `contents` | array | Sí | Lista de contenido multimodal, al menos un elemento |
| `contents[].type` | string | Sí | `prompt`, `first_frame`, `last_frame`, `refer_image`, `feature_video`, `base_video` o `element` |
| `settings.resolution` | string | No | `720p`, `1080p` o `4k`, por defecto `720p` |
| `settings.multi_shot` | boolean | No | Si se genera un video multi-shot, por defecto `true` |
| `settings.aspect_ratio` | string | No | `16:9`, `9:16` o `1:1`, por defecto `16:9`; es obligatorio si no hay imagen de primer fotograma ni video de referencia |
| `settings.audio` | string | No | `off`, `native` o `original`, por defecto `off` |
| `settings.duration` | integer | No | 3–15 segundos, por defecto 5 segundos |
| `options.callback_url` | string | No | Dirección para recibir notificaciones de callback cuando cambia el estado de la tarea |
| `options.external_task_id` | string | No | ID de tarea personalizado |
| `options.watermark_info.enabled` | boolean | No | Si se genera un resultado con marca de agua, por defecto `false` |

Campos de los subelementos de `contents`:

| type | Campos obligatorios | Descripción |
| - | - | - |
| `prompt` | `text` | Prompt |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.