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

# Kling V4 视频生成

> 支持文生视频、图生视频、参考生视频、视频编辑和续写，输出 720p / 1080p 视频，生成时长 3–30 秒，始终带立体声音轨。

> [!NOTE]
>
> 本接口采用异步处理。提交后使用返回的 `task_id`，通过 `GET /v1/videos/generations/{task_id}` 查询任务状态和结果。

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v4",
    "prompt": "雨夜街道上一只纸船顺着水沟漂流，雨声淅沥",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/videos/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "kling-v4",
        "prompt": "雨夜街道上一只纸船顺着水沟漂流，雨声淅沥",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "kling-v4",
    prompt: "雨夜街道上一只纸船顺着水沟漂流，雨声淅沥",
    duration: 5,
    resolution: "720p",
    aspect_ratio: "9:16"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

## 模式选择

五种模式使用同一个模型名 `kling-v4`，根据传入的素材和 `omni_reference_task_type` 自动选择。

| 模式 | 传参方式 |
| - | - |
| 文生视频 | 不传图片、视频或音频素材 |
| 图生视频 | 提供首帧，可加尾帧和最多 8 张中间帧 |
| 参考生视频 | 传入 `video_urls`、`audio_urls`，或 `image_with_roles` 中包含 `reference_image`；也可显式设置 `omni_reference_task_type: "reference"` |
| 视频编辑 | 设置 `omni_reference_task_type: "edit"` 并提供输入视频 |
| 视频续写 | 设置 `omni_reference_task_type: "extend"` 并提供输入视频 |

`omni_reference_task_type` 默认为 `auto`，等同于不传。显式设置为 `reference` 时，`image_urls` 中的图片按参考图处理。

> [!WARNING]
>
> 只传 `video_url` 而未指定 `edit` 或 `extend` 会返回 HTTP 400。要将视频作为参考素材，请使用 `video_urls`。

## 请求头

**Authorization** `string` *required*

Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。

## 请求参数

**model** `string` *required*

固定为 `kling-v4`。

**prompt** `string`

描述要生成或编辑的内容。图生视频可省略，其余模式必填。

参考生视频可使用 `@Image1`、`@Video1`、`@Audio1` 引用素材，按各类素材数组的顺序从 1 开始编号。视频编辑中，输入视频为 `@Video1`，参考图为 `@Image1`、`@Image2` 等。

**duration** `integer`

生成时长，单位为秒，支持 `3`–`30`，默认 `5`。

* 视频编辑：不传时，输出时长跟随输入视频。
* 视频续写：表示新增片段的时长，返回原视频与新增片段拼接后的完整视频。

**resolution** `string` (default: 720p)

输出分辨率，支持 `720p` 和 `1080p`。请使用此字段选择分辨率，V4 不支持 `mode`。

**aspect\_ratio** `string`

支持 `16:9`、`9:16`、`1:1`、`21:9`；参考生视频额外支持 `auto`。

| 模式 | 默认行为 |
| - | - |
| 文生视频 | `16:9` |
| 图生视频 | 跟随首帧图片 |
| 参考生视频 | `auto` |
| 视频编辑 | 跟随输入视频 |
| 视频续写 | 不支持传入此字段，沿用原视频宽高比 |

**image\_urls** `string[]`

图片 URL 列表，含义取决于模式：

* 图生视频：第 1 张为首帧，第 2 张为尾帧，最多 2 张。
* 参考生视频、视频编辑：作为参考图，最多 10 张。仅使用参考图生成视频时，请显式设置 `omni_reference_task_type: "reference"`。

素材 URL 必须可公开访问。

**image\_with\_roles** `object[]`

带角色的图片列表，每项包含 `url` 和 `role`。

| `role` | 用途 |
| - | - |
| `first_frame` | 图生视频的首帧，必须恰好 1 张 |
| `last_frame` | 图生视频的尾帧，或视频续写的目标尾帧 |
| `keyframe` | 图生视频的中间帧，也接受 `middle_frame`，按数组顺序使用，最多 8 张 |
| `reference_image` | 参考生视频的参考图 |

图生视频的首帧、尾帧、中间帧合计最多 10 张。

**first\_frame\_image** `string`

图生视频的首帧图片 URL，也可通过 `image_with_roles` 的 `first_frame` 或 `image_urls` 第 1 张提供。

**last\_frame\_image** `string`

图生视频的尾帧图片 URL，或视频续写的目标尾帧图片 URL。

**video\_urls** `string[]`

参考生视频的参考视频列表，最多 5 段，合计最多使用 30 秒。

视频编辑或续写时，也可传入恰好 1 条视频 URL 代替 `video_url`，并指定 `omni_reference_task_type: "edit"` 或 `"extend"`。

**video\_url** `string`

视频编辑或续写的输入视频 URL，必须同时指定 `omni_reference_task_type: "edit"` 或 `"extend"`。

视频编辑的输入视频须至少 3 秒，不足 3 秒返回 HTTP 400；超过 30 秒时截取前 30 秒。

**audio\_urls** `string[]`

参考生视频的参考音频列表，最多 3 段，每段 5–30 秒。

参考生视频中，参考图、参考视频和参考音频合计最多 15 个素材。

**omni\_reference\_task\_type** `string` (default: auto)

支持 `auto`、`reference`、`edit`、`extend`。

* `auto`：根据素材自动选择文生、图生或参考生视频，等同于不传。
* `reference`：参考生视频，`image_urls` 中的图片按参考图处理。
* `edit`：视频编辑，需要输入视频。
* `extend`：视频续写，需要输入视频。

**audio\_setting** `string`

