> ## 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 Flash 视频生成

> 支持文生视频、单张首帧图生视频、图像与视频参考、视频编辑和续写；仅输出 720p，生成时长 3–20 秒，24fps。

> [!NOTE]
>
> 本接口采用异步处理。提交后使用返回的 `task_id`，通过 `GET /v1/tasks/{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-flash",
    "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-flash",
        "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-flash",
    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-flash`，根据传入的素材和 `omni_reference_task_type` 自动选择。

| 模式 | 传参方式 |
| - | - |
| 文生视频 | 不传图片、视频或音频素材 |
| 图生视频 | 只提供一张首帧：`first_frame_image`、`image_with_roles` 的 `first_frame`，或 `image_urls` 的唯一一张图片 |
| 参考生视频 | 传入 `video_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-flash`。

**prompt** `string`

描述要生成或编辑的内容。图生视频可省略，其余模式必填。参考生视频使用 `@Image1` / `@Video1` 指代素材，按各类数组顺序从 1 编号。编辑时输入视频为 `@Video1`，参考图为 `@Image1`、`@Image2` 等。

**duration** `integer`

整数秒 `3`–`20`，通常默认 `5`。编辑不传时，跟随输入视频时长并向上取整；续写表示新增片段时长。显式传 `0` 返回 HTTP 400，`null` 等同不传。按此整数时长计费，实际成片可能多约 1 帧。

**seconds** `integer`

`duration` 的别名，规则相同。同时传入两个值时，两者都必须在 `3`–`20` 内且相等，否则返回 HTTP 400。

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

仅支持 `720p`，默认可省略。传 `1080p` 返回 HTTP 400；不支持通过 `mode` 选择档位。

**aspect\_ratio** `string`

文生视频、参考生视频和编辑支持 `16:9`、`9:16`、`1:1`、`21:9`；只有参考生视频支持 `auto`。图生视频不支持 `aspect_ratio` 或 `size`，非空值会返回 HTTP 400；空字符串视为不传。需要其他比例时，请先裁剪首帧。

| 模式 | 默认行为 |
| - | - |
| 文生视频 | `16:9` |
| 图生视频 | 不支持 `aspect_ratio` / `size`，跟随首帧；需要其他比例时先裁图 |
| 参考生视频 | `auto` |
| 视频编辑 | 跟随输入视频 |
| 视频续写 | 不支持传入此字段，沿用原视频宽高比 |

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

图生视频只能传一张首帧；传两张会返回 HTTP 400。参考生视频和编辑模式下为参考图，最多 10 张。仅使用图片作为参考素材时，显式设置 `omni_reference_task_type: "reference"`。素材 URL 必须可公开访问。首帧和参考图的宽、高均须至少 300px，宽高比须在 2:5–5:2 之间；不满足时提交返回 HTTP 400，不扣费。

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

每项包含 `url` 和 `role`。图生视频只接受恰好一张 `first_frame`；参考生视频和编辑使用 `reference_image`。不支持尾帧或中间帧。参考图最多 10 张，与参考视频合计最多 15 个素材。首帧和参考图的宽、高均须至少 300px，宽高比须在 2:5–5:2 之间；不满足时提交返回 HTTP 400，不扣费。

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

图生视频的首帧图片 URL，也可通过 `image_with_roles` 的 `first_frame` 或 `image_urls` 第 1 张提供。首帧和参考图的宽、高均须至少 300px，宽高比须在 2:5–5:2 之间；不满足时提交返回 HTTP 400，不扣费。

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

参考视频数组，最多 5 段，合计时长不超过 20 秒；超限直接返回 HTTP 400，不截取。编辑和续写也可传恰好 1 条代替 `video_url`，并显式设置对应任务类型。

参考视频仅支持 MP4 / MOV，宽、高均须在 700–4553px 范围内。时长按视频流计算，不按容器时长；每段至少 3 秒，合计不超过 20 秒。任一参考视频不足 3 秒时，提交返回 HTTP 400，不扣费。

**video\_url** `string`

编辑或续写的输入视频 URL，必须显式设置 `omni_reference_task_type: "edit"` 或 `"extend"`，否则返回 HTTP 400。编辑输入须为 3–20 秒；不足 3 秒或超过 20 秒会直接拒绝，不扣费。

编辑视频仅支持 MP4 / MOV，宽、高均须在 700–4553px 范围内；3–20 秒按视频流时长判断，不按容器时长。格式、宽高或编辑时长不符合要求时，提交返回 HTTP 400，不扣费。

