# 可灵 / Kling 视频

> 可灵 3.0、Turbo、Omni 与动作控制的现代原生请求，以及批量、外部 ID 和游标任务查询。

Base URL：`https://platform.sgt.site/kling`

本文中的接口路径均相对于此 Base URL；完整请求地址由二者拼接。

| 方法 | 路径 |
| --- | --- |
| POST | `/{operation}/{model}` |
| GET | `/tasks?task_ids={id1},{id2}` |
| GET | `/tasks?external_task_ids={外部ID1},{外部ID2}` |
| POST | `/tasks`（游标查询） |
| GET | `/models`、`/v1/models` |

模型自动发现：`GET /models` 与 `GET /v1/models`（支持尾斜杠）使用平台虚拟密钥，返回当前身份实际可达且启用的可灵渠道模型，并沿用模型授权和价格过滤。它们是平台兼容扩展，不是可灵官方列表 API；无可见项时返回 HTTP 200、`object: "list"`、`data: []`，不调用上游、不创建任务或扣费。模型别名可能不含 `kling` 前缀。

本页 Base URL 加 `/models` 得到 `https://platform.sgt.site/kling/models`。若客户端自动追加 `/v1/models`，使用本页 Base URL；若只追加 `/models`，也可以把 Base URL 设为 `https://platform.sgt.site/kling/v1`。发现成功不代表可把生成接口替换为 OpenAI 视频路径，实际操作以目录中的 `public_endpoints` 为准。

<a id="native-kling-section-1"></a>

## 5.1 路由矩阵

路径与官方一致，厂商前缀 `/kling` 已包含在本页 Base URL 中。模型由 URL 路径选择，请求正文不要传 `model`、`model_name` 或 `billing`。

| 操作 | POST 路径 | 模型 |
| --- | --- | --- |
| 文生视频 | `/text-to-video/{model}` | `kling-3.0`、`kling-3.0-turbo` |
| 首帧/首尾帧生成 | `/image-to-video/{model}` | `kling-3.0`；Turbo 仅首帧 |
| 多模态 Omni | `/omni-video/kling-3.0-omni` | `kling-3.0-omni` |
| 动作控制 | `/motion-control/kling-3.0` | `kling-3.0` |
| 按 ID 查询 | `GET /tasks` | 平台任务 ID 或已登记的客户外部 ID |
| 按时间分页 | `POST /tasks` | 当前主体可见的视频任务 |

所有接口使用 `Authorization: Bearer <完整虚拟密钥>`。GET 的 `task_ids` 与 `external_task_ids` 二选一，每种传一个参数值，多个 ID 用逗号分隔；不能在 GET 中附加分页筛选，分页使用 POST。

<a id="native-kling-section-2"></a>

## 5.2 通用设置

| 字段 | 范围和默认值 |
| --- | --- |
| `settings.resolution` | 默认 `720p`；3.0/Omni 支持 `720p/1080p/4k`，Turbo/动作控制不接受 4k |
| `settings.duration` | 非动作控制为整数 3–15，默认 5 |
| `settings.aspect_ratio` | 非动作控制支持 `16:9/9:16/1:1`，默认 16:9 |
| `settings.audio` | 3.0 为 `off/native`，默认 off；Omni 编辑 base_video 可另选 original；Turbo 不接受此字段 |
| `settings.multi_shot` | 3.0/Omni 原生默认 true；示例显式 false；Turbo 不接受此字段 |
| `options.watermark_info.enabled` | boolean，水印 |
| `options.callback_url` | 可选，平台允许的 HTTPS 接收地址；按平台已确认任务事实通知 |
| `options.external_task_id` | 可选，客户自定义 ID，不超过 255 字节，不含首尾空白；同消费主体及协议内必须唯一 |

提示词最多 3072 个字符（官方建议不超过 2500），动作控制最多 2500 个字符。平台按官方字段名严格校验，未列出的字段返回 400。

<a id="native-kling-section-3"></a>

## 5.3 文生视频

`POST /text-to-video/kling-3.0`

完整的 Bash / curl 请求如下。将 `KEY` 替换为自己的完整虚拟密钥：

