> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Kling-v3.0 视频生成
> Kling Video 3.0 支持最长 15 秒视频生成，提供多镜头控制、原生音频和更稳定的主体一致性。
## 概览
Kling Video 3.0 可将文本描述或静态图片生成最高 4K 的视频片段。模型支持生成 3 到 15 秒的视频，相比早期版本 10
秒的上限有明显提升。它可以在一次生成中处理写实场景、风格化内容，以及复杂的多步骤动作。
你也可以在生成视频的同时生成原生音频，包括带口型同步的对白、音效和环境声。
## 关键规则
* 每次请求都必须传入 `multi_shots`。
* 当 `multi_shots` 为 `true` 时：
* `img_urls` 必须且只能包含 1 张图片。
* `audio` 会被强制设为 `true`。
* `shot_type` 用于控制多镜头生成模式：
* `customize`：需要传入 `multi_prompt`
* `intelligence`：需要传入 `prompt`
* 当 `shot_type` 为 `customize` 时，所有 `multi_prompt` 镜头时长之和必须严格等于 `duration`。
* 单镜头模式下，`img_urls` 支持传入 1 张起始帧，或传入 2 张图片进行首尾帧控制。
* 如果提供了 `img_urls`，`aspect_ratio` 会被忽略，输出视频会跟随第一张图片的宽高比。
* 多镜头模式下，`audio` 会被强制设为 `true`。
* `element_list` 最多支持 3 个元素，每个元素可接收 1 到 4 张参考图片。
## 使用方式
### 文生视频
描述你希望看到的画面。模型会根据描述生成视频画面，并可选择同时生成音频。
**使用示例**：
```json theme={null} theme={null}
{
"model": "kling/v3",
"input": {
"mode": "std",
"multi_shots": false,
"prompt": "An astronaut floats alone in deep space, Earth glowing blue behind them, camera slowly rotating around their helmet reflecting the stars.",
"duration": 10,
"aspect_ratio": "16:9",
"audio": true
}
}
```
### 图生视频
上传一张起始图片，并描述你希望生成的运动效果。你也可以提供一张结束图片，用于控制视频最终过渡到的画面。
**使用示例**：
```json start image theme={null} theme={null}
{
"model": "kling/v3",
"input": {
"mode": "std",
"multi_shots": false,
"prompt": "Cinematic drone footage of a dragon made of living fire soaring over a frozen Nordic fjord at twilight.",
"img_urls": [
"https://example.com/start_image.jpg"
],
"duration": 15,
"audio": true
}
}
```
```json first-last-frame theme={null} theme={null}
{
"model": "kling/v3",
"input": {
"mode": "pro",
"multi_shots": false,
"prompt": "The robot slowly repairs itself and stands up ready for battle.",
"img_urls": [
"https://example.com/start-frame.jpg",
"https://example.com/end-frame.jpg"
],
"duration": 15,
"audio": true
}
}
```
## 多镜头模式
对于包含多个场景的视频，请将 `multi_shots` 设置为 `true`。
多镜头模式支持两种生成方式：
### 校验规则
* 当 `multi_shots=true` 且 `shot_type=customize` 时：
* 必须传入 `multi_prompt`
* 所有镜头时长总和必须等于 `duration`
* 当 `multi_shots=true` 且 `shot_type=intelligence` 时：
* 必须传入 `prompt`
* 不应再传入 `multi_prompt`
* 当 `multi_shots=false` 时：
* `shot_type` 会自动设置为 `null`
### 1. 自定义分镜模式
使用 `shot_type="customize"` 并配合 `multi_prompt` 手动定义每个镜头。
`multi_prompt` 需要传入一个 JSON 数组，每个元素定义一个镜头，并包含该镜头的提示词和时长。
最多可定义 6 个镜头，每个镜头时长至少为 1 秒。所有镜头时长之和必须等于 `duration` 参数。
### 使用示例
```json theme={null}
{
"model": "kling/v3",
"input": {
"mode": "pro",
"multi_shots": true,
"shot_type": "customize",
"img_urls": [
"https://example.com/reference-start.jpg"
],
"multi_prompt": [
{
"prompt": "Wide shot of the explorer entering a ruined temple.",
"duration": 4
},
{
"prompt": "Medium shot as the explorer lifts a glowing relic and dust falls from the ceiling.",
"duration": 6
}
],
"duration": 10,
"audio": true
}
}
```
### 2. 智能分镜模式
使用 `shot_type="intelligence"` 并配合单个 `prompt`。
模型会自动理解提示词内容，并智能生成多个电影化镜头与转场。
### 使用示例
```json theme={null}
{
"model": "kling/v3",
"input": {
"mode": "std",
"multi_shots": true,
"shot_type": "intelligence",
"img_urls": [
"https://example.com/reference-start.jpg"
],
"prompt": "A lone samurai walks through a rainy cyberpunk city, neon reflections glowing on wet streets, cinematic atmosphere, dramatic camera transitions.",
"duration": 10,
"audio": true
}
}
```
### 元素参考
在 `element_list` 数组中定义元素后，可以在提示词中使用 `@element_name` 语法引用对应图片。
```json single-shot with element reference theme={null} theme={null}
{
"model": "kling/v3",
"input": {
"mode": "pro",
"multi_shots": false,
"prompt": "In a bright rehearsal room, sunlight streams through the window @element_dog",
"img_urls": [
"https://example.com/reference_room.png"
],
"element_list": [
{
"name": "element_dog",
"description": "dog",
"name": "hero",
"description": "A young explorer wearing a yellow raincoat.",
"element_image_urls": [
"https://example.com/element_dog_1.png",
"https://example.com/element_dog_2.png"
]
}
],
"duration": 10,
"audio": true
}
}
```
```json multi-shot with element reference theme={null} theme={null}
{
"model": "kling/v3",
"input": {
"mode": "pro",
"multi_shots": true,
"shot_type": "customize",
"multi_prompt": [
{
"prompt": "a happy dog in running @element_dog",
"duration": 3
},
{
"prompt": "a happy dog play with a cat @element_cat",
"duration": 3
}
],
"element_list": [
{
"name": "element_cat",
"description": "cat",
"element_image_urls": [
"https://example.com/element_cat.png"
]
},
{
"name": "element_dog",
"description": "dog",
"element_image_urls": [
"https://example.com/element_dog_1.png",
"https://example.com/element_dog_2.png"
]
}
],
"duration": 6,
"aspect_ratio": "9:16",
"audio": true
}
}
```
## 查询任务状态
提交任务后，请使用统一查询接口查看进度并获取结果：
了解如何查询任务状态并获取生成结果
生产环境中，建议使用 `callback_url` 参数接收任务完成后的自动通知，而不是轮询状态接口。
## 相关资源
查看所有可用模型
查询账户剩余积分
## OpenAPI
````yaml zh/models/kling/v3-0.json post /api/v1/client/job/CreateTask
openapi: 3.0.0
info:
title: Kling V3 API
description: crun.ai Kling V3 API 文档
version: 1.0.0
contact:
name: Technical Support
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API 服务器
security:
- ApiKeyAuth: []
paths:
/api/v1/client/job/CreateTask:
post:
summary: Kling-v3.0 视频生成
operationId: kling/v3
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- kling/v3
description: |-
用于生成的模型名称，必填。
- 此接口必须使用 `kling/v3`
callback_url:
type: string
format: uri
description: |-
可选。用于接收任务完成通知的回调 URL。
- 生成完成后，系统会向该 URL POST 任务状态和结果
- 回调 payload 结构与任务状态查询接口返回的 `data` 对象一致
- 您的回调接口应支持接收包含结果的 JSON POST 请求
- 成功接收后应返回 HTTP 200 状态码
example: https://your-domain.com/api/callback
input:
type: object
description: Kling V3 高阶视频生成任务的输入参数。支持标准 / 专业模式、多镜头序列、智能分镜和精细元素控制。
properties:
mode:
type: string
description: '`std` 生成 720p，`pro` 生成 1080p。`4K` 输出视频分辨率为 4K。'
enum:
- std
- pro
- 4K
default: std
example: pro
multi_shots:
type: boolean
description: 是否使用多镜头模式。`true` 启用多镜头模式，`false` 启用单镜头模式。
shot_type:
type: string
description: >-
控制多镜头生成方式。`customize` 表示手动分镜模式，需要传入
`multi_prompt`；`intelligence` 表示 AI 智能分镜模式，需要传入
`prompt`，模型会自动拆分镜头。
enum:
- customize
- intelligence
default: customize
example: customize
prompt:
type: string
description: >-
文本提示词。当 `multi_shots=false` 时必填；当 `multi_shots=true` 且
`shot_type=intelligence` 时也必须提供。
maxLength: 2500
img_urls:
type: array
description: >-
可选输入图片。单镜头模式可提供 1 张起始帧，或提供 2 张图片进行首尾帧控制；多镜头模式必须提供且仅提供 1
张起始帧。
items:
type: string
format: uri
maxItems: 2
example:
- https://example.com/start-frame.jpg
- https://example.com/end-frame.jpg
multi_prompt:
type: array
description: >-
当 `multi_shots=true` 且 `shot_type=customize` 时必填。最多提供 6
个镜头定义，所有镜头时长之和必须等于 `duration`。
maxItems: 6
items:
type: object
properties:
prompt:
type: string
description: 该镜头的提示词。
minLength: 1
maxLength: 500
example: >-
Close-up of the main character taking a deep
breath.
duration:
type: integer
description: 该镜头的时长，单位为秒。
minimum: 1
maximum: 15
example: 3
required:
- prompt
- duration
element_list:
type: array
description: 可选元素一致性参考。最多支持 3 个元素，每个元素可使用 1 到 4 张参考图片。
maxItems: 3
items:
type: object
properties:
name:
type: string
description: 元素名称，可在提示词中使用，例如 `@hero`。
maxLength: 50
example: hero
description:
type: string
description: 元素描述。
maxLength: 500
example: A young explorer wearing a yellow raincoat.
element_image_urls:
type: array
description: 该元素的参考图片。请提供 1 到 4 个图片 URL。
items:
type: string
format: uri
minItems: 1
maxItems: 4
example:
- https://example.com/element_dog_1.jpeg
- https://example.com/element_dog_2.jpeg
required:
- name
- description
example:
- name: element_dog
description: dog
element_image_urls:
- https://example.com/element_dog_1.jpeg
- https://example.com/element_dog_2.jpeg
- name: element_cat
description: cat
element_image_urls:
- https://example.com/element_cat.png
audio:
type: boolean
description: 是否生成音频。当 `multi_shots=true` 时，该字段会强制为 `true`。
default: false
example: true
duration:
type: integer
description: 视频时长，单位为秒。
minimum: 3
maximum: 15
default: 5
example: 10
aspect_ratio:
type: string
enum:
- '1:1'
- '16:9'
- '9:16'
default: '16:9'
description: 生成视频的宽高比。提供 `img_urls` 时，该字段会被忽略，输出视频会跟随第一张图片的宽高比。
example: '16:9'
input_compliance:
type: string
description: 可选输入合规检测设置。
enum:
- disabled
- enabled
example: enabled
output_compliance:
type: string
description: 可选输出合规检测设置。
enum:
- disabled
- enabled
example: enabled
required:
- multi_shots
example:
model: kling/v3
callback_url: https://your-domain.com/api/callback
input:
mode: pro
multi_shots: true
shot_type: customize
img_urls:
- https://example.com/reference-start.jpg
multi_prompt:
- prompt: Wide shot of the explorer entering a ruined temple.
duration: 4
- prompt: >-
Medium shot as @hero lifts a glowing relic and dust falls
from the ceiling.
duration: 6
element_list:
- name: hero
description: A young explorer wearing a yellow raincoat.
element_image_urls:
- https://example.com/hero-1.jpg
- https://example.com/hero-2.jpg
duration: 10
audio: true
input_compliance: enabled
output_compliance: enabled
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
task_id:
type: string
description: 任务 ID，可用于通过任务详情接口查询任务状态
example: task_12345678
example:
code: 200
message: success
data:
task_id: task_12345678
'422':
description: 参数校验错误
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
errors:
type: array
description: 详细的参数校验错误信息
items:
type: string
example:
- specific error field message
example:
code: 422
message: Missing Params or Type Error
errors:
- specific error field message
'500':
$ref: '#/components/responses/Error'
components:
schemas:
ApiResponse:
type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 422
- 429
- 455
- 500
- 501
- 505
description: |-
响应状态码
- **200**：成功，请求已成功处理
- **401**：未授权，身份验证凭证缺失或无效
- **402**：积分不足，账户积分不足以执行本次操作
- **404**：未找到，请求的资源或接口不存在
- **422**：参数校验错误，请求参数未通过校验
- **429**：触发速率限制，请求频率已超过当前资源限制
- **455**：服务不可用，系统正在维护
- **500**：服务器错误，处理请求时发生意外错误
- **501**：生成失败，内容生成任务失败
- **505**：功能已禁用，请求的功能当前不可用
message:
type: string
description: 响应消息；失败时为错误说明
example: success
responses:
Error:
description: 服务器错误
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: |-
所有 API 都需要通过 API Key 进行身份验证。
获取 API Key：
1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取您的 API Key
使用方式：
添加到请求头：
x-api-key: YOUR_API_KEY
注意：
- 请妥善保管您的 API Key，不要与他人共享
- 如果怀疑 API Key 已泄露，请立即在管理页面重置
````