> ## Documentation Index
> Fetch the complete documentation index at: https://quwan-b8010aef.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 可灵 Kling 视频生成示例

> Kling V3、V3 Omni、3.0 Turbo 与 V2.6 的能力矩阵、文生与图生、视频参考与编辑、分镜及完整轮询示例

# 可灵 Kling 视频生成示例

通过平台 `POST /v1/videos` 创建异步视频任务，使用返回的 `id` 查询进度，完成后下载视频。本文参数均放在 JSON 顶层；使用平台 API Key，不需要供应商密钥或供应商任务地址。

## 模型与能力矩阵

| 能力 | `kling-v3` | `kling-3.0-turbo` | `kling-v3-omni` |
| - | - | - | - |
| 文生视频、首帧图生视频 | 支持 | 支持 | 支持 |
| 时长 | 3–15 秒整数，默认 5 秒 | 同左 | 普通生成同左；视频编辑继承输入时长 |
| 清晰度 `mode` | `std`（720p）、`pro`（1080p）、`4k` | `std`（720p）、`pro`（1080p） | `std`、`pro`、`4k`；输入视频时不支持 `4k` |
| 默认清晰度 | `std` | `std` | `std` |
| 同步音频 `generate_audio` | 默认 `true`，可传 `false` 关闭 | 固定有声，不能传 `false` | 默认 `false`；输入视频时不能开启新音频 |
| 文生画幅 `ratio` | `16:9`（默认）、`9:16`、`1:1` | 同左 | 同左 |
| 图生画幅 | 由首帧决定 | 同左 | 单纯首帧图生由首帧决定；参考生视频可设 `ratio` |
| 尾帧 | 支持，必须同时提供首帧 | 不支持 | 支持，必须同时提供首帧，不能追加其他参考图 |
| 多图参考生视频 | 不支持 | 不支持 | 支持 |
| 自定义分镜 `multi_prompt` | 支持 1–6 个分镜 | 同左 | 支持；不能与输入视频组合 |
| 智能分镜 `shot_type: intelligence` | 支持 | 支持 | 支持；不能与输入视频组合 |
| 负向提示词 `negative_prompt` | 支持 | 不支持 | 不支持 |
| 引导系数 `cfg_scale` | 支持 0–1 | 不支持 | 不支持 |
| 主体参考 `elements` | 图生视频、动作控制支持；文生视频不支持 | 不支持 | 支持，最多 3 个；可仅以主体作为参考素材 |
| 视频参考 / 视频编辑 `video_list` | 不支持 | 不支持 | 支持，最多 1 段输入视频 |
| 动作控制 | 支持 `std`、`pro`，不支持 `4k` | 不支持 | 不支持独立动作控制接口 |
| Remix | 不支持 | 不支持 | 不支持；视频编辑使用 `video_list` |

历史模型 `kling-v2-6-std`、`kling-v2-6-pro` 继续使用相同的平台接口，但参数范围不同，见文末“V2.6 兼容调用”。请使用当前环境 `GET /v1/models` 返回的模型 ID。

## 快速开始：文生视频

```bash theme={null}
curl https://api.tokenops.ai/v1/videos \
  -H 'Authorization: Bearer <API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-3.0-turbo",
    "prompt": "一只红狐狸缓慢走过雪地，固定远景机位，伴随轻微的踩雪声",
    "mode": "std",
    "duration": 5,
    "ratio": "16:9"
  }'
```

V3 无声视频使用 `"model":"kling-v3"` 和 `"generate_audio":false`。两款模型的 `std` 档均支持有声视频。

创建响应中的 `id` 是后续查询和下载使用的平台任务 ID。以下响应仅为字段示意，实际 ID 以接口返回为准：

```json theme={null}
{
  "id": "<VIDEO-ID>",
  "object": "video.generation",
  "status": "pending"
}
```

## V3 / Turbo 参数说明

