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

# 多模态视频编辑

> 接口与可灵官网一致；支持视频选区管理和元素增删改

* 与官网一致：本页所有请求体、字段命名与返回结构与可灵官网保持一致
* 字段详解：请参考[官网权威文档](https://klingai.kuaishou.com/docs)

多模态视频编辑是一个多步骤的工作流：

1. **初始化视频** → 获取 session\_id
2. **选区管理** → 增加/删减/清除/预览选区
3. **提交编辑任务** → 执行增加/替换/删除元素

## 1. 初始化待编辑视频

`POST /kling/v1/videos/multi-elements/init-selection`

| 参数          | 类型     | 必填  | 说明                     |
| ----------- | ------ | --- | ---------------------- |
| `video_id`  | string | 二选一 | 视频ID（与 video\_url 二选一） |
| `video_url` | string | 二选一 | 视频URL（与 video\_id 二选一） |

```bash theme={null}
curl --request POST \
  --url https://models.hingnet.com.cn/kling/v1/videos/multi-elements/init-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://example.com/video-to-edit.mp4"
  }'
```

响应

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "status": 0,
    "session_id": "sess_abc123...",
    "fps": 30.0,
    "original_duration": 5,
    "width": 1920,
    "height": 1080,
    "total_frame": 150,
    "normalized_video": "https://..."
  }
}
```

## 2. 增加视频选区

`POST /kling/v1/videos/multi-elements/add-selection`

| 参数            | 类型     | 必填    | 说明             |
| ------------- | ------ | ----- | -------------- |
| `session_id`  | string | **是** | 会话ID（24小时有效）   |
| `frame_index` | int    | **是** | 帧号             |
| `points`      | array  | **是** | 点选坐标列表（最多10个点） |

```bash theme={null}
curl --request POST \
  --url https://models.hingnet.com.cn/kling/v1/videos/multi-elements/add-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "sess_abc123...",
    "frame_index": 0,
    "points": [
      {"x": 0.5, "y": 0.5}
    ]
  }'
```

> **坐标范围**：x 和 y 均在 \[0, 1] 范围内

## 3. 删减视频选区

`POST /kling/v1/videos/multi-elements/delete-selection`

参数与增加选区相同，用于删除已选中的区域。

## 4. 清除视频选区

`POST /kling/v1/videos/multi-elements/clear-selection`

| 参数           | 类型     | 必填    | 说明   |
| ------------ | ------ | ----- | ---- |
| `session_id` | string | **是** | 会话ID |

## 5. 预览已选区视频

`POST /kling/v1/videos/multi-elements/preview-selection`

| 参数           | 类型     | 必填    | 说明   |
| ------------ | ------ | ----- | ---- |
| `session_id` | string | **是** | 会话ID |

返回带 mask 标记的预览视频和封面。

## 6. 创建编辑任务

`POST /kling/v1/videos/multi-elements`

| 参数                 | 类型     | 必填    | 说明                               |
| ------------------ | ------ | ----- | -------------------------------- |
| `model_name`       | string | 否     | 模型名称，仅支持 `kling-v1-6`            |
| `session_id`       | string | **是** | 会话ID                             |
| `edit_mode`        | string | **是** | 操作类型：`addition`、`swap`、`removal` |
| `image_list`       | array  | 条件    | 参考图像列表（增加需1-2张，替换需1张，删除不需要）      |
| `prompt`           | string | **是** | 正向文本提示词                          |
| `negative_prompt`  | string | 否     | 负向文本提示词                          |
| `mode`             | string | 否     | 生成模式：`std`、`pro`，默认 `std`        |
| `duration`         | string | 否     | 视频时长：`5`、`10`，默认 `5`             |
| `callback_url`     | string | 否     | 回调通知地址                           |
| `external_task_id` | string | 否     | 自定义任务ID                          |

编辑模式说明

| edit\_mode | 说明   | 图片要求   |
| ---------- | ---- | ------ |
| `addition` | 增加元素 | 1-2张图片 |
| `swap`     | 替换元素 | 1张图片   |
| `removal`  | 删除元素 | 不需要图片  |

补充约束

* `model_name` 仅支持 `kling-v1-6`；
* `session_id` 有效期 24 小时；
* `duration` 仅支持 `5`/`10`；
* 选区坐标 `x/y` 取值范围 `[0,1]`。

### 场景：替换视频中的人物

```bash theme={null}
curl --request POST \
  --url https://models.hingnet.com.cn/kling/v1/videos/multi-elements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1-6",
    "session_id": "sess_abc123...",
    "edit_mode": "swap",
    "image_list": [
      {"image": "https://example.com/new-character.jpg"}
    ],
    "prompt": "Replace the selected person with the new character",
    "mode": "std",
    "duration": "5"
  }'
```

## 7. 查询编辑任务

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/videos/multi-elements/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/videos/multi-elements?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

任务成功响应

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "task_01JGHR...",
    "task_status": "succeed",
    "session_id": "sess_abc123...",
    "task_result": {
      "videos": [
        {
          "id": "vid_123",
          "session_id": "sess_abc123...",
          "url": "https://...",
          "duration": "5"
        }
      ]
    }
  }
}
```