续写输入不受编辑模式的视频高度范围和 3 秒下限限制，例如 480p、2 秒的视频可以续写。

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

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

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

**audio\_setting** `string`

用于带参考视频的参考生视频：`origin` 保留第一段参考视频的原声，`auto` 重新生成声音，默认 `auto`。`origin` 必须配合参考视频；若第一段参考视频没有音轨，输出也没有音轨。编辑会重新生成声音，不保留原声，编辑请求请省略该参数。续写不支持此字段。

## 输出尺寸与帧率

输出使用 `720p` 档位，实际像素随比例变化，成片为 24fps。实际时长可能比 `duration` 多约 1 帧，例如请求 3 秒，成片约 3.04 秒。

| 比例 / 模式 | 实际像素 |
| - | - |
| `16:9` | 1280×720 |
| `9:16` | 720×1280 |
| `1:1` | 960×960 |
| `21:9` | 1464×628 |
| 图生视频 | 跟随首帧比例，总像素约 0.92MP；例如 1:2.5 首帧输出 604×1516 |

## 请求示例

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

### 图生视频：单张首帧

```json theme={null}
{
  "model": "kling-v4-flash",
  "image_urls": [
    "https://example.com/start.png"
  ]
}
```

只提供一张首帧即可，`prompt` 可省略。不支持尾帧、中间帧或两张首帧图片。

不支持 `aspect_ratio` / `size`，跟随首帧；需要其他比例时先裁图。

首帧和参考图的宽、高均须至少 300px，宽高比须在 2:5–5:2 之间；不满足时提交返回 HTTP 400，不扣费。

### 参考生视频

```json theme={null}
{
  "model": "kling-v4-flash",
  "prompt": "The girl in @Image1 runs along the beach with the camera movement from @Video1.",
  "image_with_roles": [
    {
      "url": "https://example.com/girl.png",
      "role": "reference_image"
    }
  ],
  "video_urls": [
    "https://example.com/camera.mp4"
  ],
  "aspect_ratio": "auto",
  "duration": 5
}
```

参考图最多 10 张、参考视频最多 5 段，合计最多 15 个素材；参考视频总时长不超过 20 秒。不支持参考音频。需要保留第一段参考视频的声音时，添加 `audio_setting: "origin"`。使用 `origin` 时，若第一段参考视频没有音轨，输出也没有音轨。

首帧和参考图的宽、高均须至少 300px，宽高比须在 2:5–5:2 之间；不满足时提交返回 HTTP 400，不扣费。

参考视频仅支持 MP4 / MOV，宽、高均须在 700–4553px 范围内。时长按视频流计算，不按容器时长；每段至少 3 秒，合计不超过 20 秒。任一参考视频不足 3 秒时，提交返回 HTTP 400，不扣费。

### 视频编辑

```json theme={null}
{
  "model": "kling-v4-flash",
  "prompt": "Change the scene to a snowy winter night.",
  "omni_reference_task_type": "edit",
  "video_url": "https://example.com/in.mp4",
  "image_urls": [
    "https://example.com/style.png"
  ]
}
```

编辑输入须为 3–20 秒，按视频流时长判断。不传 `duration` 时输出时长按输入时长向上取整，不传 `aspect_ratio` 时跟随输入视频。编辑会重新生成声音，不保留原视频声音；请求中请省略 `audio_setting`。

首帧和参考图的宽、高均须至少 300px，宽高比须在 2:5–5:2 之间；不满足时提交返回 HTTP 400，不扣费。

编辑视频仅支持 MP4 / MOV，宽、高均须在 700–4553px 范围内；3–20 秒按视频流时长判断，不按容器时长。格式、宽高或编辑时长不符合要求时，提交返回 HTTP 400，不扣费。

### 视频续写

```json theme={null}
{
  "model": "kling-v4-flash",
  "prompt": "The camera continues moving forward as the sky grows darker.",
  "omni_reference_task_type": "extend",
  "video_url": "https://example.com/in.mp4",
  "duration": 5
}
```

从输入视频最后一帧开始生成 3–20 秒的新片段，只返回新生成的片段，不包含原视频，按新片段时长计费。续写不接受图片或目标尾帧，也不支持 `aspect_ratio`、`audio_setting`，宽高比沿用原视频。

续写输入不受编辑模式的视频高度范围和 3 秒下限限制，例如 480p、2 秒的视频可以续写。

## 查询任务

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

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