| 参数 | 类型 | 说明 |
| - | - | - |
| `model` | string | 必填，使用能力矩阵中的模型 ID |
| `prompt` | string | 单镜头、智能分镜及动作控制必填，最多 2500 字符；自定义分镜时不传 |
| `duration` | integer | 普通生成 3–15 秒，默认 5；动作控制不传 |
| `seconds` | string | `duration` 的兼容写法，如 `"5"`；同时传入时必须相同 |
| `mode` | string | `std`、`pro` 或 V3 的 `4k` |
| `resolution` | string | 清晰度的另一种写法：`720p`、`1080p`、`4k`（兼容 `2160p`） |
| `size` | string | `宽x高`，按短边 720、1080、2160 选择档位；不是任意尺寸生成 |
| `ratio` | string | 文生画幅，默认 `16:9`；图生不通过此参数裁剪首帧 |
| `generate_audio` | boolean | V3 默认开启；Turbo 固定开启；动作控制改用 `keep_original_sound` |
| `sound` | string | 音频兼容参数 `on` / `off`；若同时传入，`generate_audio` 优先。建议只使用 `generate_audio` |
| `negative_prompt` | string | 仅 V3 普通生成使用，不用于动作控制 |
| `cfg_scale` | number | 仅 V3 普通生成使用，0–1；不用于动作控制 |
| `content` | array | 首帧、尾帧、动作视频，格式见后文 |
| `multi_prompt` | array | 自定义分镜，格式及约束见后文 |
| `multi_shot` | boolean | 开启多镜头；传分镜列表时自动开启，不能显式设为 `false` |
| `shot_type` | string | `customize` 配合分镜列表；`intelligence` 配合 `prompt` |
| `elements` | array | 仅 V3 图生视频、动作控制的主体参考 |
| `character_orientation` | string | 动作控制必填，`image` 或 `video` |
| `keep_original_sound` | boolean | 动作控制是否保留参考视频原声，默认保留 |

### 清晰度与画幅

推荐只传 `mode` 和 `ratio`。如果同时传 `mode`、`resolution`、`size`，它们必须指向相同清晰度；文生视频同时传 `size` 和 `ratio` 时，宽高比也必须一致。

| 清晰度 | `mode` | `resolution` | `size` 示例：横屏 / 竖屏 / 方形 |
| - | - | - | - |
| 720p | `std` | `720p` | `1280x720` / `720x1280` / `720x720` |
| 1080p | `pro` | `1080p` | `1920x1080` / `1080x1920` / `1080x1080` |
| 4K（仅 V3） | `4k` | `4k` | `3840x2160` / `2160x3840` / `2160x2160` |

图生视频的画幅由首帧决定，返回的实际宽高可能与表中示例不同。`size` 选择清晰度档位，不保证输出精确等于传入尺寸。

## 首帧图生视频

将示例 URL 换成供应商可访问的图片地址。普通图生只需要一张首帧；不要重复传入同一首帧的多个表示。

```bash theme={null}
curl https://api.tokenops.ai/v1/videos \
  -H 'Authorization: Bearer <API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling-3.0-turbo",
    "prompt": "保持人物和房间布局一致，人物缓慢转头，镜头轻微推进",
    "mode": "pro",
    "duration": 5,
    "content": [
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": {"url": "https://your-cdn.example/first.png"}
      }
    ]
  }'
```

V3 / Turbo 的图片角色支持 `first_frame`，兼容 `reference_image` 和空角色；尾帧支持 `last_frame` 或 `end_frame`。图片内容的 `type` 必须是 `image_url`。

Turbo 首帧使用 JPG/JPEG/PNG，文件不超过 50MB，宽高至少 300px，宽高比在 1:2.5 到 2.5:1 之间。避免使用需要登录、短期签名已过期或仅内网可访问的素材链接。

### 首尾帧（仅 V3）

