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

# Kling 4.0

> 通过 AnyFast API 调用 Kling 4.0 文生视频、图生视频、全能参考和视频编辑能力。

Kling 4.0 通过 AnyFast API 生成或编辑视频，支持文本描述、关键帧图片，以及图片和视频参考。Kling 4.0 使用新版接口：模型名称直接写在请求路径中，输出配置放在 `settings`，通用选项放在 `options`。

> [!NOTE]
>
> 使用本文列出的 `/kling/v2/.../kling-4.0` 创建接口。请求体不需要填写 `model` 或 `model_name`。不要混用 Kling Legacy 接口中的 `mode: "std"`、顶层字符串 `duration`、`multi_prompt` 等参数。

## 核心能力

* **文生视频** — 使用提示词描述场景、人物、动作、镜头和声音。
* **图生视频** — 使用 `contents` 提交提示词和首帧、中间帧或尾帧图片。
* **全能参考生成** — 组合提示词、参考图片和参考视频，并通过素材 `id` 在提示词中指定用途。
* **视频编辑** — 使用全能参考接口提交 `base_video`，并描述需要修改和保留的内容。
* **异步任务查询** — 使用创建响应中的系统任务 ID 查询状态和生成结果。

| 能力 | 创建接口 | 主要输入 |
| - | - | - |
| 文生视频 | `POST /kling/v2/text-to-video/kling-4.0` | `prompt` |
| 图生视频 | `POST /kling/v2/image-to-video/kling-4.0` | `contents` 中的提示词和关键帧图片 |
| 全能参考生成 | `POST /kling/v2/omni-video/kling-4.0` | 提示词、参考图片和参考视频 |
| 视频编辑 | `POST /kling/v2/omni-video/kling-4.0` | 提示词和 `base_video` |

## 接入地址与鉴权

基础地址为 `https://www.anyfast.ai`。请求头如下：

```http theme={null}
Authorization: Bearer YOUR_ANYFAST_API_KEY
Content-Type: application/json
```

将 `YOUR_ANYFAST_API_KEY` 替换为具备该模型调用权限的 AnyFast API Key。

## 快速示例

```bash cURL — 文生视频 theme={null}
curl --request POST \
  --url 'https://www.anyfast.ai/kling/v2/text-to-video/kling-4.0' \
  --header 'Authorization: Bearer YOUR_ANYFAST_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "雨后的街道，一辆红色汽车缓慢驶过，镜头向右平移。写实风格，真实雨声，不要字幕，不要突然切镜头。",
    "settings": {
      "resolution": "720p",
      "aspect_ratio": "21:9",
      "duration": 3
    },
    "options": {
      "watermark_info": {
        "enabled": false
      }
    }
  }'
```

```bash cURL — 图生视频 theme={null}
curl --request POST \
  --url 'https://www.anyfast.ai/kling/v2/image-to-video/kling-4.0' \
  --header 'Authorization: Bearer YOUR_ANYFAST_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "type": "prompt",
        "text": "从@start开始，保持人物身份和构图。人物微笑抬手，微风吹动头发，有自然风声。连续单镜头，不要字幕。"
      },
      {
        "type": "first_frame",
        "url": "https://example.com/first-frame.jpg",
        "id": "start"
      }
    ],
    "settings": {
      "resolution": "720p",
      "duration": 3
    },
    "options": {
      "watermark_info": {
        "enabled": false
      }
    }
  }'
```

```bash cURL — 全能参考生成 theme={null}
curl --request POST \
  --url 'https://www.anyfast.ai/kling/v2/omni-video/kling-4.0' \
  --header 'Authorization: Bearer YOUR_ANYFAST_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "type": "prompt",
        "text": "保持@actor中人物的面容、发型和服装，参考@motion中的动作节奏。人物在明亮的训练场自然活动，镜头平稳，不要字幕。"
      },
      {
        "type": "refer_image",
        "url": "https://example.com/character.jpg",
        "id": "actor"
      },
      {
        "type": "feature_video",
        "url": "https://example.com/motion.mp4",
        "id": "motion"
      }
    ],
    "settings": {
      "resolution": "720p",
      "aspect_ratio": "1:1",
      "duration": 3
    },
    "options": {
      "watermark_info": {
        "enabled": false
      }
    }
  }'
```

