视频生成驱动说明

<title>视频生成驱动说明</title>

# 视频生成驱动说明

## 概述

图生视频驱动实现了调用第三方视频生成模型（异步 API，创建任务后轮询状态）的驱动逻辑。

## 支持的模型

| Task ID | 模型 | 驱动 | 支持的图片模式 | 支持参考音频/视频 |
|-|-|-|-|-|
| 21 | 第三方视频生成模型（首尾帧增强版） | 对应驱动 | first_last_frame | 不支持 |
| 22 | 第三方视频生成模型（快速版） | 对应驱动 | first_last_frame, multi_reference | 支持 |
| 23 | 第三方视频生成模型（标准版） | 对应驱动 | first_last_frame, multi_reference | 支持 |

## 特性

- **异步接口**：提交任务后返回 `project_id`，通过轮询 `check_status` 获取结果
- **多帧支持**：支持首帧（first_frame）、尾帧（last_frame）
- **多参考图**：支持 `multi_reference` 模式下多张参考图（role: reference_image）
- **参考视频**：支持传入参考视频（role: reference_video）
- **参考音频**：支持传入参考音频（role: reference_audio）
- **图片压缩上传**：本地图片自动压缩后上传至对象存储

## Content 数组格式

视频生成 API 使用 content 数组传递输入：

```JSON
{
  "model": "模型标识（按 Task ID 选择）",
  "content": [
    {"type": "text", "text": "视频描述提示词"},
    {"type": "image_url", "image_url": {"url": "首帧图URL"}, "role": "first_frame"},
    {"type": "image_url", "image_url": {"url": "尾帧图URL"}, "role": "last_frame"},
    {"type": "image_url", "image_url": {"url": "参考图1URL"}, "role": "reference_image"},
    {"type": "image_url", "image_url": {"url": "参考图2URL"}, "role": "reference_image"},
    {"type": "video_url", "video_url": {"url": "参考视频URL"}, "role": "reference_video"},
    {"type": "audio_url", "audio_url": {"url": "参考音频URL"}, "role": "reference_audio"}
  ],
  "duration": 5,
  "ratio": "9:16",
  "generate_audio": false,
  "watermark": false
}
```

### 角色说明

| 角色 | 类型 | 说明 |
|-|-|-|
| `first_frame` | image_url | 视频首帧图片 |
| `last_frame` | image_url | 视频尾帧图片 |
| `reference_image` | image_url | 参考图片（可多张） |
| `reference_video` | video_url | 参考视频 |
| `reference_audio` | audio_url | 参考音频 |

## 参考音频/视频数据来源

参考音频和参考视频优先从 `ai_tool` 模型字段读取，向后兼容 `extra_config`：

1. **参考视频**：优先读取 `ai_tool.video_path`，备选 `extra_config.reference_video`
2. **参考音频**：优先读取 `ai_tool.audio_path`，备选 `extra_config.reference_audio`

## 配置

在配置中添加视频生成服务配置（驱动读取该服务配置节下的 `api_key`，数据库配置优先、YAML 配置兜底；配置节名称定义于 `config/default_configs.py`）：

```YAML
<视频生成服务配置节>:
  api_key: "<your_api_key>"
```

## 文件列表

| 文件 | 说明 |
|-|-|
| `task/visual_drivers/`（对应驱动） | 驱动实现 |
| `task/visual_drivers/base_video_driver.py` | 驱动基类 |
| `config/unified_config.py` | 驱动配置定义 |
| `model/ai_tools.py` | AI 工具模型（含 audio_path、video_path 字段） |