以下 JSON 作为 `POST /v1/videos` 的请求体：

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "镜头从开场缓慢移动到结束画面，保持人物身份和场景连续",
  "mode": "pro",
  "duration": 5,
  "generate_audio": false,
  "content": [
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://your-cdn.example/first.png"}},
    {"type": "image_url", "role": "last_frame", "image_url": {"url": "https://your-cdn.example/last.png"}}
  ]
}
```

不能仅传尾帧。Turbo 不支持尾帧；动作控制不能同时传尾帧。

## 自定义分镜

两款模型都通过 `multi_prompt` 定义多个镜头。下面是 5 秒、两个镜头的请求体：

```json theme={null}
{
  "model": "kling-v3",
  "mode": "std",
  "duration": 5,
  "generate_audio": false,
  "multi_shot": true,
  "shot_type": "customize",
  "multi_prompt": [
    {"index": 1, "prompt": "白色背景，红色小球在桌面缓慢滚动，全景", "duration": "2"},
    {"index": 2, "prompt": "切换到深色背景，蓝色立方体缓慢旋转，特写", "duration": "3"}
  ]
}
```

使用 Turbo 时，将 `model` 改为 `kling-3.0-turbo`，删除 `generate_audio:false`。图生分镜可在以上请求中加入首帧 `content`，Turbo 仍不能加入尾帧。

* `multi_prompt` 包含 1–6 项，`index` 从 1 连续递增。
* 每项 `prompt` 非空且不超过 512 字符，不能包含半角分号 `;`，可改用句号、逗号或全角分号。
* 每项 `duration` 是正整数字符串，至少 1 秒；总和必须等于顶层 `duration`，总时长仍为 3–15 秒。
* 自定义分镜不同时传顶层 `prompt`。`shot_type` 可省略，传入时使用 `customize`。
* 组合后的分镜提示词总长度（含镜头序号和时长描述）最多 2500 字符，超出会返回参数错误，不会截断。
* `multi_prompt` 会自动开启多镜头，不能与 `multi_shot:false` 共用。

### 智能分镜

使用顶层 `prompt` 描述镜头要求，传 `shot_type:intelligence`，不传 `multi_prompt`；也可使用 `multi_shot:true` 配合顶层 `prompt`。

```json theme={null}
{
  "model": "kling-3.0-turbo",
  "mode": "std",
  "duration": 5,
  "shot_type": "intelligence",
  "prompt": "先用全景展示雪地里的红狐狸，再切换到狐狸脚步的特写，伴随踩雪声"
}
```

## 主体参考（仅 V3）

在图生视频或动作控制中加入顶层 `elements`，并通过提示词中的 `@Element1` 引用第一项主体。每项选择以下一种形态：

| 形态 | 字段 | 约束 |
| - | - | - |
| 内联图片 | `frontal_image_url` + `reference_image_urls` | 一张正面图；其他角度参考图最多 3 张，建议提供 1–3 张以增强一致性 |
| 已有主体 | `element_id` | 非空字符串或正整数，必须是上游账号可用的主体 ID |

同一项不能混用 `element_id` 与内联图片。平台当前不提供本文主体的创建、审核或管理流程；优先使用内联图片方式。

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "@Element1 缓慢转头并微笑，保持首帧中的服装和房间布局",
  "mode": "std",
  "duration": 5,
  "generate_audio": false,
  "content": [
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://your-cdn.example/scene.png"}}
  ],
  "elements": [
    {
      "frontal_image_url": "https://your-cdn.example/person-front.png",
      "reference_image_urls": ["https://your-cdn.example/person-side.png"]
    }
  ]
}
```

`elements` 不能用于 V3 文生视频或 Turbo。主体数量等额外限制仍可能由上游校验。

## 动作控制（仅 V3）

提供一张角色图和一个参考动作视频。`character_orientation:image` 以角色图片朝向为准，`video` 以参考视频朝向为准。此场景的输出时长由参考视频决定。

```json theme={null}
{
  "model": "kling-v3",
  "prompt": "人物按照参考视频完成动作，保持角色外观一致",
  "mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true,
  "content": [
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://your-cdn.example/character.png"}},
    {"type": "video_url", "role": "reference_video", "video_url": {"url": "https://your-cdn.example/motion.mp4"}}
  ]
}
```

动作控制支持 `std` / `pro`，不支持 `4k`。不要传 `duration`、`seconds`、`generate_audio`、`sound`、`negative_prompt`、`cfg_scale`、尾帧或分镜。朝向为 `image` 时参考视频最长 10 秒，朝向为 `video` 时最长 30 秒。确保人物完整清晰、无遮挡。

## 查询任务与下载

