# 视频任务

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

视频生成是异步任务。创建任务后保存任务 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 风格视频

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A short cinematic product video",
    "size": "720x1280",
    "seconds": "4"
  }'
```

上传参考文件时使用 `multipart/form-data`，并把文件放到 `input_reference`。已生成的视频可以用 `POST /v1/videos/{video_id}/remix` 继续调整风格、节奏或镜头表现。

## 轮询任务

通用视频任务：

```bash
TASK_ID="task_xxx"

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

OpenAI 风格视频任务：

```bash
VIDEO_ID="video_abc123"

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、模型、请求参数摘要和最终文件地址。

## 常见模型和兼容接口

- 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 的“视频任务”接口组。