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

请求参数:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "success": true,
  "message": "任务已取消"
}

📊 任务状态说明

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

💰 积分消耗规则

文生视频的积分消耗计算方式：

• 基础消耗: 15积分
• 时长消耗: 每1秒消耗3积分
• 高清模式: 额外消耗25积分

示例:

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

🔧 前端集成示例

创建任务

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)
  }
}

轮询任务状态

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. 性能优化: 合理设置轮询间隔，避免频繁请求

📞 技术支持

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