```bash theme={null}
# 使用创建响应里的真实 id 替换 <VIDEO-ID>
curl 'https://api.tokenops.ai/v1/videos/<VIDEO-ID>' \
  -H 'Authorization: Bearer <API-KEY>'

# completed 后下载；-L 用于跟随下载重定向
curl -L 'https://api.tokenops.ai/v1/videos/<VIDEO-ID>/content' \
  -H 'Authorization: Bearer <API-KEY>' \
  -o kling-video.mp4
```

| `status` | 含义 | 下一步 |
| - | - | - |
| `pending` | 排队中 | 继续查询同一 ID |
| `in_progress` | 生成或处理结果中 | 继续查询同一 ID |
| `completed` | 已完成 | 读取 `url` 或使用下载接口 |
| `failed` | 已失败 | 检查 `error`，修正后再决定是否创建新任务 |

完成响应包含 `url`、`seconds`，上游提供宽高时还会包含 `size`。字段示意：

```json theme={null}
{
  "id": "<VIDEO-ID>",
  "object": "video.generation",
  "status": "completed",
  "url": "https://your-result.example/video.mp4",
  "seconds": "5",
  "size": "1920x1080"
}
```

建议每 10 秒查询一次。任务可能超过 10 分钟，客户端等待超时不代表生成失败。保存任务 ID，稍后继续查询；不要因本地轮询超时就重复提交创建请求。重复查询同一任务不会重新生成视频。

## 完整 Python 示例

安装 `requests`，设置环境变量 `TOKENOPS_API_KEY` 后运行。示例接受所有上述顶层参数，图生、分镜和音频字段会完整发送。

```python theme={null}
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://api.tokenops.ai/v1"
SESSION = requests.Session()
SESSION.headers["Authorization"] = f"Bearer {os.environ['TOKENOPS_API_KEY']}"


def create_video(payload):
    response = SESSION.post(f"{BASE_URL}/videos", json=payload, timeout=60)
    response.raise_for_status()
    task = response.json()
    print("请保存任务 ID:", task["id"])
    return task["id"]


def wait_video(video_id, wait_seconds=1200):
    deadline = time.monotonic() + wait_seconds
    while time.monotonic() < deadline:
        response = SESSION.get(f"{BASE_URL}/videos/{video_id}", timeout=60)
        response.raise_for_status()
        task = response.json()
        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(f"任务失败: {task.get('error')}")
        time.sleep(10)
    raise TimeoutError(f"仍未完成，请继续查询同一任务 {video_id}，不要重复创建")


def download_video(video_id, output_path):
    with SESSION.get(
        f"{BASE_URL}/videos/{video_id}/content", stream=True, timeout=120
    ) as response:
        response.raise_for_status()
        with Path(output_path).open("wb") as target:
            for chunk in response.iter_content(1024 * 1024):
                if chunk:
                    target.write(chunk)


if __name__ == "__main__":
    video_id = create_video({
        "model": "kling-v3",
        "prompt": "海边的金毛犬缓慢奔跑，固定镜头，阳光温暖",
        "mode": "std",
        "duration": 5,
        "generate_audio": False,
    })
    result = wait_video(video_id)
    print("实际时长:", result.get("seconds"), "尺寸:", result.get("size"))
    download_video(video_id, "kling-video.mp4")
```

如果已保存任务 ID，可直接调用 `wait_video(video_id)` 和 `download_video`，无需再次调用 `create_video`。创建请求若因网络超时没有收到响应，先核对是否已成功创建，避免自动重试导致生成多个付费任务。

## 计费与常见错误

普通生成按模型计费页中的清晰度、有声/无声档位及实际视频秒数结算；动作控制按对应档位与实际时长结算。V3 默认有声会影响价格，需无声时显式传 `generate_audio:false`。Turbo 固定有声。

成功视频的时长以任务返回的 `seconds` 为准，不要把播放器容器中多出的少量编码时长自行向上取整。创建时的预扣可能早于最终账单；失败或最终用量变化时，平台按实际结果进行结算或退款，账本更新可能有延迟。视频响应不保证包含文本模型式的 `usage` 尾包，最终扣费请以平台账单为准。

