8c55f9f376
主要更新: - 修复了所有主要的代码逻辑错误 - 实现了完整的任务清理系统 - 添加了系统设置页面的任务清理管理功能 - 修复了API调用认证问题 - 优化了密码加密和验证机制 - 统一了错误处理模式 - 添加了详细的文档和测试工具 新增功能: - 任务清理管理界面 - 任务归档和清理日志 - API监控和诊断工具 - 完整的测试套件 技术改进: - 修复了Repository方法调用错误 - 统一了模型方法调用 - 改进了类型安全性 - 优化了代码结构和可维护性
299 lines
6.5 KiB
Markdown
299 lines
6.5 KiB
Markdown
# 文生视频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. **性能优化**: 合理设置轮询间隔，避免频繁请求
|
||
|
||
## 📞 **技术支持**
|
||
|
||
如有问题，请联系开发团队或查看系统日志获取详细错误信息。
|
||
|
||
|