# Flux 3 Video

用 POST /v1/videos 调用 flux-3-video。按秒计费，只支持完整渲染。

`flux-3-video` 是 Black Forest Labs 的视频模型。创建任务后轮询查询，完成时读取返回的 `url`，或用 `GET /v1/videos/{id}/content` 下载视频。

```http
POST /v1/videos
GET /v1/videos/{task_id}
```

只支持完整渲染。按秒计费，特价版和官方版价格相同。没选的字段不要传。图片和视频只接受公网可直接访问的 URL，任务完成前不能过期。

## 价格

| 分辨率 | 无视频输入 | 有视频输入 |
| --- | ---: | ---: |
| 720p | ¥1.32 / 秒 | ¥1.848 / 秒 |
| 1080p | ¥2.112 / 秒 | ¥2.376 / 秒 |

有视频输入只看 `input_reference`。首帧、尾帧和 `images` 里的关键帧不改变单价。

## 请求参数

| 参数 | 必填 | 类型 | 范围 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | 是 | string | `flux-3-video` | 固定这个模型 ID |
| `prompt` | 否 | string | — | 画面描述。不传时必须有首帧，或传 `input_reference` |
| `resolution` | 是 | string | `720p`、`1080p`，或宽x高 | `720p` 对应 1280x720，`1080p` 对应 1920x1080。传宽x高时按短边归入这两档。不传按 720p |
| `duration` | 是 | integer | 5–20 | 整数秒。也可以用整数字符串传 `seconds`。小于 5 或大于 20 会被拒绝 |
| `image` | 否 | string | — | 首帧图。不能和 `input_reference` 同时传 |
| `end_frame` | 否 | string | — | 尾帧图。没有首帧会被拒绝。不能和 `input_reference` 同时传 |
| `images` | 否 | array | 1–10 | 关键帧。1 张是开头，2 张是开头和结尾，更多张会均匀排开。不能和 `input_reference` 同时传 |
| `input_reference` | 否 | string | mp4 | 一条视频续写。传入后按有视频单价计费。不能和图片同时传 |
| `aspect_ratio` | 否 | string | `21:9`、`2:1`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | 不传则由画面内容决定 |
| `audio` | 否 | boolean | — | 不传时生成音频。传 `false` 关闭 |
| `safety_tolerance` | 否 | integer | 0–4 | 内容尺度 |

## 文生视频

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "prompt": "a red circle moving across a lake",
    "resolution": "720p",
    "duration": 5
  }'
```

创建成功只返回任务，不返回视频文件：

```json
{
  "id": "task_example",
  "object": "video",
  "model": "flux-3-video",
  "status": "queued"
}
```

## 首尾帧

`images` 的第一张是首帧，第二张是尾帧。

```bash
curl https://kaienapi.com/v1/videos \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "prompt": "a smooth transition from the first frame to the last frame",
    "images": [
      "https://example.com/first.jpg",
      "https://example.com/last.jpg"
    ],
    "resolution": "720p",
    "duration": 5
  }'
```

## 查询

用创建时返回的任务 ID 查询。状态还是 `queued` 或 `in_progress` 时继续轮询，直到 `completed` 或 `failed`。

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

完成后的响应：

```json
{
  "id": "task_example",
  "object": "video",
  "model": "flux-3-video",
  "status": "completed",
  "url": "<file url>"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 任务号。用 `GET /v1/videos/{id}` 查询 |
| `status` | string | `queued` 排队，`in_progress` 处理中，`completed` 完成，`failed` 失败 |
| `url` | string | 完成时的成片地址 |

也可以下载视频二进制：

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