```bash
BASE_URL="https://platform.sgt.site/kling"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/text-to-video/kling-3.0" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"prompt":"清晨的海边，镜头缓慢向灯塔推进","settings":{"resolution":"720p","duration":3,"aspect_ratio":"16:9","audio":"off","multi_shot":false},"options":{"external_task_id":"video-order-001"}}'
```

每次新生成使用新的外部 ID。下面是同一接口的其他请求体：

```json
{
  "prompt": "清晨的海边，镜头缓慢向灯塔推进",
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": "off",
    "multi_shot": false
  },
  "options": {
    "watermark_info": {"enabled": false}
  }
}
```

使用 Turbo 时把路径模型换为 `kling-3.0-turbo`，并删除 `audio`、`multi_shot`。文生视频必须使用顶层 `prompt`，不能附带 `contents`。

<a id="native-kling-section-4"></a>

## 5.4 图生视频

`POST /image-to-video/kling-3.0`

```json
{
  "contents": [
    {"type": "prompt", "text": "人物自然转头，保持面部和服装一致"},
    {"type": "first_frame", "url": "https://media.example.com/first.png"}
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": "off",
    "multi_shot": false
  }
}
```

图生视频使用 `contents`，不带顶层 prompt；必须有一个 first_frame。普通 3.0 可增加一个 `last_frame`，Turbo 不接受尾帧。3.0 可引用当前主体可见的平台 element（最多 3 个，需同时提供 `element_id` 和用于提示词引用的 `id`）。`element_id` 使用[主体创建或官方预置目录](native-kling-resources.md)返回的 `kr_...` ID；`id` 使用本次提示词中的名称，例如 `person_1`。

<a id="native-kling-section-5"></a>

## 5.5 Omni 多模态

`POST /omni-video/kling-3.0-omni`

参考图示例：

```json
{
  "contents": [
    {"type": "prompt", "text": "让 @image_1 中的人物向镜头挥手"},
    {
      "type": "refer_image",
      "url": "https://media.example.com/person.png",
      "id": "image_1"
    }
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": "off",
    "multi_shot": false
  }
}
```

视频编辑示例：

```json
{
  "contents": [
    {"type": "prompt", "text": "将视频中的场景改成落日氛围"},
    {
      "type": "base_video",
      "url": "https://media.example.com/reference.mp4",
      "id": "video_1"
    }
  ],
  "settings": {
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "audio": "off",
    "multi_shot": false
  }
}
```

| 输入 | 约束 |
| --- | --- |
| `refer_image` / `element` | 无参考视频时合计最多 7 项；有参考视频时最多 4 项 |
| `feature_video` | 最多一个参考视频，要求 `audio=off`、`multi_shot=true` |
| `base_video` | 最多一个参考视频，允许 `audio=off/original`、要求 `multi_shot=false`；不允许首尾帧，也不允许 native 音频 |
| `last_frame` | 必须同时存在 first_frame |
| `id` | 若提供，各内容项之间不可重复 |
| `element` | 需要 `element_id=kr_...` 和本次引用名称 `id`；引用[主体与音色接口](native-kling-resources.md)中当前主体可见的资源 |

`feature_video` 与 `base_video` 合计最多一项。输入视频时输出长度可能跟随素材，请以查询结果中的 `duration` 为准。需要保留被编辑视频原声时，将视频编辑示例的 `settings.audio` 改为 `original`；没有 base_video 或使用 feature_video 时不能选择 original。费用仍按实际时长与本次冻结的价格表达式计算。素材格式、尺寸、时长要求见 5.8。

<a id="native-kling-section-6"></a>

## 5.6 动作控制

`POST /motion-control/kling-3.0`

```json
{
  "contents": [
    {"type": "prompt", "text": "让图片中的人物模仿参考视频动作"},
    {"type": "image", "url": "https://media.example.com/person.png"},
    {"type": "video", "url": "https://media.example.com/motion.mp4"}
  ],
  "settings": {
    "resolution": "720p",
    "character_orientation": "video",
    "audio": "off"
  }
}
```

