# 可灵 3.0 能力总览

> 可灵 3.0（Kling 3.0）系列视频模型：路径式 3.0 接口、六个模型、文/图/Omni 生成、动作控制、数字人、声音复刻与计费说明

可灵 3.0（Kling 3.0）是快手可灵的新一代视频生成模型，提供**标准版 `kling-3.0`**、**极速版 `kling-3.0-turbo`** 与**多模态版 `kling-3.0-omni`** 三档视频能力，覆盖文生视频、图生视频（首帧 / 尾帧 / 首尾帧）与 Omni 多模态融合生成（参考图 / 参考视频 / 主体元素）；并在此之上扩展了**动作控制 `kling-3.0-motion-control`**、**数字人 `kling-3.0-avatar`** 与**声音复刻 `kling-3.0-voice`** 三个专用能力，共 **6 个模型**。LoopRouter 以**对标可灵官方 3.0 的路径式接口**对外提供：视频生成走 `/text-to-video/{model}`、`/image-to-video/{model}`、`/omni-video/{model}`，动作控制走 `/motion-control/{model}`，数字人走 `/videos/avatar/image2video`，声音复刻走 `/general/custom-voices`；视频任务查询走 `GET /tasks`，数字人与声音复刻各有专属查询端点；Base URL 换成 `https://api.looprouter.com`、鉴权换成 LoopRouter 令牌即可。

<Note>
可灵 3.0 是**路径式**接口（模型名在 URL 路径里，如 `/text-to-video/kling-3.0`），请求体用 `settings` / `options` / `contents`。所有端点的路径都可**选**加 `/v1` 前缀（如 `/v1/text-to-video/kling-3.0`），行为完全一致，方便 Base URL 带 `/v1` 的可灵 SDK 直接接入；不加前缀是默认形态。它与旧版 body 式的 `/kling/v1` 接口是两套独立的 API，请勿混用。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    文生视频、图生视频、Omni 多模态与任务查询
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/kling/text-to-video">
    在文档内直接对可灵 3.0 端点发起真实请求
  </Card>
  <Card title="获取 API Key" icon="key" href="https://console.looprouter.com/keys">
    在控制台创建 `sk-` 令牌
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="六个模型" icon="layer-group">
    视频三档 `kling-3.0` / `kling-3.0-turbo` / `kling-3.0-omni`，外加动作控制、数字人、声音复刻
  </Card>
  <Card title="Omni 多模态融合" icon="wand-magic-sparkles">
    `/omni-video` 统一处理参考图、参考视频、基准视频与主体元素
  </Card>
  <Card title="动作控制 / 数字人 / 声音复刻" icon="person-running">
    参考视频驱动动作、音频驱动人像口型、音源克隆音色（`voice_id` 可回填数字人）
  </Card>
  <Card title="路径式原生接口" icon="plug">
    对标可灵官方 3.0 路径式 API，已有示例替换 Base URL 与令牌即可运行
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 | 适用端点 |
| --- | --- | --- |
| `kling-3.0` | 可灵 3.0 标准版：文 / 图生视频，支持 `4k`、多镜头、原生音频 | `/text-to-video`、`/image-to-video` |
| `kling-3.0-turbo` | 可灵 3.0 Turbo 极速版：更快出片，分辨率通常至 `1080p` | `/text-to-video`、`/image-to-video` |
| `kling-3.0-omni` | 可灵 3.0 Omni 多模态版：融合参考图 / 参考视频 / 基准视频 / 主体元素统一生成 | `/omni-video` |
| `kling-3.0-motion-control` | 动作控制：用参考视频驱动图片 / 主体做出对应动作 | `/motion-control/{model}` |
| `kling-3.0-avatar` | 数字人：用音频驱动人像口型说话 | `/videos/avatar/image2video` |
| `kling-3.0-voice` | 声音复刻：克隆一段音源的音色，产出可复用的 `voice_id` | `/general/custom-voices` |