| 情况 | 处理方式 |
| - | - |
| `duration must be an integer between 3 and 15` | V3 / Turbo 使用 3–15 秒整数 |
| `mode conflicts with resolution` / `size conflicts with mode or resolution` | 只保留一种清晰度写法，或使三者一致 |
| `Kling 3.0 Turbo always generates audio` | 删除 `generate_audio:false` 或 `sound:off` |
| `prompt and multi_prompt are mutually exclusive` | 自定义分镜只传 `multi_prompt` |
| `multi_prompt durations must sum to duration` | 各分镜秒数之和等于顶层时长 |
| 尾帧、主体或动作控制参数不支持 | 对照模型能力矩阵，确认使用 V3 及正确场景 |
| 素材 URL 不可访问或上游拒绝素材 | 使用可访问且符合格式要求的素材 |
| 轮询超过本地等待时间 | 保存 ID 并继续查询，不能据此判定任务失败 |

V3 / Turbo 不支持旧版 `camera_control`、`static_mask`、`dynamic_masks`、`watermark`、`watermark_info`、`external_task_id`；`video_list` 也不是 V3 动作控制入口。不要将其他可灵模型的专有参数直接套用到这两个模型。

## Kling V3 Omni

`kling-v3-omni` 支持文字、图片、主体形象和参考视频输入，可用于生成新视频、保持角色外观或编辑已有视频。本文介绍平台的视频能力；图片生成、数字人口播、指定台词及口型同步不属于本文的功能说明。

创建、查询和下载仍使用 `POST /v1/videos`、`GET /v1/videos/{id}`、`GET /v1/videos/{id}/content`。先确认当前环境 `GET /v1/models` 已返回 `kling-v3-omni`。下面的 JSON 均为创建接口的完整请求体，替换素材 URL 后即可使用；认证方式与前文相同。

### 参数与组合限制

| 参数 | 类型 | 默认值与约束 |
| - | - | - |
| `model` | string | `kling-v3-omni` |
| `prompt` | string | 描述目标画面，最多 2500 字符；自定义分镜时不传 |
| `mode` | string | 默认 `std`；支持 `std`、`pro`、`4k`，输入视频时仅支持前两项 |
| `duration` | integer | 默认 5，支持 3–15；视频编辑时省略 |
| `seconds` | string | 时长兼容写法；与 `duration` 同时传入时必须相同；视频编辑时省略 |
| `ratio` | string | 文生及参考生视频默认 `16:9`，支持 `9:16`、`1:1`；单纯首帧图生由首帧决定，视频编辑时省略 |
| `resolution` / `size` | string | 清晰度兼容写法，值和冲突规则见前文；视频编辑可以用 `mode` / `resolution` 选择档位，但不能传 `size` |
| `generate_audio` | boolean | 默认 `false`；无输入视频时可开启原生音频，输入视频时不能设为 `true` |
| `sound` | string | 音频兼容写法 `on` / `off`；同时传入时 `generate_audio` 优先，建议只用后者 |
| `image_list` | array | 图片素材，每项含 `image` URL；`type` 省略表示参考图，`first_frame` 表示首帧，`end_frame` / `last_frame` 表示尾帧 |
| `content` | array | 图片的另一种写法，使用 `type:image_url` 和 `image_url.url`，`role` 规则见下文 |
| `elements` | array | 最多 3 个主体；每项使用内联主体图片或已有 `element_id`，格式见下文 |
| `video_list` | array | 最多 1 段视频，每项含 `video_url`、`refer_type` 和可选的 `keep_original_sound` |
| `multi_prompt` | array | 1–6 个自定义分镜，与顶层 `prompt` 互斥；不能与输入视频组合 |
| `multi_shot` / `shot_type` | boolean / string | 自定义分镜自动开启多镜头；智能分镜使用 `shot_type:intelligence` 配合 `prompt`；不能与输入视频组合 |

素材组合规则：

* `image_list` 与 `content` 的图片合计：无输入视频时最多 7 张，有输入视频时最多 4 张。不要用两种写法重复提交同一首帧或尾帧。
* 尾帧必须与首帧同时提供；首尾帧不能追加其他参考图片，也不能与输入视频组合。
* `content` 图片的 `role:first_frame` 表示首帧，`last_frame` / `end_frame` 表示尾帧；`reference_image`、`multi_reference_image` 或省略 `role` 均表示参考图。普通 V3 的 `reference_image` 首帧兼容写法不适用于 Omni。
* 有输入视频时不能开启新音频、使用 `4k`、首尾帧或分镜；参考图片和主体仍可作为补充素材。
* 不支持 `negative_prompt`、`cfg_scale`、`character_orientation`、顶层 `keep_original_sound`、`input_reference`，以及前文列出的旧版相机、蒙版、水印和自定义任务 ID 参数。

