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

# 可灵视频 3.0 模型

相比上一版本，可灵视频 3.0 音画同步升级，主体一致性增强，支持多镜头叙事。

在可灵视频 O1 和可灵视频 2.6 的基础之上，可灵 3.0 系列模型基于深度融合的统一模型训练框架，实现了更原生的多模态输入和输出，将音画同步能力和主体一致性控制能力融合，并且突破了时长限制。

在支持更长视频生成（15s）的同时，可灵 3.0 系列模型支持原生直出音画，并实现了高度灵活的分镜控制能力与更精准的语义响应精度，为 AI 影像内容注入生命力，整体画面真实感显著提升，人物演绎更具表演张力。

![可灵视频 3.0 模型能力对比概览](https://static.geekai.co/storage/2026/02/27/image-20260227142959902.png)

### 模型参数

* 模型ID：`kling-video-v3`
* 模型价格：你可以在[模型详情页](https://geekai.co/models/kling-video-v3)查看最新价格信息
* 调用入口：`https://geekai.co/api/v1/videos/generations`
* 模型参数：参考[视频 API 手册](https://docs.geekai.co/cn/api/video/generations)
* API认证：[获取 API KEY](https://geekai.co/user/api_keys)

<Note>
  不支持视频公共 API 中的以下参数：

  * `negative_prompt`
  * `size`
  * `fps`

  附：[可灵视频 3.0 官方 API 文档](https://docs.qingque.cn/d/home/eZQCedMeoI1MTquS1SFRihz4S?identityId=1oEFzU43FYK#section=h.0zdc4fiohq6h)
</Note>

`aspect_ratio` 参数支持以下取值：

* `1:1`
* `16:9`
* `9:16`

支持通过 `quality` 参数替代官方的 `mode` 参数来控制生成视频的分辨率，`quality` 的取值范围是 `std`（对应 `720p`）、 `pro`（对应 `1080p`）和 `4k`（v3开始支持），默认值是 `std`，不同质量的视频生成时间和成本不同。

支持通过 `with_audio` 参数来控制是否生成带有音频的视频，`with_audio` 的取值范围是 `true`（对应官方 `audio` 值为 `native`） 和 `false`（对应官方 `audio` 值为 `off`），默认值是 `false`，生成带有音频的视频会增加生成时间和成本。

支持通过 `watermark` 参数替代官方的 `watermark_info` 参数来控制生成视频是否带有水印，`watermark` 的取值范围是 `true` 和 `false`，默认值是 `false`。

可灵视频 3.0 的 `duration` 参数支持生成 3-15s 的视频，默认值是 5s，生成更长时长的视频会增加生成时间和成本。

支持通过 `extra_body` 传递额外参数来设置视频分镜、参考主体和音色等信息：

* `multi_shot`： 控制是否开启分镜，取值范围是 `true` 和 `false`，默认值是 `false`，开启多镜头模式后，可以通过 `shot_type` 参数来指定分镜类型。
* `shot_type`： 指定分镜类型，取值范围是 `customize` 和 `intelligence`，分别代表自定义分镜和智能分镜， 当 `multi_shot` 为 `true` 时本参数必填。
* `multi_prompt`： 描述每个分镜的信息，如提示词、时长等，当 `multi_shot` 为 `true` 且 `shot_type` 为 `customize` 时，本参数必填。
* `element_list`： 参考主体列表，基于主体库中主体的 ID 配置，最多支持3个。

以上字段参数类型和官方参数完全一致：

![可灵视频 3.0 分镜参数说明](https://static.geekai.co/storage/2026/02/27/image-20260227150217721.png)

### 模型价格

可灵视频 3.0 的价格按照生成视频的质量、时长和是否带有音频来计算，以下是价格表：

| 模型      | 质量           | 声音 | 价格（单位：元/秒） |
| ------- | ------------ | -- | ---------- |
| 可灵视频3.0 | `720p`（std）  | 无声 | 0.6        |
| 可灵视频3.0 | `720p`（std）  | 有声 | 0.9        |
| 可灵视频3.0 | `1080p`（pro） | 无声 | 0.8        |
| 可灵视频3.0 | `1080p`（pro） | 有声 | 1.2        |
| 可灵视频3.0 | `4k`         | 无声 | 3.0        |
| 可灵视频3.0 | `4k`         | 有声 | 3.0        |

使用极客智坊提供的[低价代理渠道](https://docs.geekai.co/cn/docs/model_price)调用时，不同参数对应价格按照价格表x对应的折扣值即可：以高可用速度优先渠道为例，折扣值是 `0.8`，那么生成 5 秒无声标准视频价格是 `0.6 x 5 x 0.8 = 2.4` 元，其他参数依次类推。

### 文生视频

通过文字描述来生成对应视频：

```bash theme={null}
curl --location --request POST 'https://geekai.co/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "model": "kling-video-v3",
    "prompt": "广角跟踪镜头：一辆影青色的双门轿跑在沙漠公路上行驶，热浪扭曲清晰可见，头顶烈日高悬",
    "async": true
}'
```

由于视频生成通常比较耗时，建议通过极客智坊提供的异步任务模式生成视频。

[视频 API](https://docs.geekai.co/cn/api/video/generations) 中的 `async` 参数用于控制是否异步生成视频，默认为 `false`，表示创建视频接口会同步等待视频生成完毕并返回。如果设置为 `true`，则会异步生成视频并返回任务ID：

```json theme={null}
{
    "model": "kling-video-v3",
    "task_id": "77e3772b-4e92-4fce-a24c-63907585689d",
    "task_status": "pending"
}
```

你可以使用返回的任务 ID 来查询生成状态和获取视频结果：

```bash theme={null}
curl --location --request GET 'https://geekai.co/api/v1/videos/77e3772b-4e92-4fce-a24c-63907585689d' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' 
```

你可以根据视频生成任务状态 `task_status` 值判断视频是否已经生成完成，这个状态值包括四种情况：

* `pending`：任务已创建，等待处理
* `running`：任务正在处理
* `succeed`：任务成功完成，可以获取结果
* `failed`：任务失败，可能是由于内容违规或其他错误

如果任务还在运行中，返回结果如下：

```json theme={null}
{
    "model": "kling-video-v3",
    "task_id": "77e3772b-4e92-4fce-a24c-63907585689d",
    "task_status": "running"
}
```

轮询视频生成结果接口直到任务状态值为 `succeed`，你就可以获取到生成的视频 URL：

```json theme={null}
{
    "model": "kling-video-v3",
    "task_id": "77e3772b-4e92-4fce-a24c-63907585689d",
    "task_status": "succeed",
    "video_result": [
        {
            "url": "https://static.geekai.co/video/2025/10/14/6c6b8c475899a1c82bcd59a84e78ab46.mp4"
        }
    ]
}
```

### 图生视频

**首帧**

通过 `image` 传入单图即可实现基于首帧生成视频：

```bash theme={null}
curl --location --request POST 'https://geekai.co/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "model": "kling-video-v3",
    "prompt": "无人机以极快速度穿越复杂障碍或自然奇观，带来沉浸式飞行体验",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_i2v.png",
    "async": true
}'
```

**首尾帧**

通过 `image` + `image_tail` 传入首尾两张图即可实现基于首尾帧生成视频：

```bash theme={null}
curl --location --request POST 'https://geekai.co/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "model": "kling-video-v3",
    "prompt": "图中女孩对着镜头说\"茄子\"，360度环绕运镜",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg",
    "image_tail": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg",
    "async": true
}'
```

图片要求：

* 支持 JPG、PNG、WEBP 格式，单张图片大小不超过 10MB；
* 支持 URL 和 Base64 两种方式传入图片，URL 方式需要保证图片可以被公网访问；
* 图片宽高尺寸不小于 300px，图片宽高比介于 1:2.5 \~ 2.5:1 之间；
* image 参数与 image\_tail 参数至少二选一，二者不能同时为空。

### 动作控制

可灵视频动作控制是一项基于视频动作捕捉与迁移的技术，主要核心功能包括动作克隆、精准动作迁移、肢体与表情全面掌控。它能提取参考视频中的人物动作、手势、口型与表情特征，驱动静态图像角色生成动态视频。

下面是可灵视频 3.0 动作控制生成视频的一个示例：

```bash theme={null}
curl --location 'https://geekai.co/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "model": "kling-video-v3",
    "action": "motion-control",
    "prompt": "The girl is wearing a loose gray T-shirt and denim shorts",
    "images": [
        "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/35d77e27300cf5e8995704cd858d759c.png"
    ],
    "videos": [
        "https://v4-kling.kechuangai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance_10s.mp4"
    ],
    "async": true
}'
```

要基于动作控制生成视频，需要设置 `action` 字段值为 `motion-control`，目前仅 2.6 和 3.0 版本支持该功能，其他模型设置该参数会报错。

### 自定义主体

可灵视频 3.0 支持通过自定义主体来生成视频，自定义主体可以实现基于参考图+参考视频+自定义音色生成视频。

你可以通过独立的主体管理API生成自定义主体进行引用，也可以在创建视频任务时一起提交主体素材，对于一次性任务这样更方便（自定义音色暂不支持自动转化，仍然需要通过独立的自定义音色接口获取音色ID）：

```bash theme={null}
curl --location 'http://localhost:9090/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-EiUld1Mu44RCopc4StjX0taJxyuKmvQ4FhOdaEVjs0QJxEVr' \
--data '{
    "model": "kling-video-v3",
    "prompt": "镜头逐渐环绕至女孩的正面，随后女孩抬起头，面向镜头温暖地微笑，仿佛出看见多年的好友",
    "extra_body": {
        "element_list": [
            {
                "name": "test",
                "description": "test",
                "reference_type": "image_refer",
                "image": "https://docs.qingque.cn/image/api/convert/loadimage?id=5429715788081310775fcACVlWX4tixUlJ4_9IB6cLY5&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true",
                "images": [
                    "https://docs.qingque.cn/image/api/convert/loadimage?id=-8171406105386702772fcADvwnhMxVe7ui5iW40e9ytI&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true",
                    "https://docs.qingque.cn/image/api/convert/loadimage?id=-2458305557636706550fcADvwnhMxVe7ui5iW40e9ytI&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true",
                    "https://docs.qingque.cn/image/api/convert/loadimage?id=-8983666481517966162fcADvwnhMxVe7ui5iW40e9ytI&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true"
                ]
            }
        ]
    },
    "async": true
}'
```

如果你想要通过独立的自定义主体接口获取主体ID，则需要调用自定义主体功能先创建主体：

```bash theme={null}
curl --location 'https://geekai.co/api/v1/elements/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "name": "test",
    "description": "test",
    "reference_type": "image_refer",
    "image": "https://docs.qingque.cn/image/api/convert/loadimage?id=5429715788081310775fcACVlWX4tixUlJ4_9IB6cLY5&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true",
    "images": [
        "https://docs.qingque.cn/image/api/convert/loadimage?id=-8171406105386702772fcADvwnhMxVe7ui5iW40e9ytI&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true",
        "https://docs.qingque.cn/image/api/convert/loadimage?id=-2458305557636706550fcADvwnhMxVe7ui5iW40e9ytI&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true",
        "https://docs.qingque.cn/image/api/convert/loadimage?id=-8983666481517966162fcADvwnhMxVe7ui5iW40e9ytI&docId=eZQCqDGoymg61UKgMckSB2oMh&identityId=2Cn18n4EIHT&loadSource=true"
    ],
    "platform": "kling"
}'
```

主体创建接口是一个异步接口，需要通过响应字段中获取的 `task_id` 调用自定义主体轮询接口获取主体生成结果：

```bash theme={null}
curl --location 'http://localhost:9090/api/v1/elements/{task_id}' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
```

当 `task_status` 值为 `succeed`， 表示生成成功，对应的生成结果数据结构如下：

```json theme={null}
{
    "task_id": "f886ca26-908b-4e26-9ffb-361694376bd7",
    "task_status": "succeed",
    "task_result": {
        "elements": [
            {
                "element_id": 317708663449203,
                "element_name": "test",
                "element_description": "test",
                "element_image_list": {
                    "frontal_image": "https://p4-kling.klingai.com/bs2/upload-ylab-stunt/muse/826925436873121851/IMAGE/20260803/397445ffd89d6c4c97ca4a0e77edab88-2f846b67-7dac-476e-90a8-4721006b19af?x-kcdn-pid=113274",
                    "refer_images": [
                        {
                            "image_url": "https://p4-kling.klingai.com/bs2/upload-ylab-stunt/muse/826925436873121851/IMAGE/20260803/d011e36b6110d27e2e9a35fddc6690df-abd1d09a-d804-4b67-8559-aed9f40fc77d?x-kcdn-pid=113274"
                        },
                        {
                            "image_url": "https://p4-kling.klingai.com/bs2/upload-ylab-stunt/muse/826925436873121851/IMAGE/20260803/d258b8655e67bb611346603e036ea770-271c8e7b-2b37-4e47-b87e-a3499ce4c107?x-kcdn-pid=113274"
                        },
                        {
                            "image_url": "https://p4-kling.klingai.com/bs2/upload-ylab-stunt/muse/826925436873121851/IMAGE/20260803/3b0a96d2a2ef050388bffbe027614f7f-dc5388b5-5ed4-4970-a978-08f3453cd9a7?x-kcdn-pid=113274"
                        }
                    ]
                },
                "status": "succeed"
            }
        ]
    }
}
```

`task_result.elements[0].element_id` 即为本次生成的主体 ID，你可以将其传入视频生成接口实现基于自定义主体创建视频：

```bash theme={null}
curl --location 'http://localhost:9090/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-EiUld1Mu44RCopc4StjX0taJxyuKmvQ4FhOdaEVjs0QJxEVr' \
--data '{
    "model": "kling-video-v3",
    "prompt": "镜头逐渐环绕至女孩的正面，随后女孩抬起头，面向镜头温暖地微笑，仿佛出看见多年的好友",
    "extra_body": {
        "element_list": [
            {
                "id": 317708663449203
            }
        ]
    },
    "async": true
}'
```

如果要基于参考视频生成自定义主体，则 `reference_type` 参数需要设置为 `video_refer` 同时通过 `videos` 字段传入参考视频 URL。

### 自定义音色

你可以通过自定义音色接口创建自定义音色用于在自定义主体时引用：

```bash theme={null}
curl --location 'https://geekai.co/api/v1/voices/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "name": "定制人声",
    "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/out.mp3",
    "platform": "kling"
}'
```

该接口也是异步接口，需要通过响应字段中获取的 `task_id` 调用自定义音色轮询接口获取音色生成结果：

```bash theme={null}
curl --location 'https://geekai.co/api/v1/voices/{task_id}' \
--header 'Authorization: Bearer $GEEKAI_API_KEY'
```

生成结果数据结构如下：

```json theme={null}
{
    "task_id": "dfa470a4-15b1-46e1-94c3-f05e0d3719a1",
    "task_status": "succeed",
    "task_result": {
        "voices": [
            {
                "voice_id": "913110442183659540",
                "voice_name": "定制人声",
                "trial_url": "https://v4-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/826925436873121851/AUDIO/20260803/824e0d209316c56bc79376e51334511f-ca312556-2b4b-4b54-8ee1-ec1a30af619e.quality.wav?x-kcdn-pid=113274"
            }
        ]
    }
}
```

### 视频分镜

可灵视频 3.0 支持通过 `extra_body` 参数来控制分镜能力，以下是一个多镜头图生视频示例：

```bash theme={null}
curl --location --request POST 'https://geekai.co/api/v1/videos/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $GEEKAI_API_KEY' \
--data '{
    "model":"kling-video-v3",
    "prompt":"她转身一笑，然后缓缓走出画面",
    "image":"https://static.geekai.co/storage/2025/11/14/woman_skyline_original_720p.jpeg",
    "duration": 8,
    "extra_body": {
        "multi_shot": true,
        "shot_type": "customize",
        "multi_prompt": [
            {
                "index": 1,
                "prompt": "第一镜头：她转身一笑",
                "duration": "3"
            },
            {
                "index": 2,
                "prompt": "第二镜头：她缓缓走出画面",
                "duration": "5"
            }
        ]
    },
    "async": true
}'
```