```bash cURL — 视频编辑 theme={null}
curl --request POST \
  --url 'https://www.anyfast.ai/kling/v2/omni-video/kling-4.0' \
  --header 'Authorization: Bearer YOUR_ANYFAST_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "type": "prompt",
        "text": "编辑@base，只把人物手中红色陶瓷杯改成蓝色。保持人物面容、服装、手部动作、背景、镜头运动、台词和环境声不变。不要新增物体或字幕。"
      },
      {
        "type": "base_video",
        "url": "https://example.com/source-video.mp4",
        "id": "base"
      }
    ],
    "settings": {
      "resolution": "720p",
      "aspect_ratio": "adaptive"
    },
    "options": {
      "watermark_info": {
        "enabled": false
      }
    }
  }'
```

## 查询任务结果

视频生成采用异步流程。创建接口成功表示任务已受理，不代表视频已经生成完成。保存创建响应中的 `data.id`，并使用同一个 AnyFast API Key 查询：

```bash cURL theme={null}
curl --request GET \
  --url 'https://www.anyfast.ai/kling/v2/tasks?task_ids=YOUR_TASK_ID' \
  --header 'Authorization: Bearer YOUR_ANYFAST_API_KEY'
```

创建响应中的 `data` 是对象，查询响应中的 `data` 是数组。创建响应示例：

```json theme={null}
{
  "code": 0,
  "message": "",
  "request_id": "REQUEST_ID",
  "data": {
    "id": "asyntask_EXAMPLE",
    "status": "submitted",
    "create_time": 1793672435967,
    "update_time": 1793672435967,
    "external_id": ""
  }
}
```

| 字段 | 说明 |
| - | - |
| `code` | 接口业务状态码，成功示例为 `0` |
| `message` | 接口消息 |
| `request_id` | 请求追踪标识，返回时可用于排查 |
| `data.id` | 系统任务 ID，需保存并用于查询 |
| `data.status` | 当前任务状态 |
| `data.create_time` | 创建时间，Unix 毫秒时间戳 |
| `data.update_time` | 更新时间，Unix 毫秒时间戳 |
| `data.external_id` | 自定义任务标识，未设置时可能为空 |

| 状态 | 含义 | 客户端处理 |
| - | - | - |
| `submitted` | 已提交 | 继续查询 |
| `processing` | 正在生成 | 继续查询 |
| `succeeded` | 生成成功 | 读取 `outputs` |
| `failed` | 生成失败 | 保存错误信息并停止轮询 |

建议每隔 10–20 秒查询一次，并设置应用自己的等待上限。到达等待上限时保留任务 ID，后续可继续查询；不要直接重新提交相同生成请求。

查询成功响应示例：

```json theme={null}
{
  "code": 0,
  "message": "",
  "data": [
    {
      "id": "asyntask_EXAMPLE",
      "status": "succeeded",
      "create_time": 1793672435967,
      "update_time": 1793672563000,
      "outputs": [
        {
          "type": "video",
          "url": "https://example.com/generated-video.mp4",
          "duration": "3.042"
        }
      ]
    }
  ]
}
```

从匹配任务的 `outputs` 中选择 `type: "video"` 的结果：

| 字段 | 说明 |
| - | - |
| `url` | 视频结果地址 |
| `duration` | 实际结果时长，单位秒，可能为带小数的字符串 |
| `watermark_url` | 含水印版本地址，仅在提供该结果时存在 |

查询路径不需要拼接模型名称，也不需要填写原厂任务 ID。结果地址可能带有效期或访问签名，生成成功后应及时下载并保存，不要将其当作永久存储地址。

## 参数说明

### 创建请求

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `prompt` | string | 文生视频必填 | 视频内容描述，可同时写入希望出现及希望避免的内容 |
| `contents` | object\[] | 图生视频、全能参考和视频编辑使用 | 提交提示词及关键帧或参考素材；必须包含提示词项 |
| `settings` | object | 否 | 输出清晰度、时长和画面比例 |
| `settings.resolution` | string | 否 | `720p` 或 `1080p`；建议显式填写 |
| `settings.duration` | integer | 否 | 3–30 秒之间的整数；建议显式填写 |
| `settings.aspect_ratio` | string | 否 | `21:9`、`16:9`、`9:16`、`1:1` 或 `adaptive` |
| `options` | object | 否 | 通用选项 |
| `options.watermark_info.enabled` | boolean | 否 | 是否额外生成含水印版本，默认 `false` |
| `options.external_task_id` | string | 否 | 调用方自定义任务标识；当前用户范围内应唯一 |
| `options.callback_url` | string | 否 | 官方协议定义的任务状态通知地址；使用前确认当前通道支持情况 |

