backend/backend_app/api/video/README.md

视频生成API文档

概述

视频生成API提供企业级文本到视频生成服务，支持多种视频风格、分辨率、时长等参数控制，可生成MP4、AVI、MOV等多种格式的视频文件，支持背景音乐和语音解说。

API端点

1. 生成视频

POST /api/v1/video/generate

请求体：

{
  "prompt": "一只小鸟从天空飞过，落在树枝上，背景是森林",
  "style": "animation",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "frame_rate": 30,
  "background_music": false,
  "voice_over": true,
  "voice_over_text": "这是一只美丽的小鸟，它在森林中自由飞翔",
  "user_id": "user_12345"
}

参数说明：

参数	类型	必填	默认值	说明
prompt	string	是	-	视频描述文本，最长2000字符
style	string	否	animation	视频风格：animation(动画)、realistic(真人实拍)、3d(3D建模)、cartoon(卡通)、cinematic(电影感)
duration	int	否	5	视频时长（秒），范围1-60
resolution	string	否	720p	分辨率：480p、720p、1080p、4k
aspect_ratio	string	否	16:9	宽高比：16:9、4:3、1:1、9:16
frame_rate	int	否	30	帧率，范围1-60
background_music	bool	否	false	是否添加背景音乐
voice_over	bool	否	false	是否添加语音解说
voice_over_text	string	否	null	语音解说文本
user_id	string	否	null	用户ID，用于统计和配额管理

响应：

{
  "success": true,
  "video_url": "/api/video/files/video_abc123.mp4",
  "video_id": "video_abc123",
  "duration": 5,
  "file_size": 1024000,
  "resolution": "720p",
  "format": "mp4",
  "thumbnail_url": "/api/video/files/thumbnails/thumb_abc123.jpg",
  "timestamp": "2024-01-01T12:00:00",
  "estimated_generation_time": 30
}

2. 获取视频状态

POST /api/v1/video/status

请求体：

{
  "video_id": "video_abc123"
}

响应：

{
  "success": true,
  "video_id": "video_abc123",
  "status": "processing",
  "progress": 65.5,
  "estimated_completion_time": "2024-01-01T12:01:30",
  "message": "正在生成视频帧...",
  "timestamp": "2024-01-01T12:00:30"
}

状态说明：

• pending: 等待处理
• processing: 处理中
• completed: 已完成
• failed: 失败

3. 获取视频文件

GET /api/v1/video/files/{video_id}.{format}

参数：

参数	类型	必填	说明
video_id	string	是	视频文件ID
format	string	是	文件格式：mp4、avi、mov、webm

响应： 返回视频文件流，Content-Type为对应的视频类型。

4. 获取视频缩略图

GET /api/v1/video/files/thumbnails/{thumbnail_filename}

参数：

参数	类型	必填	说明
thumbnail_filename	string	是	缩略图文件名，格式：thumb_{video_id}.jpg

响应： 返回缩略图文件流，Content-Type为image/jpeg。

5. 获取支持的视频风格

GET /api/v1/video/supported-styles

响应：

{
  "success": true,
  "styles": {
    "animation": {"name": "动画", "description": "2D/3D动画风格"},
    "realistic": {"name": "真人实拍", "description": "实拍视频效果"},
    "3d": {"name": "3D建模", "description": "三维建模渲染"},
    "cartoon": {"name": "卡通", "description": "卡通漫画风格"},
    "cinematic": {"name": "电影感", "description": "电影级视觉效果"}
  },
  "resolutions": ["480p", "720p", "1080p", "4k"],
  "formats": ["mp4", "avi", "mov", "webm"],
  "timestamp": "2024-01-01T12:00:00"
}

6. 列出视频文件

GET /api/v1/video/list?page=1&page_size=20

查询参数：

参数	类型	必填	默认值	说明
page	int	否	1	页码
page_size	int	否	20	每页数量

响应：

{
  "success": true,
  "videos": [
    {
      "video_id": "video_abc123",
      "filename": "video_abc123.mp4",
      "size": 1024000,
      "created_at": "2024-01-01T12:00:00",
      "format": "mp4",
      "has_thumbnail": true
    }
  ],
  "total": 8,
  "page": 1,
  "page_size": 20,
  "timestamp": "2024-01-01T12:00:00"
}

7. 删除视频文件

POST /api/v1/video/delete

请求体：

{
  "video_id": "video_abc123",
  "confirm": true
}

响应：

{
  "success": true,
  "message": "视频文件已成功删除",
  "timestamp": "2024-01-01T12:00:00"
}

8. 健康检查

GET /api/v1/video/health

响应：

{
  "status": "healthy",
  "service": "video_generation",
  "output_dir": "./video_outputs",
  "video_files_count": 15,
  "thumbnail_files_count": 15,
  "timestamp": "2024-01-01T12:00:00"
}

错误处理

所有API端点都遵循统一的错误响应格式：

{
  "detail": "错误描述信息"
}

HTTP状态码：

• 200: 请求成功
• 400: 参数错误
• 404: 资源不存在
• 500: 服务器内部错误

企业级功能

1. 异步处理

支持长视频生成的异步处理，可通过状态查询接口实时获取生成进度。

2. 多格式支持