<Note>
前三个视频模型的模型名写在 URL 路径中（`/text-to-video/kling-3.0`），任务类型由**调用的端点**决定：`kling-3.0` 与 `kling-3.0-turbo` 走文生 / 图生端点，多模态融合用 `kling-3.0-omni` 走 `/omni-video`。动作控制、数字人、声音复刻是**专用端点**，计费模型由端点自动绑定：动作控制支持官方 `contents` / `settings` 或扁平结构两种请求形态（并存时以 `contents` / `settings` 优先），数字人与声音复刻请求体为扁平结构。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 图生视频（首帧、尾帧、首尾帧）/ Omni 多模态（参考图、参考视频、基准视频、主体元素） |
| 分辨率 | `720p` / `1080p` / `4k`（Turbo 通常至 `1080p`；具体可用档位以控制台「模型广场」为准） |
| 时长 | `duration` 为整数秒（常用 `5` / `10`），可用区间以模型档位为准 |
| 宽高比 | `16:9`（默认）/ `9:16` / `1:1` |
| 音频 | `native`（生成配套音频）/ `original`（保留参考视频原声，仅 Omni）/ `off`（默认静音） |
| 多镜头 | `multi_shot` 布尔，默认开启；用于多镜头分镜叙事 |
| 参考图 / 主体（Omni） | `refer_image` 传参考图后由网关自动创建主体，或用 `element` + `element_id` 引用既有主体 |
| 参考 / 基准视频（Omni） | `feature_video`（运镜 / 风格参考）、`base_video`（在其基础上续写 / 编辑） |
| 任务模式 | 异步任务：`submitted → processing → succeeded / failed` |
| 任务保留 | 成片 `url` 为限时链接，请及时转存 |