支持 `origin`（保留输入视频原声）和 `auto`（重新生成声音），仅用于视频编辑或带参考视频的参考生视频。

* 视频编辑：默认保留原声；设为 `auto` 时重新生成声音。
* 带参考视频的参考生视频：默认重新生成声音；设为 `origin` 时保留参考视频原声。
* 视频续写：不支持此字段，原视频声音保留，新增片段自动配声。

V4 始终生成带立体声音轨的视频，声音与画面一起生成。

## 请求示例

以下素材 URL 为占位示例，请替换为实际可公开访问的地址。

### 图生视频：首帧和尾帧

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "镜头缓缓推近",
  "image_urls": ["https://example.com/start.png", "https://example.com/end.png"]
}
```

第 1 张为首帧，第 2 张为尾帧。图生视频可不传 `prompt`。

### 图生视频：首帧、中间帧和尾帧

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "女孩从窗边走到门口，回头微笑",
  "image_with_roles": [
    {"url": "https://example.com/1.png", "role": "first_frame"},
    {"url": "https://example.com/2.png", "role": "keyframe"},
    {"url": "https://example.com/3.png", "role": "keyframe"},
    {"url": "https://example.com/4.png", "role": "last_frame"}
  ],
  "duration": 10
}
```

中间帧按数组顺序使用。必须恰好提供 1 张首帧，首帧、尾帧和中间帧合计最多 10 张。

### 参考生视频

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "@Image1 里的女孩跟着 @Video1 的运镜在海边奔跑，背景音乐用 @Audio1",
  "image_with_roles": [
    {"url": "https://example.com/girl.png", "role": "reference_image"}
  ],
  "video_urls": ["https://example.com/camera.mp4"],
  "audio_urls": ["https://example.com/bgm.mp3"],
  "aspect_ratio": "auto",
  "duration": 5
}
```

最多 10 张参考图、5 段参考视频、3 段参考音频，三类合计最多 15 个。参考视频合计最多使用 30 秒，每段参考音频为 5–30 秒。

### 视频编辑

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "把场景换成下雪的冬夜",
  "omni_reference_task_type": "edit",
  "video_url": "https://example.com/in.mp4",
  "image_urls": ["https://example.com/style.png"]
}
```

输入视频至少 3 秒，超过 30 秒时截取前 30 秒。不传 `duration` 和 `aspect_ratio` 时，输出时长和宽高比跟随输入视频。默认保留原声，可用 `audio_setting: "auto"` 重新生成声音。

### 视频续写

```json theme={null}
{
  "model": "kling-v4",
  "prompt": "镜头继续向前推进，天色渐暗",
  "omni_reference_task_type": "extend",
  "video_url": "https://example.com/in.mp4",
  "duration": 5
}
```

从输入视频最后一帧开始续写，返回原视频与新片段拼接后的完整视频，只按新片段时长计费。

可通过 `last_frame_image` 或 `image_with_roles` 中的 `last_frame` 提供目标尾帧。续写不支持 `aspect_ratio` 和 `audio_setting`。

## 查询任务

将提交响应中的任务 ID 替换到以下请求中：

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/videos/generations/<task_id>' \
  --header 'Authorization: Bearer <token>'
```

生成耗时参考：3 秒 720p 视频约 3 分钟，15 秒视频约 3.5 分钟。

## 计费

按秒计费，具体单价以[模型定价](https://apimart.ai/pricing)为准。`720p` 和 `1080p` 分别计价。

视频编辑与带参考视频的参考生视频使用视频输入单价，其他模式使用普通生成单价。

| 模式 | 计费秒数 |
| - | - |
| 文生视频、图生视频、仅带图片或音频的参考生视频 | 输出秒数 |
| 视频续写 | 新增片段秒数 |
| 视频编辑、带参考视频的参考生视频 | 输出秒数 + max(输出秒数, 输入视频秒数) |

输入视频秒数按各段时长相加后向上取整，最多计 30 秒。例如，编辑一段 3.04 秒的视频且不传 `duration`，输出为 4 秒，计费为 4 + 4 = 8 秒。

视频编辑与带参考视频的参考生视频会在提交时探测输入视频时长，探测失败直接返回 HTTP 400，不扣费。生成失败全额退款。

## 不支持的参数

以下参数或取值会返回 HTTP 400：

* `mode`：V4 没有 `std`、`pro` 或 `4k` 档位，请使用 `resolution`。
* `negative_prompt`、`watermark: true`、`audio: false`。
* `multi_shot`、`multi_prompt`、`element_list`、`video_list`。
* `camera_control`、`voice_list`。

## 常见错误

| 报错 | 处理方式 |
| - | - |
| `video_url needs omni_reference_task_type edit ... or extend` | 使用 `video_url` 时明确指定 `edit` 或 `extend`；参考视频请使用 `video_urls` |
| `image-to-video requires exactly 1 first frame` | 恰好提供 1 张首帧，不能只传尾帧或中间帧 |
| `first frame, last frame and keyframes together are at most 10 images` | 将首帧、尾帧和中间帧总数减少至最多 10 张 |
| `reference images, videos and audios together are at most 15 files` | 将参考素材总数减少至最多 15 个 |
| `video edit requires an input video of at least 3 seconds` | 使用至少 3 秒的输入视频 |
| `Failed to probe the input video duration` | 检查 URL 是否可访问，内容是否为有效视频文件 |
| `has no std/pro/4k mode` | 移除 `mode`，使用 `resolution` |
| `Could not download the input from ... (HTTP 403)` | 替换为无防盗链、可公开访问的素材地址 |


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