AIGC/demo/IMAGE_TO_VIDEO_API_README.md

# 图生视频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
```