297 lines
6.8 KiB
Markdown
297 lines
6.8 KiB
Markdown
# 图生视频API配置说明
|
||
|
||
## 概述
|
||
|
||
图生视频API允许用户上传图片并生成视频内容。系统支持首帧图片（必填）和尾帧图片（可选），结合用户描述文字生成动态视频。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 图片上传（支持JPG、PNG、WEBP格式）
|
||
- ✅ 多种视频比例（16:9、4:3、1:1、3:4、9:16）
|
||
- ✅ 可调节视频时长（5s、10s、15s、30s）
|
||
- ✅ 高清模式（1080P，额外消耗积分）
|
||
- ✅ 实时任务状态监控
|
||
- ✅ 进度条显示
|
||
- ✅ 任务取消功能
|
||
- ✅ 积分消耗计算
|
||
|
||
## API接口
|
||
|
||
### 1. 创建图生视频任务
|
||
|
||
**POST** `/api/image-to-video/create`
|
||
|
||
**请求参数：**
|
||
- `firstFrame` (File, 必填): 首帧图片
|
||
- `lastFrame` (File, 可选): 尾帧图片
|
||
- `prompt` (String, 必填): 描述文字
|
||
- `aspectRatio` (String, 可选): 视频比例，默认"16:9"
|
||
- `duration` (Integer, 可选): 视频时长（秒），默认5
|
||
- `hdMode` (Boolean, 可选): 是否高清模式，默认false
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "任务创建成功",
|
||
"data": {
|
||
"id": 1,
|
||
"taskId": "img2vid_abc123def456",
|
||
"username": "test_user",
|
||
"firstFrameUrl": "/uploads/img2vid_abc123def456/first_frame_1234567890.jpg",
|
||
"prompt": "测试图生视频",
|
||
"aspectRatio": "16:9",
|
||
"duration": 5,
|
||
"hdMode": false,
|
||
"status": "PENDING",
|
||
"progress": 0,
|
||
"costPoints": 20,
|
||
"createdAt": "2025-01-24T10:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取用户任务列表
|
||
|
||
**GET** `/api/image-to-video/tasks`
|
||
|
||
**查询参数：**
|
||
- `page` (Integer, 可选): 页码，默认0
|
||
- `size` (Integer, 可选): 每页数量，默认10
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"taskId": "img2vid_abc123def456",
|
||
"status": "COMPLETED",
|
||
"progress": 100,
|
||
"resultUrl": "/outputs/img2vid_abc123def456/video_1234567890.mp4",
|
||
"createdAt": "2025-01-24T10:30:00"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 0,
|
||
"size": 10
|
||
}
|
||
```
|
||
|
||
### 3. 获取任务详情
|
||
|
||
**GET** `/api/image-to-video/tasks/{taskId}`
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"taskId": "img2vid_abc123def456",
|
||
"username": "test_user",
|
||
"firstFrameUrl": "/uploads/img2vid_abc123def456/first_frame_1234567890.jpg",
|
||
"prompt": "测试图生视频",
|
||
"aspectRatio": "16:9",
|
||
"duration": 5,
|
||
"hdMode": false,
|
||
"status": "COMPLETED",
|
||
"progress": 100,
|
||
"resultUrl": "/outputs/img2vid_abc123def456/video_1234567890.mp4",
|
||
"costPoints": 20,
|
||
"createdAt": "2025-01-24T10:30:00",
|
||
"completedAt": "2025-01-24T10:35:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 获取任务状态
|
||
|
||
**GET** `/api/image-to-video/tasks/{taskId}/status`
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "img2vid_abc123def456",
|
||
"status": "PROCESSING",
|
||
"progress": 45,
|
||
"resultUrl": null,
|
||
"errorMessage": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 取消任务
|
||
|
||
**POST** `/api/image-to-video/tasks/{taskId}/cancel`
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "任务已取消"
|
||
}
|
||
```
|
||
|
||
## 任务状态说明
|
||
|
||
| 状态 | 描述 | 说明 |
|
||
|------|------|------|
|
||
| PENDING | 等待中 | 任务已创建，等待处理 |
|
||
| PROCESSING | 处理中 | 正在生成视频 |
|
||
| COMPLETED | 已完成 | 视频生成成功 |
|
||
| FAILED | 失败 | 生成过程中出现错误 |
|
||
| CANCELLED | 已取消 | 用户主动取消任务 |
|
||
|
||
## 积分消耗计算
|
||
|
||
- **基础消耗**: 10积分
|
||
- **时长消耗**: 时长(秒) × 2积分
|
||
- **高清模式**: 额外20积分
|
||
|
||
**示例：**
|
||
- 5秒普通视频：10 + 5×2 = 20积分
|
||
- 10秒高清视频：10 + 10×2 + 20 = 50积分
|
||
|
||
## 前端集成示例
|
||
|
||
### 1. 创建任务
|
||
|
||
```javascript
|
||
import { imageToVideoApi } from '@/api/imageToVideo'
|
||
|
||
const createTask = async () => {
|
||
const params = {
|
||
firstFrame: firstFrameFile.value,
|
||
lastFrame: lastFrameFile.value, // 可选
|
||
prompt: inputText.value.trim(),
|
||
aspectRatio: aspectRatio.value,
|
||
duration: parseInt(duration.value),
|
||
hdMode: hdMode.value
|
||
}
|
||
|
||
try {
|
||
const response = await imageToVideoApi.createTask(params)
|
||
if (response.data.success) {
|
||
console.log('任务创建成功:', response.data.data)
|
||
// 开始轮询任务状态
|
||
startPollingTask(response.data.data.taskId)
|
||
}
|
||
} catch (error) {
|
||
console.error('创建任务失败:', error)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 轮询任务状态
|
||
|
||
```javascript
|
||
const startPollingTask = (taskId) => {
|
||
const stopPolling = imageToVideoApi.pollTaskStatus(
|
||
taskId,
|
||
// 进度回调
|
||
(progressData) => {
|
||
console.log('任务进度:', progressData.progress + '%')
|
||
updateProgressBar(progressData.progress)
|
||
},
|
||
// 完成回调
|
||
(taskData) => {
|
||
console.log('任务完成:', taskData.resultUrl)
|
||
showResult(taskData.resultUrl)
|
||
},
|
||
// 错误回调
|
||
(error) => {
|
||
console.error('任务失败:', error.message)
|
||
showError(error.message)
|
||
}
|
||
)
|
||
|
||
// 可以调用 stopPolling() 来停止轮询
|
||
}
|
||
```
|
||
|
||
## 文件上传限制
|
||
|
||
- **文件大小**: 最大10MB
|
||
- **支持格式**: JPG、PNG、WEBP
|
||
- **存储路径**: `/uploads/{taskId}/`
|
||
- **输出路径**: `/outputs/{taskId}/`
|
||
|
||
## 数据库表结构
|
||
|
||
```sql
|
||
CREATE TABLE image_to_video_tasks (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
task_id VARCHAR(50) NOT NULL UNIQUE,
|
||
username VARCHAR(100) NOT NULL,
|
||
first_frame_url VARCHAR(500) NOT NULL,
|
||
last_frame_url VARCHAR(500),
|
||
prompt TEXT,
|
||
aspect_ratio VARCHAR(10) NOT NULL DEFAULT '16:9',
|
||
duration INT NOT NULL DEFAULT 5,
|
||
hd_mode BOOLEAN NOT NULL DEFAULT FALSE,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
|
||
progress INT DEFAULT 0,
|
||
result_url VARCHAR(500),
|
||
error_message TEXT,
|
||
cost_points INT DEFAULT 0,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
completed_at TIMESTAMP NULL
|
||
);
|
||
```
|
||
|
||
## 部署注意事项
|
||
|
||
1. **文件存储**: 确保 `uploads` 和 `outputs` 目录有写入权限
|
||
2. **异步处理**: 已启用 `@EnableAsync` 支持异步任务处理
|
||
3. **安全配置**: 图生视频API需要用户认证
|
||
4. **CORS配置**: 已配置支持前端跨域访问
|
||
5. **文件大小**: 已设置最大上传文件大小为10MB
|
||
|
||
## 测试方法
|
||
|
||
1. 启动后端服务
|
||
2. 运行测试脚本：`./test-image-to-video-api.sh`
|
||
3. 或使用前端页面进行测试
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **文件上传失败**
|
||
- 检查文件大小是否超过10MB
|
||
- 确认文件格式是否支持
|
||
- 检查服务器存储权限
|
||
|
||
2. **任务状态不更新**
|
||
- 检查异步处理是否正常
|
||
- 查看服务器日志
|
||
- 确认数据库连接正常
|
||
|
||
3. **前端轮询失败**
|
||
- 检查网络连接
|
||
- 确认API接口地址正确
|
||
- 查看浏览器控制台错误
|
||
|
||
### 日志查看
|
||
|
||
```bash
|
||
# 查看应用日志
|
||
tail -f logs/application.log
|
||
|
||
# 查看特定任务日志
|
||
grep "img2vid_abc123def456" logs/application.log
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|