### 文生视频与原生音频

默认生成无声 720p 视频。需要有声时显式开启 `generate_audio`；下面生成 3 秒的 1080p 有声视频：

```json theme={null}
{
  "model": "kling-v3-omni",
  "prompt": "窗边的一枚小铃铛轻轻摇动，固定机位，伴随清晰铃声",
  "mode": "pro",
  "duration": 3,
  "ratio": "16:9",
  "generate_audio": true
}
```

4K 文生视频使用 `"mode":"4k"`；默认仍为无声。生成效果取决于提示词与素材，有音轨不代表指定台词或口型同步得到保证。

### 首帧与首尾帧图生视频

只提供第一项即可首帧图生；同时提供两项则约束起始和结束画面。画幅由首帧决定，不需要额外传 `ratio`。

```json theme={null}
{
  "model": "kling-v3-omni",
  "prompt": "人物缓慢将碗倾向镜头，保持人物外观和房间一致，结束于尾帧姿态",
  "mode": "pro",
  "duration": 3,
  "image_list": [
    {"image": "https://your-cdn.example/start.png", "type": "first_frame"},
    {"image": "https://your-cdn.example/end.png", "type": "end_frame"}
  ]
}
```

### 多图与主体参考

参考图片按顺序使用 `@Image1`、`@Image2` 引用，主体按顺序使用 `@Element1`、`@Element2` 引用。它们用于保持角色、场景或风格；参考图片不自动等同于视频首帧。

```json theme={null}
{
  "model": "kling-v3-omni",
  "prompt": "@Element1 位于 @Image1 的房间中，手持 @Image2 中的碗，保持服装和人物外观，镜头缓慢推进",
  "mode": "std",
  "duration": 3,
  "ratio": "16:9",
  "image_list": [
    {"image": "https://your-cdn.example/room.png"},
    {"image": "https://your-cdn.example/bowl.png"}
  ],
  "elements": [
    {
      "frontal_image_url": "https://your-cdn.example/person-front.png",
      "reference_image_urls": ["https://your-cdn.example/person-side.png"]
    }
  ]
}
```

每个内联主体必须有 `frontal_image_url`，`reference_image_urls` 最多 3 张。已有主体可将这一项替换为 `{"element_id":"已有主体ID"}`；同一项不能同时包含 ID 和内联图片，也不能两者都不传。无需首帧时可以只提交 `elements`，不传 `image_list`。

### 视频参考与视频编辑

| `video_list[].refer_type` | 用途 | 时长与画幅 |
| - | - | - |
| `feature` | 参考输入视频的运动、镜头或风格生成新视频 | 可传 `duration` 和 `ratio` |
| `base`，省略时的默认值 | 对输入视频中的目标、外观或场景进行编辑 | 继承输入视频时长和画幅；不能传 `duration`、`seconds`、`ratio`、`size` |

两种模式都在 **`video_list` 的视频项内** 使用字符串 `"keep_original_sound":"yes"` / `"no"` 控制是否保留原声，默认 `yes`。这与顶层布尔值 `generate_audio` 的“新生成音频”含义不同。下面是参考生成：

```json theme={null}
{
  "model": "kling-v3-omni",
  "prompt": "参考 @Video1 的运动轨迹和固定机位，一颗红球从左向右滚过白色桌面",
  "mode": "pro",
  "duration": 3,
  "ratio": "16:9",
  "generate_audio": false,
  "video_list": [
    {"video_url": "https://your-cdn.example/reference.mp4", "refer_type": "feature", "keep_original_sound": "no"}
  ]
}
```

下面是视频编辑。为避免与继承的时长和画幅冲突，不传上述四个字段：

```json theme={null}
{
  "model": "kling-v3-omni",
  "prompt": "将红球改为蓝球，保持原视频的白色桌面、运动轨迹和镜头不变",
  "mode": "std",
  "video_list": [
    {"video_url": "https://your-cdn.example/original.mp4", "refer_type": "base", "keep_original_sound": "no"}
  ]
}
```