通过[任务查询接口](https://docs.apimart.ai/cn/api-reference/tasks/status.md)查询，保存 `task_id` 并持续查询到 `completed` 或 `failed`。720p、3 秒视频实测约 1–4 分钟出结果，仅供参考；不要因达到固定等待时长就判断任务失败。

## 计费

按秒计费，具体单价以[模型定价](https://apimart.ai/pricing)为准。普通生成与视频输入使用不同价目。

| 模式 | 计费秒数 |
| - | - |
| 文生视频、图生视频、仅图片参考生视频 | 输出秒数；`kling-v4-flash@720P` |
| 视频续写 | 新增片段秒数；`kling-v4-flash@720P` |
| 视频编辑、带参考视频的参考生视频 | 输出秒数 + max(输出秒数, 输入视频秒数)；`kling-v4-flash@720P-input` |

输入视频秒数按各段视频流时长相加后向上取整，不按容器时长。例如编辑 3.04 秒的视频并传 `duration: 3`，计费为 3 + 4 = 7 秒。编辑和带参考视频的参考生视频在提交时会探测格式、宽高和视频流时长；探测失败、非 MP4 / MOV、宽或高不在 700–4553px、总时长超过 20 秒，或编辑输入不足 3 秒时，返回 HTTP 400，不扣费。参考视频每段按视频流时长判断，不足 3 秒时提交返回 HTTP 400，不扣费。

任务失败全额退款，平台判定超时也按失败退款。客户端停止查询不会取消任务；任务之后成功，仍正常计费。

## 不支持的参数

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

* `resolution: "1080p"`
* `last_frame_image`, `role: "last_frame"`, `role: "keyframe"`
* `audio_urls`, `audio_url`
* `mode`, `negative_prompt`, `watermark: true`, `audio: false`
* `multi_shot`, `multi_prompt`, `element_list`, `video_list`
* `camera_control`, `voice_list`

## 常见错误

| 报错 | 处理方式 |
| - | - |
| `kling-v4-flash only supports resolution 720p (got: 1080p)` | 使用 `720p`，不要传 `1080p`。 |
| `kling-v4-flash duration must be between 3 and 20 seconds` | `duration` / `seconds` 使用 3–20 的整数；不要传 0。 |
| `kling-v4-flash image-to-video follows the first frame's aspect ratio; remove aspect_ratio / size` | 图生视频移除 `aspect_ratio` 和 `size`；比例跟随首帧，需要其他比例时先裁图。 |
| `kling-v4-flash first frame: image width and height must be at least 300px` | 首帧或参考图宽、高均须至少 300px。 |
| `kling-v4-flash first frame: image aspect ratio (width:height) must be between 2:5 and 5:2` | 将图片宽高比调整到 2:5–5:2 之间。 |
| `kling-v4-flash input video #1: unsupported video format webm/mkv (supported: mp4/mov)` | 编辑或参考视频使用 MP4 / MOV，不支持 WebM / MKV。 |
| `kling-v4-flash input video #1: video height must be between 700 and 4553px` | 编辑或参考视频的宽、高均须在 700–4553px；此范围不适用于续写输入。 |
| `kling-v4-flash input video #1: video width must be between 700 and 4553px` | 编辑或参考视频的宽、高均须在 700–4553px；竖屏视频宽度也须至少 700px。 |
| `kling-v4-flash reference video #1 must be at least 3 seconds` | 每段参考视频按视频流时长判断，须至少 3 秒；不足时提交返回 HTTP 400，不扣费。 |
| `kling-v4-flash only supports aspect_ratio 16:9, 9:16, 1:1 or 21:9 (got: auto)` | 只有参考生视频支持 `auto`；图生视频应省略比例字段。 |
| `kling-v4-flash image-to-video only takes a first frame; last frame and keyframes are not supported` | 只保留一张首帧，移除尾帧、中间帧或第二张图片。 |
| `kling-v4-flash reference-to-video does not take reference audios` | 移除 `audio_urls` / `audio_url`。 |
| `kling-v4-flash video extend takes no images` | 续写请求移除图片及目标尾帧。 |
| `kling-v4-flash input videos must be at most 20 seconds in total` | 参考视频总时长或编辑输入不得超过 20 秒，不会自动截取。 |
| `video edit requires an input video of at least 3 seconds` | 编辑使用视频流时长至少 3 秒的输入；不是按容器时长判断。 |
| `video_url needs omni_reference_task_type edit ... or extend` | 明确指定 `edit` / `extend`；参考视频放入 `video_urls`。 |
| `Failed to probe the input video duration` | 检查输入 URL 能否访问且内容是否为有效视频。 |
| `duration (3) and seconds (5) are aliases and must match` | 只传一个别名，或让两个值相同且都在 3–20 内。 |


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