必须有一个视频和一个图片或 element。`character_orientation=image` 表示人物朝向与图片一致，此时参考视频最长 10 秒；`video` 表示与视频一致，参考视频最长 30 秒；使用 element 时只能选 `video`。音频取 `original`（默认，保留参考视频原声）或 `off`。此操作不接受 `duration`、`multi_shot`、`aspect_ratio`，输出时长跟随参考视频中可提取的有效动作。

<a id="native-kling-section-7"></a>

## 5.7 提交和查询响应

提交响应示例：

```json
{
  "code": 0,
  "message": "",
  "request_id": "request_example",
  "data": {
    "id": "task_example",
    "status": "submitted",
    "create_time": 1790553600000,
    "update_time": 1790553600000
  }
}
```

查询 `GET /tasks?task_ids=task_example`：

```json
{
  "code": 0,
  "message": "",
  "data": [
    {
      "id": "task_example",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "id": "video_example",
          "url": "https://media.example.com/generated-video.mp4",
          "duration": "5.04"
        }
      ]
    }
  ]
}
```

注意提交 `data` 是对象，查询 `data` 是数组。状态是 `submitted/processing/succeeded/failed`；原生时间字段为毫秒，输出 duration 可以是小数字符串。按 `outputs[].type` 识别视频，再使用对应 URL。`failed` 时 `data[].message` 为平台受控的失败提示，不含模型服务原文。

<a id="native-kling-h-63de1547"></a>

### 批量与外部 ID 查询

以下请求只读取任务，不触发新的生成或费用：

```bash
BASE_URL="https://platform.sgt.site/kling"
KEY="替换为你的完整虚拟密钥"
curl --get "$BASE_URL/tasks" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode 'task_ids=task_a,task_b'

curl --get "$BASE_URL/tasks" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode 'external_task_ids=video-order-001,video-order-002'
```

每次最多查询 500 个 ID。HTTP 200 的 `data` 是可见任务数组；不存在、已删除或无当前权限的任务不出现在结果中，全部不可见时为 `[]`。平台先校验消费主体、企业、当前模型和密钥限制，不向调用方暴露共享上游账号列表。

提交时的 `options.external_task_id` 不会覆盖平台生成的 `data.id`；响应的 `external_id` 返回调用方自己的外部 ID。已有受理或任务占用同一外部 ID 时，重复提交返回 HTTP 409；它不提供“重复 POST 自动取回原任务”的幂等契约。只有确认尚未提交、没有任务接管并完成资金和用量回收后，该 ID 才可用于新的请求，例如修正预算不足后重试。已接管、已发送或结果未知的任务保留唯一声明；结果未知时按原平台 ID 或外部 ID 查询，不能更换 ID 自动重新提交。

<a id="native-kling-h-081b84a0"></a>

### 游标查询

`POST /tasks` 用于按时间和状态查询。JSON 请求体不产生生成费用。

```bash
BASE_URL="https://platform.sgt.site/kling"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/tasks" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"limit":20,"filters":[{"key":"status","values":["succeeded"]},{"key":"product_type","values":["video"]}]}'
```

| 字段 | 类型 | 默认与规则 |
| --- | --- | --- |
| `start_time` | string | Unix 毫秒时间戳；默认 end_time 前 30 天，须早于 end_time |
| `end_time` | string | Unix 毫秒时间戳；默认当前时间 |
| `limit` | integer | 默认 100，范围 1–500 |
| `filters` | array | 可省略；每项包含 key 与非空 values 数组 |
| `filters[].key=status` | string | values 可用 submitted/processing/succeeded/failed |
| `filters[].key=product_type` | string | 本页视频使用 video；协议还接受 image/try_on，但只返回当前已接入且可见的记录 |
| `cursor` | string | 使用上一页返回的 next_cursor；沿用该游标的原时间范围和筛选条件 |

成功响应格式如下（任务字段节选）：

```json
{
  "code": 0,
  "message": "",
  "request_id": "request_example",
  "data": {
    "result": [{"id": "task_example", "status": "succeeded", "create_time": 1790553600000}],
    "next_cursor": "下一页的游标"
  }
}
```

