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

响应示例：

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

响应示例：

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

响应示例：

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

响应示例：

{
  "success": true,
  "data": {
    "id": "img2vid_abc123def456",
    "status": "PROCESSING",
    "progress": 45,
    "resultUrl": null,
    "errorMessage": null
  }
}

5. 取消任务

POST /api/image-to-video/tasks/{taskId}/cancel

响应示例：

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

任务状态说明

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

积分消耗计算

• 基础消耗: 10积分
• 时长消耗: 时长(秒) × 2积分
• 高清模式: 额外20积分

示例：

• 5秒普通视频：10 + 5×2 = 20积分
• 10秒高清视频：10 + 10×2 + 20 = 50积分

前端集成示例

1. 创建任务

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. 轮询任务状态

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

数据库表结构

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接口地址正确
   • 查看浏览器控制台错误

日志查看

# 查看应用日志
tail -f logs/application.log

# 查看特定任务日志
grep "img2vid_abc123def456" logs/application.log