> ## 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.

# 图生视频

> 接口与可灵官网一致；支持首帧驱动、动态笔刷、运镜控制

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

请求参数

| 参数                 | 类型     | 必填    | 说明                                                                                                                                                         |
| ------------------ | ------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model_name`       | string | 否     | 模型名称，默认 `kling-v1`。可选：`kling-v1`、`kling-v1-5`、`kling-v1-6`、`kling-v2-master`、`kling-v2-1`、`kling-v2-1-master`、`kling-v2-5`、`kling-v2-5-turbo`、`kling-v2-6` |
| `image`            | string | **是** | 首帧图片 URL 或 Base64                                                                                                                                          |
| `image_tail`       | string | 否     | 尾帧图片 URL 或 Base64                                                                                                                                          |
| `prompt`           | string | 否     | 文本提示词                                                                                                                                                      |
| `negative_prompt`  | string | 否     | 负向文本提示词                                                                                                                                                    |
| `voice_list`       | array  | 否     | 语音列表（仅 `kling-v2-6` 支持，最多2个）                                                                                                                               |
| `sound`            | string | 否     | 是否生成声音：`on`/`off`（仅 `kling-v2-6` 支持）                                                                                                                       |
| `cfg_scale`        | number | 否     | 生成自由度 \[0, 1]，仅 `kling-v1`/`kling-v1-5`/`kling-v1-6` 支持                                                                                                    |
| `mode`             | string | 否     | 生成模式：`std`、`pro`，默认 `std`                                                                                                                                  |
| `static_mask`      | string | 否     | 静态笔刷涂抹区域                                                                                                                                                   |
| `dynamic_masks`    | array  | 否     | 动态笔刷配置列表（最多6组）                                                                                                                                             |
| `camera_control`   | object | 否     | 摄像机运动控制                                                                                                                                                    |
| `aspect_ratio`     | string | 否     | 画面纵横比：`16:9`、`9:16`、`1:1`，默认 `16:9`                                                                                                                        |
| `duration`         | string | 否     | 视频时长：`5`、`10`，默认 `5`                                                                                                                                       |
| `watermark_info`   | object | 否     | 是否生成含水印结果                                                                                                                                                  |
| `callback_url`     | string | 否     | 回调通知地址                                                                                                                                                     |
| `external_task_id` | string | 否     | 自定义任务ID                                                                                                                                                    |

> **重要约束**
>
> * `image` 必填，`image_tail` 可选；
> * `image + image_tail`、`dynamic_masks/static_mask`、`camera_control` 三组选一，互斥不可同时使用；
> * `voice_list` 仅 `kling-v2-6` 支持，且使用时 `sound=on`、最多 2 个。

动态笔刷配置

```json theme={null}
{
  "dynamic_masks": [
    {
      "mask": "base64编码的掩码图片",
      "trajectories": [
        {"x": 100, "y": 200},
        {"x": 150, "y": 250}
      ]
    }
  ]
}
```

* `trajectories`：运动轨迹坐标序列，以输入图片左下为原点的像素坐标，至少2个点，最多77个点
* `dynamic_masks` 最多 6 组；`static_mask` 与 `dynamic_masks.mask` 分辨率需与 `image` 一致，否则上游可能失败

### 场景一：首帧驱动

```bash theme={null}
curl --request POST \
  --url https://models.hingnet.com.cn/kling/v1/videos/image2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1",
    "image": "https://example.com/first-frame.jpg",
    "prompt": "A mouse runs toward the camera, smiling and blinking",
    "mode": "std",
    "duration": "5",
    "aspect_ratio": "16:9"
  }'
```

### 场景二：首帧 + 尾帧

```bash theme={null}
curl --request POST \
  --url https://models.hingnet.com.cn/kling/v1/videos/image2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1",
    "image": "https://example.com/child.jpg",
    "image_tail": "https://example.com/adult.jpg",
    "prompt": "A little girl grows up",
    "mode": "pro",
    "duration": "10",
    "aspect_ratio": "16:9"
  }'
```

### 场景三：使用摄像机运镜

```bash theme={null}
curl --request POST \
  --url https://models.hingnet.com.cn/kling/v1/videos/image2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-master",
    "image": "https://example.com/landscape.jpg",
    "prompt": "Camera slowly zooms in on the mountain peak",
    "camera_control": {
      "type": "simple",
      "config": {
        "zoom": 5
      }
    },
    "duration": "10",
    "aspect_ratio": "16:9"
  }'
```

示例响应

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "req_1735558800_xyz789",
  "data": {
    "task_id": "task_01JGHM...",
    "task_status": "submitted",
    "created_at": 1735558800000,
    "updated_at": 1735558800000
  }
}
```