下一页发送 `{"cursor":"上次返回的next_cursor","limit":20}`。`next_cursor` 为空字符串时没有下一页。游标不能当作授权凭证，仍需同一虚拟密钥，并在每页重新检查当前权限。查询默认最近 30 天，不套用其他厂商的七天窗口。

<a id="native-kling-h-c4932872"></a>

### 受理结果未知与回调

网络断开、超时或异常成功响应时，平台保留同一个任务及资金，继续按其 ID 核对；不要重复生成。生成状态与账务结算分别确认，缺少可信时长或用量不会把预估金额当成最终金额。

`options.callback_url` 由平台接收、验证并保存，不直接交给上游。回调正文是单个裸任务对象，包含平台 id、status、毫秒时间、客户 external_id 和输出；没有 GET 查询的 code/data 数组外壳。按[任务回调与验签](task-callbacks.md)校验平台 HMAC 并按事件 ID 去重，不使用厂商 Webhook Secret 验证平台通知。

<a id="native-kling-section-10"></a>

## 5.8 官方接口与输入限制

官方地址为 `https://api-beijing.klingai.com`，平台 Base URL 为 `https://platform.sgt.site/kling`，下表路径分别相对于各自 Base URL，请求体相同：

| 操作 | 官方接口 | 平台接口 |
| --- | --- | --- |
| 文生视频 | `POST /text-to-video/{model}` | `POST /text-to-video/{model}` |
| 图生视频 | `POST /image-to-video/{model}` | `POST /image-to-video/{model}` |
| Omni 视频 | `POST /omni-video/kling-3.0-omni` | `POST /omni-video/kling-3.0-omni` |
| 动作控制 | `POST /motion-control/kling-3.0` | `POST /motion-control/kling-3.0` |
| 按 ID 查询 | `GET /tasks` | `GET /tasks`，task_ids 与 external_task_ids 二选一 |
| 游标查询 | `POST /tasks` | `POST /tasks`，返回当前主体可见的记录 |

**图片（`first_frame`、`last_frame`、`refer_image`、动作控制的 `image`）：**格式 jpg、jpeg、png；单张不超过 50 MB；宽、高不小于 300 px；宽高比在 1:2.5 到 2.5:1 之间；可用 URL 或 Base64。3.0 和 Omni 支持只传首帧或首帧+尾帧，不支持只传尾帧；Turbo 只支持首帧。

**Omni 参考视频（`feature_video`、`base_video`）：**格式 mp4、mov；单个不超过 200 MB；时长 3–15.5 秒（含）；宽、高在 700–4553 px（含）之间，总像素不超过 8294400，宽高比 0.4–2；帧率 24–60 fps（输出为 24 fps）；最多 1 段，只能用 URL。

**Omni 参考图与主体数量：**

- 无参考视频时，参考图与多图主体合计不超过 7 个；同时使用视频角色主体时，视频角色主体不超过 3 个，参考图与多图主体合计不超过 4 个。
- 有参考视频时，参考图与多图主体合计不超过 4 个；不能同时使用视频角色主体和参考图。
- 使用首帧或首尾帧时，最多 3 个主体。

**动作控制参考视频（`video`）：**格式 mp4、mov；单个不超过 100 MB；宽、高在 340–3850 px（含）之间；时长不少于 3 秒，`character_orientation=video` 时最长 30 秒、`image` 时最长 10 秒；最多指定 1 个主体。

**其他官方规则：**

- 多镜头：`multi_shot=true` 时可在提示词中按“镜头 n, m, words;”分镜，最多 6 个镜头，各镜头时长之和等于总时长。
- 生成的视频、图片会在 30 天后被清理，请及时转存。
- 原生字段的可用组合以本页规则为准；平台任务与资源标识不能替换为共享上游账号的原始标识。

创建主体、绑定音色、查询及删除不再使用的资源，见[可灵主体与音色](native-kling-resources.md)。资源创建与视频生成分别计费；正在生成或结果待核对的引用会阻止删除对应资源。