# Kling/v3

Kling v3 系列视频生成模型，统一使用 `kling-v3` 模型 ID，根据入参自动路由到下列三种生成模式：

- **文生视频（t2v）**：仅传 `prompt`
- **图生视频（i2v）**：传入参考图（首帧或首尾帧）
- **运动控制（motion_control）**：同时传入参考图与参考视频，由参考视频驱动角色运动

也可以通过 `parameters.kling_v3_type` 显式指定模式，详见下方"模式选择"。

## 模式选择

服务端按以下优先级判定本次请求走哪种模式：

1. `parameters.kling_v3_type` 显式指定时优先生效，可选值：`t2v` / `i2v` / `motion_control`
2. 未显式指定时按入参隐式推导：
   - `input.video_url` 非空 → `motion_control`
   - 存在任一首帧图字段（`parameters.image` / `input.images` / `input.first_frame_url` / `input.img_url`）→ `i2v`
   - 否则 → `t2v`

> 推荐生产环境直接传 `kling_v3_type` 显式指定，避免未来字段语义变化导致的隐式路由偏差。

## 异步提交任务

### 接口

`https://api.modelverse.cn/v1/tasks/submit`

### 输入

#### 通用参数

| 参数                         | 类型    | 是否必选 | 描述                                                                                                                                                                                                                                                    |
| :--------------------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| model                        | string  | 是       | 模型名称，统一为 `kling-v3`                                                                                                                                                                                                                              |
| parameters.kling_v3_type     | string  | 否       | 显式指定生成模式，可选值：`t2v`、`i2v`、`motion_control`。不传则按入参隐式推导                                                                                                                                                                            |
| input.prompt                 | string  | 条件必选 | 提示词，最多 2500 字符。`t2v` / `i2v` 模式下当 `multi_shot` 为 `false` 时必填；`motion_control` 模式下可选                                                                                                                                                |
| input.negative_prompt        | string  | 否       | 反向提示词，最多 2500 字符                                                                                                                                                                                                                               |
| parameters.mode              | string  | 否       | 生成模式。`std`：标准模式（720P）；`pro`：专业模式（1080P）。默认 `std`                                                                                                                                                                                  |
| parameters.aspect_ratio      | string  | 否       | 视频长宽比，可选值：`16:9`、`9:16`、`1:1`。默认 `16:9`。`i2v` 模式下忽略此参数，以输入图片的宽高比为准                                                                                                                                                    |
| parameters.duration          | int     | 否       | 视频时长（秒）。`t2v` / `i2v` 模式可选 `3` ~ `15`；`motion_control` 模式可选 `5`、`10`。默认 `5`                                                                                                                                                          |
| parameters.watermark_enabled | bool    | 否       | 是否生成带水印的结果                                                                                                                                                                                                                                     |
| parameters.external_task_id  | string  | 否       | 自定义任务 ID，不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。请确保单用户下唯一                                                                                                                                                                   |

#### 文生视频 / 图生视频 模式专属参数（`t2v` / `i2v`）

| 参数                         | 类型    | 是否必选 | 描述                                                                                                                                                                                                                                                    |
| :--------------------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| parameters.image             | string  | 条件必选 | 参考图像（首帧），`i2v` 模式下必填，`t2v` 模式下不传。支持图片 Base64 编码或图片 URL（确保可访问）。<br/>Base64 编码时请勿添加 `data:image/png;base64,` 等前缀，直接传入编码字符串即可。<br/>- 图片格式支持 `.jpg`、`.jpeg`、`.png`<br/>- 文件大小不超过 10MB<br/>- 宽高尺寸不小于 300px，宽高比介于 1:2.5 ~ 2.5:1 之间 |
| parameters.image_tail        | string  | 否       | 视频尾帧图片，传入后同时控制首尾帧。需配合 `image` 一起使用。支持 URL 或 Base64 编码，格式要求参照 `image` 参数                                                                                                                                           |
| parameters.sound             | string  | 否       | 是否生成声音，可选值：`on`、`off`，默认 `off`                                                                                                                                                                                                            |
| parameters.multi_shot        | bool    | 否       | 是否启用多镜头模式，默认 `false`。<br/>为 `true` 时 `prompt` 无效；为 `false` 时 `shot_type` 和 `multi_prompt` 无效                                                                                                                                      |
| parameters.shot_type         | string  | 条件必选 | 镜头类型，当 `multi_shot` 为 `true` 时必填，可选值：`customize`                                                                                                                                                                                          |
| parameters.multi_prompt      | array   | 条件必选 | 多镜头提示词列表，当 `multi_shot` 为 `true` 且 `shot_type` 为 `customize` 时不能为空。<br/>最少 1 个镜头，最多 6 个；每个镜头内容不超过 512 字符；每个镜头时长不小于 1 秒且不大于总时长；所有镜头时长之和需等于总时长。<br/>每项包含：<br/>- `index`：镜头序号，从 1 开始（int）<br/>- `prompt`：该镜头提示词（string）<br/>- `duration`：该镜头时长（string） |

#### 运动控制 模式专属参数（`motion_control`）