### `contents` 素材类型

| `contents[].type` | 用途 | 主要字段 |
| - | - | - |
| `prompt` | 描述生成或编辑要求 | `text` |
| `first_frame` | 首帧图片或约束 | `url`、`id` |
| `middle_frame` | 中间关键帧或约束 | `url`、`id` |
| `last_frame` | 尾帧图片或约束 | `url`、`id` |
| `refer_image` | 人物外观、场景、风格等图片参考 | `url`、`id` |
| `feature_video` | 动作等特征参考 | `url`、`id` |
| `base_video` | 待编辑的原视频 | `url`、`id` |

素材 ID 在同一任务内不得重复。存在多张 `middle_frame` 或多张 `refer_image` 时，应分别填写唯一 ID。官方还定义了 `element` 和 `voice` 素材类型，用于引用已创建的主体和音色；相关调用需要对应资产及管理能力，本页不提供这些管理接口的接入示例。

## 输出与输入限制

### 输出设置

明确填写 `settings.aspect_ratio` 时按指定比例生成。使用 `adaptive` 或省略该字段时，先识别提示词中的画面比例要求，再根据待编辑视频、关键帧或其他输入视频确定比例；均不适用时使用 `16:9`。

文生视频显式传入 `settings.duration` 时，以该参数为准；省略时先识别提示词中的时长意图，没有明确意图时默认生成 10 秒。

全能参考接口的时长按以下顺序确定：

1. 显式传入的 `settings.duration`。
2. 提示词中的明确时长意图。
3. `base_video` 的时长。
4. 以上均未提供时，默认 10 秒。

全能参考接口最多提交一段 `base_video`。示例省略 `settings.duration`；需要明确控制输出长度时可填写该参数。

### 素材要求

以下为官方参数约束；实际可用能力还取决于当前接入资源。

| 素材 | 要求 |
| - | - |
| 图片格式 | JPG、JPEG、PNG |
| 单张图片大小 | 不超过 30 MB |
| 图片尺寸 | 宽、高均不小于 300 px |
| 图片宽高比 | 2:5–5:2 |
| 图片数量 | 最多 10 张 |
| 视频格式 | MP4、MOV |
| 单个视频大小 | 不超过 300 MB |
| 视频时长 | 单个视频及输入视频总时长均须在 3–30 秒内 |
| 视频尺寸 | 宽、高均在 700–4553 px；像素总面积不超过 8,294,400 |
| 视频宽高比 | 2:5–5:2 |
| 输入视频帧率 | 24–60 fps |
| 输出视频帧率 | 24 fps |

图片可使用 URL 或官方支持的 Base64 内容，视频使用 URL。URL 应能由服务端直接访问并返回素材文件。

全能参考接口还需满足：

* 图片、视频、主体和音色的总数量不超过 15。
* 无视频角色主体时，参考视频最多 5 个。
* 存在视频角色主体时，视频角色主体与参考视频合计不超过 5 个。
* 输入视频总时长包含特征参考视频、待编辑视频及视频角色主体的时长。

### 提示词长度

以下限制适用于文生视频的 `prompt` 或 `contents` 中提示词项的 `text`：

| 内容 | 上限 |
| - | -: |
| 纯英文 | 26,000 个字符 |
| 纯非英文 | 11,000 个字符 |
| 混合文本 | 英文字符数 ÷ 26,000 + 非英文字符数 ÷ 11,000 ≤ 1 |

### 提示词建议

可以按以下顺序描述：

```text theme={null}
画面主体和场景 → 动作顺序 → 镜头运动 → 声音要求 → 需要避免的内容
```

多镜头需求可直接写在提示词中。提示词表达生成目标，不保证每个动作或镜头切换时间完全精确。为便于控制生成长度和费用，建议显式设置 `settings.duration`。

### 通用选项说明

* `external_task_id` 不会替代系统生成的任务 ID，也不保证自动防止重复扣费。
* 本指南采用创建响应中的 `data.id` 查询结果；回调和外部 ID 查询不是必要依赖。

> [card] [API 参考](https://docs.anyfast.ai/zh/api-reference/model-api/kuaishou/kling-v4.md)
>
> 查看 Kling 4.0 各能力的请求和响应字段。


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