# 视频任务

提交文生视频、图生视频、查询任务状态，并下载最终视频文件。

视频生成是异步任务。创建任务后保存任务 ID，再轮询查询状态；任务完成后读取结果 URL，或下载视频文件并转存到自己的对象存储。

通用视频任务优先使用：

```http
POST /v1/video/generations
```

OpenAI 风格视频接口使用：

```http
POST /v1/videos
```

这两组接口都会返回任务对象，不会在创建请求里直接返回最终视频文件。

## 文生视频

```bash
curl https://kaienapi.com/v1/video/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2-master",
    "prompt": "一支 5 秒的产品展示短片，镜头缓慢推进，背景干净",
    "duration": 5,
    "size": "1280x720"
  }'
```

`prompt` 应说明主体、动作、镜头运动、画面环境和比例。不同模型对 `duration`、`size`、`aspect_ratio`、`resolution`、`mode` 的支持不同，接入前先用 `/v1/models` 确认可用模型 ID。

## 图生视频

```bash
curl https://kaienapi.com/v1/video/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2-master",
    "prompt": "让图片中的人物缓慢转身并看向镜头",
    "image": "https://example.com/portrait.png",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

参考图建议使用公网可访问的 OSS 或 CDN URL，并确保任务执行期间不会过期。多图、首尾帧、参考视频和参考音频字段以具体模型说明和 API Reference 为准。

## OpenAI 风格视频

以下特价版视频模型统一使用 `POST /v1/videos`，公开文档只推荐 `application/json`：

| 模型 | 适用方式 | 固定单次价格 |
| --- | --- | ---: |
| `omni_flash-10s` | 10 秒 720p，支持文生视频、最多 7 个参考图片，以及视频修改 | 1.1 |
| `veo_3_1-fast` | 文生视频、参考图视频 | 0.7 |
| `veo_3_1-lite-fl` | Lite 首尾帧视频，`images` 依次传首帧和尾帧 | 0.72 |
| `veo_3_1-fast-fl-hd` | Fast HD 首尾帧视频，`images` 依次传首帧和尾帧 | 0.88 |

### 文生视频

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash-10s",
    "prompt": "一只可爱的小猫在花园里玩耍，镜头缓慢向前推进",
    "size": "1280x720"
  }'
```

`omni_flash-10s` 的时长和 720p 档位已经包含在模型规格中，不需要额外传 `duration`。

### 图生视频

参考图片通过 JSON 的 `images` 数组传入：

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo_3_1-fast",
    "prompt": "根据参考图生成一段自然的产品展示视频",
    "size": "1280x720",
    "images": [
      "https://example.com/reference-1.jpg",
      "https://example.com/reference-2.jpg"
    ]
  }'
```

图片 URL 必须是公网可访问的文件直链，且在任务执行期间不能过期。

### 视频修改

`omni_flash-10s` 可以把公网视频直链放入 `images`，再通过 `prompt` 描述修改目标：

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash-10s",
    "prompt": "保持原视频主体和动作，把整体风格调整为明亮的商业广告",
    "size": "1280x720",
    "images": [
      "https://example.com/source-video.mp4"
    ]
  }'
```

### 首尾帧视频

模型名包含 `-fl` 时，`images[0]` 是首帧，`images[1]` 是尾帧：

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo_3_1-fast-fl-hd",
    "prompt": "让首尾画面自然过渡，保持人物和产品外观一致",
    "size": "1920x1080",
    "images": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ]
  }'
```

`veo_3_1-lite-fl` 使用相同的 JSON 结构，将 `model` 改为 `veo_3_1-lite-fl` 即可。只有一张参考图时，只传一个数组元素。不要把 `images` 写成单个字符串。

## 轮询任务

通用视频任务：

```bash
TASK_ID="task_xxx"

curl "https://kaienapi.com/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

OpenAI 风格视频任务：

```bash
VIDEO_ID="task_xxx"

curl "https://kaienapi.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

前端或服务端轮询时，只在成功或失败这类终态停止。任务仍在排队或运行时继续等待，并展示处理中状态。网络请求临时失败时等待下一轮继续查询，不要立即重复创建新任务。

## 下载结果

任务完成后下载视频内容：

```bash
curl "https://kaienapi.com/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  --output result.mp4
```

这个接口返回视频二进制，不是 JSON。浏览器端可以转成 Blob 播放或下载；服务端建议下载后转存到自己的对象存储，并在业务数据里保存任务 ID、模型、请求参数摘要和最终文件地址。

## 常见模型和兼容接口

- `omni_flash-10s`、`veo_3_1-fast`、`veo_3_1-lite-fl` 和 `veo_3_1-fast-fl-hd` 走 `/v1/videos` 和 `/v1/videos/{video_id}`。
- Sora 等其他 OpenAI 风格模型通常也走 `/v1/videos`、`/v1/videos/{video_id}` 和 `/v1/videos/{task_id}/content`。
- Kling、Veo、Seedance 等模型可走通用 `/v1/video/generations`。
- 豆包 Seedance 也支持火山方舟 Ark SDK 风格的 `/api/v3/contents/generations/tasks`。
- Kling 原生路径还包括 `/kling/v1/videos/text2video` 和 `/kling/v1/videos/image2video`。

具体参数、请求示例和返回结构见 API Reference 的“视频任务”接口组。