<Warning>
Omni 素材（`first_frame` / `last_frame` / `refer_image` / `feature_video` / `base_video` / `element`）与文本一起放在 `contents` 数组里；网关会按顺序把每个素材绑定进提示词，无需手动书写占位符。数量与组合限制以模型档位为准。
</Warning>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/text-to-video/{model}` | 文生视频（`kling-3.0` / `kling-3.0-turbo`） |
| POST | `/image-to-video/{model}` | 图生视频：首帧 / 尾帧 / 首尾帧（`kling-3.0` / `kling-3.0-turbo`） |
| POST | `/omni-video/{model}` | Omni 多模态生成（`kling-3.0-omni`） |
| POST | `/motion-control/{model}` | 动作控制（`kling-3.0-motion-control`；扁平别名 `/videos/motion-control`） |
| POST | `/videos/avatar/image2video` | 数字人提交（`kling-3.0-avatar`） |
| GET | `/videos/avatar/image2video/{task_id}` | 数字人查询（成功态 `succeed`） |
| POST | `/general/custom-voices` | 声音复刻提交（`kling-3.0-voice`） |
| GET | `/general/custom-voices/{task_id}` | 声音复刻查询（成功态 `succeed`） |
| GET | `/general/custom-voices` | 声音复刻列表（已复刻音色） |
| POST | `/general/advanced-custom-elements` | 创建自定义主体（主体管理，渠道级能力、不计费） |
| GET | `/general/advanced-custom-elements/{task_id}` | 查询自定义主体（返回 `element_id`） |
| GET | `/general/advanced-presets-elements` | 查询官方预置主体（分页） |
| GET | `/tasks` | 批量查询视频任务（`task_ids` 或 `external_task_ids`；含动作控制，不含数字人 / 声音复刻） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。以上路径均可**选**加 `/v1` 前缀（如 `/v1/text-to-video/{model}`），行为一致。
</Tip>

<Info>
视频类端点（文生 / 图生 / Omni / **动作控制**）统一走批量 `GET /tasks` 查询（`task_ids` 与 `external_task_ids` 支持逗号批量）。**数字人**与**声音复刻**各有专属查询端点——数字人走 `GET /videos/avatar/image2video/{task_id}`、声音复刻走 `GET /general/custom-voices/{task_id}`，二者成功态为 `succeed`（区别于视频端点的 `succeeded`），**不**走 `GET /tasks`。Omni 的参考主体通过 `contents` 里的 `refer_image` 自动创建。**文本转语音（TTS，`POST /audio/tts`）在本渠道不支持**，调用返回 `501`，请改用「声音复刻 + 数字人」组合（详见下方常见问题）。**主体管理**（创建 / 查询 / 官方预置列表）已开放，用参考图 / 参考视频定义可复用主体并产出 `element_id` 供 Omni / 动作控制引用（渠道级能力、不计费，详见[自定义主体](/api-capabilities/kling/custom-elements)）。暂未开放：主体的更新 / 删除、独立的音色管理 CRUD、单任务 `GET /tasks/{id}` 与游标分页 `POST /tasks`、回调（`callback_url`）投递。
</Info>

## 模型定价

不同能力有两种计费口径：**5 个视频模型按分辨率 × 时长（秒）计费**，**声音复刻按次计费**。

| 模型 | 计费方式 | 说明 |
| --- | --- | --- |
| `kling-3.0` / `kling-3.0-turbo` / `kling-3.0-omni` | 分辨率 × 时长 | 提交按参数预扣，完成按实际时长多退少补 |
| `kling-3.0-motion-control` | 分辨率 × 时长（**提交预扣 30 秒封顶**） | 输出时长由参考视频决定，提交时按 30 秒上限预扣、完成后回收 |
| `kling-3.0-avatar` | 分辨率 × 时长（**提交预扣 300 秒封顶**） | 输出时长跟随驱动音频（2-300 秒），提交时按 300 秒上限预扣、完成后回收 |
| `kling-3.0-voice` | **按次**（flat） | 每次提交按固定单价计费，非视频、无预扣回收 |

<Steps>
  <Step title="提交预扣">
    视频任务创建成功后按参数（分辨率、时长）预扣额度；动作控制 / 数字人在输出时长未知时按最大计费时长（30 秒 / 300 秒）预扣，因此提交时需保证余额充足。声音复刻在提交时一次性按次扣费。
  </Step>
  <Step title="完成结算">
    视频任务成功后按实际时长结算，多退少补；任务失败全额退回。声音复刻无二次结算。
  </Step>
</Steps>

<Info>
各分辨率每秒单价、动作控制 / 数字人的 `mode`（`std`→`720p`、`pro`→`1080p`）对应档位，以及声音复刻的按次单价，均以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率。
</Info>

## 限流与重试

- 收到 429 或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔约 10 秒；`4k` 与长时长任务生成耗时更久，请适当延长轮询周期。

## 常见问题

<AccordionGroup>
  <Accordion title="它和旧版 /kling/v1 接口一样吗？">
    不一样。可灵 3.0 是**路径式**接口（`/text-to-video/{model}` 等，路径可**选**加 `/v1` 前缀，带与不带一致），请求体用 `settings` / `options` / `contents`，提交与查询响应用 `data.outputs[]`、状态枚举 `submitted / processing / succeeded / failed`。旧版 `/kling/v1` 是 body 式接口，二者独立。
  </Accordion>
  <Accordion title="创建任务后怎么拿到视频？">
    这是异步任务：提交返回任务 `id`，需轮询 `GET /tasks?task_ids={id}` 直到 `status` 为 `succeeded`，再从 `outputs[].url` 下载成片。
  </Accordion>
  <Accordion title="支持哪些分辨率？">
    `720p` / `1080p` / `4k`（Turbo 通常至 `1080p`）。在请求 `settings.resolution` 中设置，具体可用档位以控制台「模型广场」为准。
  </Accordion>
  <Accordion title="三个模型怎么选？">
    纯文 / 图生视频且追求速度 → `kling-3.0-turbo`；需要 `4k`、多镜头、原生音频 → `kling-3.0`；需要参考图 + 参考视频 + 主体融合的多模态生成 → `kling-3.0-omni`（走 `/omni-video`）。
  </Accordion>
  <Accordion title="支持数字人 / 动作控制 / 音色定制吗？">
    支持，三者都是**专用端点**：动作控制走 `POST /motion-control/{model}`（`kling-3.0-motion-control`，参考视频驱动图片 / 主体做动作，支持官方 `contents` / `settings` 或扁平结构 `/videos/motion-control` 两种形态），数字人走 `POST /videos/avatar/image2video`（`kling-3.0-avatar`，音频驱动人像口型），声音复刻走 `POST /general/custom-voices`（`kling-3.0-voice`，克隆音源音色）。查询上，动作控制属视频任务走 `GET /tasks`；数字人走专属 `GET /videos/avatar/image2video/{task_id}`、声音复刻走 `GET /general/custom-voices/{task_id}`，两者成功态为 `succeed`。声音复刻产出的 `voice_id` 可作为数字人的 `audio_id` 复用。此外[自定义主体](/api-capabilities/kling/custom-elements)（主体管理）已开放——用参考图 / 参考视频创建可复用主体、查询拿到 `element_id`，再在 Omni / 动作控制里以 `element` 引用（渠道级能力、不计费）。仍暂未开放的是：主体的更新 / 删除、音色管理 CRUD 与回调（`callback_url`）。
  </Accordion>
  <Accordion title="为什么没有单任务查询接口？">
    统一使用批量 `GET /tasks`，`task_ids` 与 `external_task_ids` 均支持逗号批量查询（一次只认一种，`task_ids` 优先）。游标分页 `POST /tasks` 暂未开放。
  </Accordion>
  <Accordion title="支持文本转语音（TTS）吗？">
    不支持。可灵官方的文本转语音端点 `POST /audio/tts`（含 `/v1` 别名）在本渠道**不可用**，调用会返回 `501 Not Implemented`。如需「用指定音色说话」，请走两步替代方案：先用[声音复刻](/api-capabilities/kling/voice-cloning) `POST /general/custom-voices` 克隆音色拿到 `voice_id`，再用[数字人](/api-capabilities/kling/video-generation#数字人) `POST /videos/avatar/image2video` 以该 `voice_id`（作 `audio_id`）驱动人像开口说话。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    参数、示例、三类生成端点与任务查询
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>