| 参数                             | 类型   | 是否必选 | 描述                                                                                                                                                                                                                       |
| :------------------------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| input.img_url                    | string | 是       | 参考图片，支持图片 Base64 编码或图片 URL（确保可访问）。<br/>- 图片格式支持 `.jpg`、`.png`<br/>- 文件大小不超过 10MB<br/>- 宽高尺寸介于 300px ~ 65536px 之间<br/>- 宽高比介于 1:2.5 ~ 2.5:1 之间                              |
| input.video_url                  | string | 是       | 参考视频 URL，支持 MP4、MOV 格式。<br/>- 文件大小不超过 100MB<br/>- 宽高尺寸介于 340px ~ 3850px 之间<br/>- 视频时长不少于 3 秒；横向视频不超过 30 秒，竖向视频不超过 10 秒                                                    |
| parameters.character_orientation | string | 是       | 角色朝向，决定角色面朝方向。可选值：`image`（朝向与参考图一致）、`video`（朝向与参考视频一致）                                                                                                                              |
| parameters.keep_original_sound   | string | 否       | 是否保留参考视频原声，可选值：`yes`、`no`，默认 `yes`                                                                                                                                                                       |

### 请求示例

⚠️ 如果您使用 Windows 系统，建议使用 Postman 或其他 API 调用工具。

**文生视频（`t2v`，不传 `image`）：**

```shell
curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "input": {
      "prompt": "A beautiful sunset over the ocean with waves gently crashing"
    },
    "parameters": {
      "kling_v3_type": "t2v",
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "sound": "on"
    }
  }'
```

**图生视频（`i2v`，传入 `image` 作为首帧）：**

```shell
curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "input": {
      "prompt": "The image comes to life with gentle movement"
    },
    "parameters": {
      "kling_v3_type": "i2v",
      "mode": "pro",
      "duration": 5,
      "image": "https://example.com/first_frame.jpg"
    }
  }'
```

**首尾帧控制（`i2v`，同时传入 `image` 和 `image_tail`）：**

```shell
curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "input": {
      "prompt": "A girl walking through a garden"
    },
    "parameters": {
      "kling_v3_type": "i2v",
      "mode": "pro",
      "duration": 5,
      "image": "https://example.com/first_frame.jpg",
      "image_tail": "https://example.com/last_frame.jpg"
    }
  }'
```

**多镜头生成（`t2v`）：**

```shell
curl --location --globoff 'https://api.modelverse.cn/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "parameters": {
      "kling_v3_type": "t2v",
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "multi_shot": true,
      "shot_type": "customize",
      "multi_prompt": [
        {"index": 1, "prompt": "A person walking through a misty forest at dawn", "duration": "2"},
        {"index": 2, "prompt": "A car speeding down a rainy street, headlights glowing", "duration": "3"}
      ],
      "sound": "on"
    }
  }'
```

**运动控制（`motion_control`，参考图 + 参考视频）：**

```shell
curl -X POST 'https://api.modelverse.cn/v1/tasks/submit' \
-H 'Authorization: <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "model": "kling-v3",
    "input": {
      "img_url": "https://example.com/character.jpg",
      "video_url": "https://example.com/motion_reference.mp4",
      "prompt": "A person dancing gracefully"
    },
    "parameters": {
      "kling_v3_type": "motion_control",
      "duration": 5,
      "aspect_ratio": "16:9",
      "character_orientation": "image",
      "mode": "std"
    }
  }'
```

### 输出

| 参数           | 类型   | 描述               |
| :------------- | :----- | :----------------- |
| output.task_id | string | 异步任务的唯一标识 |
| request_id     | string | 请求的唯一标识     |

### 响应示例

```json
{
  "output": {
    "task_id": "task_id"
  },
  "request_id": "request_id"
}
```

## 查询任务状态

### 接口

`https://api.modelverse.cn/v1/tasks/status?task_id=<task_id>`

### 请求示例

```shell
curl --location 'https://api.modelverse.cn/v1/tasks/status?task_id=<task_id>' \
--header 'Authorization: <YOUR_API_KEY>'
```

### 输出

| 参数                 | 类型    | 描述                                              |
| :------------------- | :------ | :------------------------------------------------ |
| output.task_id       | string  | 异步任务的唯一标识                                |
| output.task_status   | string  | 任务状态：`Pending`、`Running`、`Success`、`Failure` |
| output.urls          | array   | 视频结果的 URL 列表                               |
| output.submit_time   | integer | 任务提交时间戳                                    |
| output.finish_time   | integer | 任务完成时间戳                                    |
| output.error_message | string  | 失败时返回的错误信息                              |
| usage.duration       | integer | 视频时长（秒）                                    |
| request_id           | string  | 请求的唯一标识                                    |

### 响应示例（成功）

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Success",
    "urls": ["https://xxxxx/xxxx.mp4"],
    "submit_time": 1756959000,
    "finish_time": 1756959050
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}
```

### 响应示例（失败）

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Failure",
    "submit_time": 1756959000,
    "finish_time": 1756959019,
    "error_message": "error_message"
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}
```

## 错误码

| 错误码    | 描述         |
| :-------- | :----------- |
| 006001094 | 任务资源不足 |
| 006001095 | 任务响应错误 |
| 006001099 | 任务创建错误 |