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

# omni-fast 视频生成

> 使用 omni-fast 模型生成视频 — 支持文生视频、图生视频、首尾帧插值、参考视频编辑

## 模型信息

| 模型          | 计费方式 | 说明              |
| ----------- | ---- | --------------- |
| `omni-fast` | 按次计费 | 快速视频生成，支持多种输入模式 |

## 创建视频任务

### 文生视频

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic",
    "seconds": "8",
    "aspect_ratio": "16:9"
  }'
```

### 图生视频 (I2V)

通过 `first_image_url` 提供首帧参考图：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "The scene comes alive with gentle wind and drifting clouds",
    "first_image_url": "https://example.com/start_frame.jpg",
    "seconds": "8"
  }'
```

支持 `data:image/jpeg;base64,...` 格式直接上传图片。

### 首尾帧插值

同时提供首帧和尾帧，生成平滑过渡视频：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "Smooth cinematic transition between the two frames",
    "first_image_url": "data:image/jpeg;base64,...",
    "last_image_url": "data:image/jpeg;base64,...",
    "seconds": "8",
    "aspect_ratio": "16:9"
  }'
```

### 多参考图视频 (R2V)

通过 `images[]` 传入多张参考图（最多 5 张）：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "Use the first image as character reference, second as style reference. Create a cozy cafe scene.",
    "images": [
      "data:image/jpeg;base64,...",
      "data:image/jpeg;base64,..."
    ],
    "seconds": "8"
  }'
```

### 参考视频编辑

通过 `video` 字段上传参考视频（data URI，最大 10MB）：

```bash theme={null}
curl -X POST "https://models.phanedge.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni-fast",
    "prompt": "Edit the attached video: add rainy cinematic night look with neon reflections. Output a newly generated video.",
    "video": "data:video/mp4;base64,...",
    "seconds": "8"
  }'
```

### 创建响应

```json theme={null}
{
  "id": "video_01KSDCPG3ZXAA2FD4NT3919V5P",
  "object": "video",
  "model": "omni-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1779639730
}
```

## 查询任务状态

```bash theme={null}
curl "https://models.phanedge.cloud/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $TOKEN"
```

### 状态流转

```
queued → in_progress → completed / failed
```

| 状态            | 说明       |
| ------------- | -------- |
| `queued`      | 排队中，等待处理 |
| `in_progress` | 生成中      |
| `completed`   | 已完成，可下载  |
| `failed`      | 生成失败     |

### 完成响应

```json theme={null}
{
  "id": "video_01KSDCPG3ZXAA2FD4NT3919V5P",
  "object": "video",
  "model": "omni-fast",
  "status": "completed",
  "progress": 100,
  "video_url": "https://...",
  "seconds": "5",
  "size": "1280x720",
  "completed_at": 1779639794
}
```

## 下载视频

任务完成后，通过 content 端点下载 MP4：

```bash theme={null}
curl -L "https://models.phanedge.cloud/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  --output video.mp4
```

<Tip>
  推荐始终使用 `/v1/videos/{id}/content` 下载视频，无需解析响应中的 `video_url` 字段。
</Tip>

## 参数说明

| 参数                | 类型            | 必填 | 说明                                                                                                  |
| ----------------- | ------------- | -- | --------------------------------------------------------------------------------------------------- |
| `model`           | string        | 是  | 固定为 `omni-fast`                                                                                     |
| `prompt`          | string        | 是  | 文本提示词                                                                                               |
| `seconds`         | string        | 否  | 视频时长，建议传字符串。可选值：`"4"`、`"8"`、`"10"`                                                                  |
| `duration`        | string        | 否  | `seconds` 的别名；同时传时建议保持一致                                                                            |
| `aspect_ratio`    | string        | 否  | 画面比例（见下表）                                                                                           |
| `size`            | string        | 否  | `aspect_ratio` 的别名。支持：`landscape`、`portrait`、`square`、`1920x1080`、`1080x1920`、`1280x720`、`720x1280` |
| `orientation`     | string        | 否  | `aspect_ratio` 的别名。支持：`landscape`、`portrait`                                                        |
| `resolution`      | string        | 否  | 分辨率偏好。支持：`720p`、`1080p`、`2k`、`4k`                                                                   |
| `fps`             | number/string | 否  | 帧率偏好（实测返回 24fps）                                                                                    |
| `n_frames`        | number/string | 否  | 帧数偏好（`fps` 的别名）                                                                                     |
| `n`               | number/string | 否  | 帧数偏好（`fps` 的别名）                                                                                     |
| `first_image_url` | string        | 否  | 首帧参考图（URL 或 data URI）→ 自动切换 I2V 模式                                                                  |
| `last_image_url`  | string        | 否  | 尾帧参考图（URL 或 data URI）→ 配合 `first_image_url` 做首尾帧插值                                                  |
| `images`          | string\[]     | 否  | 多参考图数组（最多 5 张，URL 或 data URI）→ 自动切换 R2V 模式                                                          |
| `video`           | string        | 否  | 参考视频（data URI 或 URL，最大约 100MB）                                                                      |
| `video_url`       | string        | 否  | `video` 的别名                                                                                         |

### 画面比例 `aspect_ratio`

| 值      | 实际输出     | 说明              |
| ------ | -------- | --------------- |
| `16:9` | 1280×720 | 横屏（推荐）          |
| `9:16` | 720×1280 | 竖屏（推荐）          |
| `1:1`  | 落到横/竖屏档  | 接口接收但不保证正方形输出   |
| `4:3`  | 落到横屏档    | 接口接收但不保证 4:3 输出 |
| `3:4`  | 落到竖屏档    | 接口接收但不保证 3:4 输出 |

### 参数别名关系

```
seconds ←→ duration
aspect_ratio ←→ size ←→ orientation
fps ←→ n_frames ←→ n
video ←→ video_url
```

### 生成模式自动切换

| 模式          | 触发条件                                   | 说明                |
| ----------- | -------------------------------------- | ----------------- |
| T2V（文生视频）   | 仅传 `prompt`                            | 纯文本描述生成视频         |
| I2V（图生视频）   | 传 `first_image_url`                    | 首帧图驱动生成           |
| 首尾帧插值       | 传 `first_image_url` + `last_image_url` | 在首尾帧之间生成过渡视频      |
| R2V（多参考图视频） | 传 `images[]`                           | 最多 5 张参考图，角色/风格参考 |
| 视频延长/编辑     | 传 `video` 或 `video_url`                | 基于已有视频延续或参考生成     |

## 最佳实践

* **时长参数**：建议传字符串格式，如 `"8"` 而非数字 `8`
* **提示词**：描述具体场景、镜头运动、光线氛围，效果更佳
* **轮询间隔**：建议 8-15 秒，服务端会自动轮询上游并更新状态
* **参考图格式**：支持 URL 和 `data:image/...;base64,...` 两种格式
* **参考视频**：data URI 上传最大 10MB，建议使用短片段
* **不要重复提交**：任务提交后保持轮询同一个 task\_id，不要并发重提