支持多种视频格式和分辨率，满足不同场景需求。

3. 缩略图生成

自动为每个视频生成缩略图，便于预览和展示。

4. 语音解说集成

支持为视频添加语音解说，实现文本到语音再到视频的完整流程。

5. 进度跟踪

实时进度跟踪和状态更新，提供良好的用户体验。

部署配置

环境变量

# 视频引擎配置
VIDEO_ENGINE=simulated  # simulated, moviepy, svd, runwayml
VIDEO_API_KEY=your_api_key
VIDEO_MODEL=svd

# 存储配置
STORAGE_TYPE=local  # local, s3, azure_blob, gcs
STORAGE_BUCKET=video-bucket
STORAGE_REGION=us-west-1

# 异步处理配置
VIDEO_ASYNC_PROCESSING=true
MAX_WORKERS=4
QUEUE_TIMEOUT=300

# API配置
API_RATE_LIMIT=30  # 视频生成较耗资源，限制更低
API_AUTH_REQUIRED=false

依赖安装

# 基本依赖
pip install fastapi uvicorn python-multipart

# 视频处理依赖（根据选择的引擎）
pip install moviepy          # 视频编辑和处理
pip install opencv-python    # 计算机视觉库
pip install pillow           # 图像处理

# AI模型相关（用于高级视频生成）
pip install diffusers        # 扩散模型（用于视频生成）
pip install transformers     # 已包含
pip install torch            # 已包含

使用示例

Python客户端

import requests
import time

BASE_URL = "http://localhost:8000/api/v1"

def generate_video(prompt, style="animation"):
    # 提交生成请求
    response = requests.post(f"{BASE_URL}/video/generate", json={
        "prompt": prompt,
        "style": style,
        "duration": 5,
        "resolution": "720p"
    })

    if response.status_code != 200:
        print(f"提交失败: {response.text}")
        return None

    data = response.json()
    if not data["success"]:
        print(f"生成失败: {data.get('message')}")
        return None

    video_id = data["video_id"]
    print(f"视频生成已提交，ID: {video_id}")

    # 轮询状态
    while True:
        status_response = requests.post(f"{BASE_URL}/video/status", json={
            "video_id": video_id
        })

        if status_response.status_code == 200:
            status_data = status_response.json()
            if status_data["success"]:
                status = status_data["status"]
                progress = status_data["progress"]

                print(f"进度: {progress}% - 状态: {status}")

                if status == "completed":
                    print(f"视频生成完成: {data['video_url']}")
                    return data
                elif status == "failed":
                    print("视频生成失败")
                    return None

        time.sleep(2)

JavaScript/TypeScript客户端

const API_BASE_URL = 'http://localhost:8000/api/v1';

class VideoGenerator {
  async generateVideo(prompt: string): Promise<any> {
    // 提交生成请求
    const response = await fetch(`${API_BASE_URL}/video/generate`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        prompt,
        style: 'animation',
        duration: 5,
        resolution: '720p'
      })
    });

    if (!response.ok) {
      throw new Error(`提交失败: ${response.status}`);
    }

    const data = await response.json();
    if (!data.success) {
      throw new Error(`生成失败: ${data.message}`);
    }

    return data;
  }

  async checkStatus(videoId: string): Promise<any> {
    const response = await fetch(`${API_BASE_URL}/video/status`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ video_id: videoId })
    });

    if (!response.ok) {
      throw new Error(`状态查询失败: ${response.status}`);
    }

    return await response.json();
  }

  async downloadVideo(videoId: string, format: string = 'mp4'): Promise<void> {
    const url = `${API_BASE_URL}/video/files/${videoId}.${format}`;
    window.open(url, '_blank');
  }
}

性能优化建议

1. 异步队列：使用消息队列处理视频生成任务，避免阻塞主线程
2. GPU加速：视频生成任务尽量使用GPU加速
3. 分级存储：热数据使用SSD，冷数据迁移到低成本存储
4. CDN分发：生成的视频文件通过CDN分发，提高访问速度
5. 预览优化：先生成低分辨率预览，再生成全分辨率版本

安全注意事项

1. 内容审核：对用户输入的描述文本进行内容安全审核
2. 资源限制：实施严格的资源使用限制，防止滥用
3. 访问控制：敏感操作需要身份验证和授权
4. 数据隔离：不同用户的数据进行逻辑或物理隔离
5. 监控告警：实时监控系统资源使用情况，设置告警阈值

扩展功能

1. 批量生成

支持批量视频生成，提高处理效率。

2. 自定义模板

支持用户上传自定义视频模板。

3. 高级编辑

支持对生成的视频进行进一步编辑（裁剪、滤镜、字幕等）。

4. 多语言支持

支持更多语言的语音解说。

5. 实时预览

支持生成过程中的实时预览功能。

故障排除

常见问题

1. 生成速度慢：检查GPU资源是否充足，考虑升级硬件或优化算法
2. 内存不足：调整视频分辨率或时长，减少内存占用
3. 文件太大：调整视频编码参数，优化文件大小
4. 质量不佳：优化描述文本，调整生成参数
5. 服务不可用：检查依赖服务状态，查看错误日志

日志查看

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

# 查看错误日志
tail -f logs/error.log

# 查看访问日志
tail -f logs/access.log