AIGC/demo/TEXT_TO_VIDEO_API_README.md

# 文生视频API使用指南

## 📋 **API概述**

文生视频API提供了完整的文本生成视频功能，包括任务创建、状态查询、进度监控和任务管理等功能。

## 🔗 **API端点**

### 基础URL
```
http://localhost:8080/api/text-to-video
```

## 📚 **API接口详情**

### 1. 创建文生视频任务

**接口**: `POST /api/text-to-video/create`

**描述**: 根据文本描述创建视频生成任务

**请求头**:
```
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
```

**请求参数**:
```json
{
  "prompt": "一只可爱的小猫在花园里玩耍",
  "aspectRatio": "16:9",
  "duration": 5,
  "hdMode": false
}
```

**参数说明**:
- `prompt` (必填): 文本描述，最大1000字符
- `aspectRatio` (可选): 视频比例，支持 "16:9", "4:3", "1:1", "3:4", "9:16"，默认 "16:9"
- `duration` (可选): 视频时长（秒），范围1-60，默认5
- `hdMode` (可选): 是否高清模式，默认false

**响应示例**:
```json
{
  "success": true,
  "message": "文生视频任务创建成功",
  "data": {
    "id": 1,
    "taskId": "txt2vid_abc123def456",
    "username": "test_user",
    "prompt": "一只可爱的小猫在花园里玩耍",
    "aspectRatio": "16:9",
    "duration": 5,
    "hdMode": false,
    "status": "PENDING",
    "progress": 0,
    "costPoints": 30,
    "createdAt": "2025-01-24T10:00:00",
    "updatedAt": "2025-01-24T10:00:00"
  }
}
```

### 2. 获取任务列表

**接口**: `GET /api/text-to-video/tasks`

**描述**: 获取用户的所有文生视频任务

**请求头**:
```
Authorization: Bearer <JWT_TOKEN>
```

**查询参数**:
- `page` (可选): 页码，从0开始，默认0
- `size` (可选): 每页数量，最大100，默认10

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "taskId": "txt2vid_abc123def456",
      "username": "test_user",
      "prompt": "一只可爱的小猫在花园里玩耍",
      "aspectRatio": "16:9",
      "duration": 5,
      "hdMode": false,
      "status": "COMPLETED",
      "progress": 100,
      "resultUrl": "/outputs/txt2vid_abc123def456/video_1737696000000.mp4",
      "costPoints": 30,
      "createdAt": "2025-01-24T10:00:00",
      "updatedAt": "2025-01-24T10:15:00",
      "completedAt": "2025-01-24T10:15:00"
    }
  ],
  "total": 1,
  "page": 0,
  "size": 10
}
```

### 3. 获取任务详情

**接口**: `GET /api/text-to-video/tasks/{taskId}`

**描述**: 获取指定任务的详细信息

**请求头**:
```
Authorization: Bearer <JWT_TOKEN>
```

**路径参数**:
- `taskId`: 任务ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "taskId": "txt2vid_abc123def456",
    "username": "test_user",
    "prompt": "一只可爱的小猫在花园里玩耍",
    "aspectRatio": "16:9",
    "duration": 5,
    "hdMode": false,
    "status": "COMPLETED",
    "progress": 100,
    "resultUrl": "/outputs/txt2vid_abc123def456/video_1737696000000.mp4",
    "costPoints": 30,
    "createdAt": "2025-01-24T10:00:00",
    "updatedAt": "2025-01-24T10:15:00",
    "completedAt": "2025-01-24T10:15:00"
  }
}
```

### 4. 获取任务状态

**接口**: `GET /api/text-to-video/tasks/{taskId}/status`

**描述**: 获取任务的当前状态和进度

**请求头**:
```
Authorization: Bearer <JWT_TOKEN>
```

**路径参数**:
- `taskId`: 任务ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "taskId": "txt2vid_abc123def456",
    "status": "PROCESSING",
    "progress": 65,
    "resultUrl": null,
    "errorMessage": null
  }
}
```

### 5. 取消任务

**接口**: `POST /api/text-to-video/tasks/{taskId}/cancel`

**描述**: 取消正在进行的任务

**请求头**:
```
Authorization: Bearer <JWT_TOKEN>
```

**路径参数**:
- `taskId`: 任务ID

**响应示例**:
```json
{
  "success": true,
  "message": "任务已取消"
}
```

## 📊 **任务状态说明**

| 状态 | 描述 | 说明 |
|------|------|------|
| PENDING | 等待中 | 任务已创建，等待处理 |
| PROCESSING | 处理中 | 正在生成视频 |
| COMPLETED | 已完成 | 视频生成成功 |
| FAILED | 失败 | 视频生成失败 |
| CANCELLED | 已取消 | 任务被用户取消 |

## 💰 **积分消耗规则**

文生视频的积分消耗计算方式：
- **基础消耗**: 15积分
- **时长消耗**: 每1秒消耗3积分
- **高清模式**: 额外消耗25积分

**示例**:
- 5秒普通视频: 15 + (5 × 3) = 30积分
- 10秒高清视频: 15 + (10 × 3) + 25 = 70积分

## 🔧 **前端集成示例**

### 创建任务
```javascript
import { textToVideoApi } from '@/api/textToVideo'

const createTask = async () => {
  try {
    const params = {
      prompt: "一只可爱的小猫在花园里玩耍",
      aspectRatio: "16:9",
      duration: 5,
      hdMode: false
    }
    
    const response = await textToVideoApi.createTask(params)
    
    if (response.data.success) {
      console.log('任务创建成功:', response.data.data)
      // 开始轮询任务状态
      startPolling(response.data.data.taskId)
    }
  } catch (error) {
    console.error('创建任务失败:', error)
  }
}
```

### 轮询任务状态
```javascript
const startPolling = (taskId) => {
  const stopPolling = textToVideoApi.pollTaskStatus(
    taskId,
    // 进度回调
    (progressData) => {
      console.log('进度:', progressData.progress + '%')
    },
    // 完成回调
    (taskData) => {
      console.log('任务完成:', taskData.resultUrl)
    },
    // 错误回调
    (error) => {
      console.error('任务失败:', error.message)
    }
  )
  
  // 需要时停止轮询
  // stopPolling()
}
```

## 🛡️ **安全说明**

1. **认证要求**: 所有API都需要JWT认证
2. **权限控制**: 用户只能访问自己的任务
3. **参数验证**: 严格的输入参数验证
4. **错误处理**: 完善的错误处理和日志记录

## 📝 **错误码说明**

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 400 | 参数错误 | 检查请求参数格式和内容 |
| 401 | 未认证 | 提供有效的JWT Token |
| 403 | 权限不足 | 确保有访问权限 |
| 404 | 任务不存在 | 检查任务ID是否正确 |
| 500 | 服务器错误 | 联系技术支持 |

## 🚀 **最佳实践**

1. **任务创建**: 创建任务后立即开始轮询状态
2. **错误处理**: 实现完善的错误处理和用户提示
3. **资源清理**: 页面卸载时停止轮询
4. **用户体验**: 提供清晰的进度反馈和状态显示
5. **性能优化**: 合理设置轮询间隔，避免频繁请求

## 📞 **技术支持**

如有问题，请联系开发团队或查看系统日志获取详细错误信息。