### 自定义分镜

每段 `duration` 使用整数字符串，`index` 从 1 连续递增，所有分镜时长之和必须等于顶层整数 `duration`。每段提示词最多 512 字符且不能含半角分号 `;`；组合后的提示词总长不超过 2500 字符。不要同时传顶层 `prompt`，也不能显式设置 `multi_shot:false`。

```json theme={null}
{
  "model": "kling-v3-omni",
  "mode": "std",
  "duration": 5,
  "shot_type": "customize",
  "multi_prompt": [
    {"index": 1, "prompt": "固定远景，白色桌面上的红色球体，白色背景", "duration": "2"},
    {"index": 2, "prompt": "硬切到近景，黑色桌面上的蓝色方块，黑色背景", "duration": "3"}
  ]
}
```

智能分镜改用 `prompt` 和 `"shot_type":"intelligence"`，不传 `multi_prompt`；不能同时设置 `multi_shot:false`。两种分镜模式均不能与 `video_list` 组合。

### Omni 计费与错误处理

按输出清晰度、有无新生成音频、是否输入参考或待编辑视频选择每秒单价，以平台模型计费页显示的价格为准。默认无声与 V3 默认有声的价格档位不同。

| 场景 | 选择的计费档位 |
| - | - |
| 无输入视频的文生、图生、多图、主体参考、分镜 | `std` / `pro` 的有声或无声档位；图片和主体不使其变成“有参考视频” |
| 视频参考、视频编辑 | `std` / `pro` 的“有参考视频”档位，保留或移除原声不改变这一分类 |
| 4K，无输入视频 | 4K 档位 |

最终按任务返回的 `seconds` 结算。视频编辑继承输入时长，预扣与实际时长不一致时会补扣或退回差额；失败任务按最终结果退款。请等待最终账本更新后核对，不要将创建时预扣金额当作最终金额，也不要根据播放器多出的少量编码时长自行向上取整。

若遇到 `end frame requires first frame`，补充首帧；`Omni video reference/edit requires generate_audio=false`，关闭新音频；`Omni video editing inherits duration and aspect ratio`，移除编辑请求中的 `duration`、`seconds`、`ratio` 和 `size`。轮询超时后继续查询原 ID，不自动重发创建请求。

## V2.6 兼容调用

历史模型仍可通过 `POST /v1/videos` 创建、`GET /v1/videos/{id}` 查询和 `/content` 下载。V2.6 使用字符串 `seconds`（`"5"` 或 `"10"`），模式由模型名中的 `-std` / `-pro` 推导，也可通过顶层 `mode` 指定。

```json theme={null}
{
  "model": "kling-v2-6-pro",
  "prompt": "保持首帧中的人物外观，让人物缓慢转头",
  "seconds": "5",
  "generate_audio": true,
  "content": [
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://your-cdn.example/first.png"}}
  ]
}
```

V2.6 的首帧使用 `reference_image`；旧适配路径不会将 `first_frame` 转成首帧。尾帧使用 `last_frame` / `end_frame`。`size` 可传 `1280x720`、`720x1280`、`1080x1080`，或用 `ratio` 推导；最终尺寸以结果为准。V2.6 不使用本文 V3 专用的 `duration`、`resolution`、`multi_prompt` 和 `elements` 调用方式。`generate_audio:true` 会请求有声视频，上游是否接受该模式组合以实际模型能力为准。

## 参考文档

本文按平台当前实现说明可用参数。供应商文档中的原生字段与接口路径不应直接替换本文的平台字段。

* [七牛云 Kling V3 接口](https://docs.modelink.ai/api/video-fal-kling-v3)
* [七牛云 Kling 3.0 Turbo 接口](https://docs.modelink.ai/api/video-fal-kling-30-turbo)
* [七牛云 Kling V3 Omni 接口](https://docs.modelink.ai/api/video-fal-kling-v3-omni)
* [七牛云 Kling 任务查询](https://docs.modelink.ai/api/video-fal-kling-task)
* [七牛云 Kling 主体参考](https://docs.modelink.ai/models-capabilities/model-kling#field-reference)


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