> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling 系列

> 使用 AIOAGI Kling 视频任务接口调用图生视频和 Omni 视频能力。

Kling 系列通过 AIOAGI 视频任务接口调用。图生视频使用 `POST /videos/image2video`，Omni 视频使用 `POST /videos/omni-video`。任务创建后，你需要使用对应的 `GET` 接口轮询任务结果。

<Warning>
  Kling 模型名称、价格、时长、模式、音频支持和任务状态字段可能变化。生产调用前，请在 **控制台**、`GET /models` 或 **开发者指南** 中核对当前可用模型。
</Warning>

## 接口概览

| 能力         | 接口                              | 方法     | 说明                     |
| ---------- | ------------------------------- | ------ | ---------------------- |
| 图生视频任务     | `/videos/image2video`           | `POST` | 基于首帧图片和提示词创建视频任务。      |
| 查询图生视频     | `/videos/image2video/{task_id}` | `GET`  | 查询图生视频任务状态和结果。         |
| Omni 视频任务  | `/videos/omni-video`            | `POST` | 基于图片、视频和元素参考创建多模态视频任务。 |
| 查询 Omni 视频 | `/videos/omni-video/{task_id}`  | `GET`  | 查询 Omni 视频任务状态和结果。     |

## 图生视频示例

```bash theme={null}
export AIO_API_KEY="sk-your-api-key"
export AIO_BASE_URL="https://api.aiearth.dev/v1"

curl "$AIO_BASE_URL/videos/image2video" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image": "https://example.com/source-image.jpg",
    "prompt": "让画面中的产品在柔和灯光下缓慢旋转，镜头轻微推进，突出金属质感和高级商业广告风格。",
    "mode": "std",
    "duration": "5",
    "sound": "on"
  }'
```

提交成功后，响应通常包含 `task_id`。请保存该 ID，用于后续查询。

## 查询图生视频结果

```bash theme={null}
curl "$AIO_BASE_URL/videos/image2video/{task_id}" \
  -H "Authorization: Bearer $AIO_API_KEY"
```

任务状态常见值包括 `submitted`、`processing`、`succeed` 和 `failed`。不同线路也可能返回 `queued`、`running`、`succeeded` 或 `completed`。

## Omni 视频示例

Omni 视频支持多图输入 `image_list`。你可以在 `prompt` 中使用 `<<<image_1>>>`、`<<<image_2>>>` 引用对应图片。

```bash theme={null}
curl "$AIO_BASE_URL/videos/omni-video" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3-omni",
    "prompt": "让 <<<image_1>>> 中的人物走到 <<<image_2>>> 的展台前，镜头从中景缓慢推进，整体保持科技发布会风格。",
    "image_list": [
      {
        "image_url": "https://example.com/person.jpg"
      },
      {
        "image_url": "https://example.com/stage.jpg"
      }
    ],
    "duration": "5",
    "mode": "std",
    "aspect_ratio": "16:9",
    "callback_url": "",
    "external_task_id": ""
  }'
```

## 查询 Omni 视频结果

```bash theme={null}
curl "$AIO_BASE_URL/videos/omni-video/{task_id}" \
  -H "Authorization: Bearer $AIO_API_KEY"
```

成功后，视频 URL 可能出现在 `data.task_result.videos[]`、`output.video_url`、`output.watermark_video_url`、`metadata.url` 或兼容字段中。请以实际响应结构为准，并在服务端记录原始响应。

## 核心参数

| 参数                 | 类型                  | 说明                                              |
| ------------------ | ------------------- | ----------------------------------------------- |
| `model_name`       | `string`            | 必填。Kling 模型 ID，例如 `kling-v3` 或 `kling-v3-omni`。 |
| `prompt`           | `string`            | 必填。描述视频动作、镜头、风格和约束。Omni 视频可引用素材占位符。             |
| `image`            | `string`            | 图生视频首帧图片。支持公网 URL 或 Base64。                     |
| `image_list`       | `array`             | Omni 视频参考图片列表。常见结构为 `{ "image_url": "..." }`。   |
| `video_list`       | `array`             | Omni 视频参考视频列表。可用于基础视频、动作或声音参考。                  |
| `mode`             | `string`            | 常见值为 `std` 或 `pro`。实际支持范围以控制台和开发者指南为准。          |
| `duration`         | `string` 或 `number` | 常见值为 `5` 或 `10` 秒。实际支持范围以模型为准。                  |
| `aspect_ratio`     | `string`            | Omni 视频画幅。常见值包括 `16:9`、`9:16`、`1:1`。            |
| `sound`            | `string`            | 图生视频音效开关。常见值为 `on` 或 `off`。                     |
| `negative_prompt`  | `string`            | 可选。描述不希望出现的内容。                                  |
| `cfg_scale`        | `number`            | 可选。提示词贴合程度。实际范围以当前模型为准。                         |
| `callback_url`     | `string`            | 可选。任务完成回调地址。                                    |
| `external_task_id` | `string`            | 可选。业务侧自定义任务 ID。                                 |

## Python 轮询示例

下面的示例展示如何轮询图生视频任务。Omni 视频只需要把查询路径改为 `/videos/omni-video/{task_id}`。

```python theme={null}
import os
import time
import requests

api_key = os.environ["AIO_API_KEY"]
base_url = os.environ.get("AIO_BASE_URL", "https://api.aiearth.dev/v1")
task_id = "task_xxx"

headers = {"Authorization": f"Bearer {api_key}"}

while True:
    response = requests.get(
        f"{base_url}/videos/image2video/{task_id}",
        headers=headers,
        timeout=60,
    )
    response.raise_for_status()
    data = response.json()
    status = (
        data.get("data", {}).get("task_status")
        or data.get("output", {}).get("task_status")
        or data.get("status")
    )
    print("status:", status)

    if status in {"succeed", "succeeded", "completed"}:
        print(data)
        break
    if status in {"failed", "failure", "canceled", "cancelled"}:
        raise RuntimeError(data)

    time.sleep(5)
```

## 排障建议

* 遇到 `401`，检查 API Key 和 `Authorization` 请求头。
* 遇到 `403`，检查账户余额、Token 组额度和模型权限。
* 遇到 `404`，核对 base URL、接口路径、模型名和 `task_id`。
* 遇到 `429`，降低提交并发和轮询频率，并加入指数退避。
* 任务成功但没有解析到 URL 时，保存原始响应，检查 `data`、`output`、`metadata` 中的视频字段。