agent_management/agent_templates/agents/video_generator_agent/README.md

Video Generator Agent

根据文本描述生成图片并拼接为视频的 AI Agent。

功能特性

• 🎨 图片生成: 使用 Gemini 3 Pro Image Preview 根据描述生成高质量图片
• 🎬 视频拼接: 使用 FFmpeg 将多张图片拼接成视频
• ✨ 转场效果: 支持多种转场效果（fade, wipeleft, wiperight, slideup, slidedown）
• 📁 文件管理: 自动管理生成的图片和视频文件
• 🔌 MCP 协议: 支持 MCP (Model Context Protocol) 工具调用
• 🌐 REST API: 提供完整的 HTTP API 接口

快速开始

1. 本地运行

# 安装依赖
pip install -r requirements.txt

# 设置环境变量
export OPENAI_API_KEY="sk-i9AwAgXDqqxsA9Ym4AjSPg"
export MODEL_NAME="taiji/gemini-3-pro-image-preview"

# 启动服务
python run_api_server.py

服务将在 http://localhost:8000 启动。

2. Docker 运行

# 构建镜像
docker build -t video-generator-agent:latest .

# 运行容器
docker run -d \
  -p 8000:8000 \
  -e OPENAI_API_KEY="sk-i9AwAgXDqqxsA9Ym4AjSPg" \
  -e MODEL_NAME="taiji/gemini-3-pro-image-preview" \
  -v $(pwd)/outputs:/app/outputs \
  video-generator-agent:latest

3. 测试

# 运行测试脚本
python test_video_agent.py

# 或指定自定义 API URL
API_BASE_URL=http://localhost:8000 python test_video_agent.py

API 使用示例

生成单张图片

curl -X POST http://localhost:8000/api/v1/generate-image \
  -H "api-key: sk-i9AwAgXDqqxsA9Ym4AjSPg" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "a beautiful sunset over mountains",
    "size": "1024x1024",
    "quality": "standard"
  }'

响应示例：

{
  "success": true,
  "file_path": "/app/outputs/images/image_20260226_123456.png",
  "filename": "image_20260226_123456.png",
  "url": "/api/v1/files/image_20260226_123456.png",
  "description": "a beautiful sunset over mountains"
}

生成视频

curl -X POST http://localhost:8000/api/v1/generate-video \
  -H "api-key: sk-i9AwAgXDqqxsA9Ym4AjSPg" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptions": [
      "sunrise over mountains",
      "a peaceful lake at noon",
      "starry night sky"
    ],
    "duration_per_image": 3,
    "fps": 30,
    "transition": "fade"
  }'

响应示例：

{
  "success": true,
  "video": {
    "file_path": "/app/outputs/videos/video_20260226_123456.mp4",
    "url": "/api/v1/files/video_20260226_123456.mp4",
    "filename": "video_20260226_123456.mp4",
    "duration": 9.0,
    "image_count": 3
  },
  "images": [
    {
      "index": 1,
      "description": "sunrise over mountains",
      "file_path": "/app/outputs/images/image_20260226_123456_1.png",
      "url": "/api/v1/files/image_20260226_123456_1.png"
    }
  ],
  "settings": {
    "duration_per_image": 3,
    "fps": 30,
    "transition": "fade"
  }
}

下载文件

# 下载图片
curl -O http://localhost:8000/api/v1/files/image_20260226_123456.png

# 下载视频
curl -O http://localhost:8000/api/v1/files/video_20260226_123456.mp4

列出文件

# 列出所有文件
curl http://localhost:8000/api/v1/list-files?file_type=all

# 只列出图片
curl http://localhost:8000/api/v1/list-files?file_type=image

# 只列出视频
curl http://localhost:8000/api/v1/list-files?file_type=video

MCP 工具

Agent 提供以下 MCP 工具：

1. generate_image

根据描述生成单张图片。

{
  "name": "generate_image",
  "arguments": {
    "description": "a futuristic city at night",
    "size": "1024x1024",
    "quality": "standard"
  }
}

2. generate_video

根据多个描述生成视频。

{
  "name": "generate_video",
  "arguments": {
    "descriptions": [
      "scene 1 description",
      "scene 2 description",
      "scene 3 description"
    ],
    "duration_per_image": 3,
    "fps": 30,
    "transition": "fade"
  }
}

3. list_generated_files

列出已生成的文件。

{
  "name": "list_generated_files",
  "arguments": {
    "file_type": "all"
  }
}

4. cleanup_old_files

清理旧文件。

{
  "name": "cleanup_old_files",
  "arguments": {
    "max_age_hours": 24
  }
}

MCP 端点

HTTP 端点

# 初始化
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": 1
  }'

# 列出工具
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

# 调用工具
curl -X POST http://localhost:8000/mcp \
  -H "api-key: sk-i9AwAgXDqqxsA9Ym4AjSPg" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "generate_image",
      "arguments": {
        "description": "a beautiful landscape"
      }
    },
    "id": 3
  }'

SSE 端点

# 连接 SSE
curl -N http://localhost:8000/mcp/sse

环境变量

变量	必需	默认值	说明
OPENAI_API_KEY	是	sk-i9AwAgXDqqxsA9Ym4AjSPg	API Key
OPENAI_BASE_URL	否	LiteLLM Gateway URL	API Base URL
MODEL_NAME	否	taiji/gemini-3-pro-image-preview	模型名称
API_PORT	否	8000	服务端口
OUTPUT_DIR	否	/app/outputs	输出目录

转场效果

支持的转场效果：

• fade - 淡入淡出
• wipeleft - 左擦除
• wiperight - 右擦除
• slideup - 上滑
• slidedown - 下滑

图片尺寸

支持的图片尺寸：

• 256x256
• 512x512
• 1024x1024 (默认)
• 1792x1024
• 1024x1792

项目结构

video_generator_agent/
├── Dockerfile                    # Docker 配置
├── requirements.txt              # Python 依赖
├── run_api_server.py            # 启动脚本
├── test_video_agent.py          # 测试脚本
├── README.md                    # 文档
└── src/
    ├── __init__.py
    ├── utils/                   # 工具模块
    │   ├── __init__.py
    │   ├── image_generator.py   # 图片生成
    │   ├── video_processor.py   # 视频处理
    │   └── file_manager.py      # 文件管理
    └── server/                  # 服务器模块
        ├── __init__.py
        ├── mcp_server.py        # MCP 工具定义
        └── api_server.py        # FastAPI 服务器

技术栈

• Pydantic AI: Agent 框架
• FastMCP: MCP 服务器
• FastAPI: REST API 框架
• FFmpeg: 视频处理
• Gemini 3 Pro Image Preview: 图片生成模型
• aiohttp: 异步 HTTP 客户端
• Pillow: 图片处理

故障排除

FFmpeg 未安装

如果遇到 FFmpeg 相关错误，请确保已安装 FFmpeg：

# Ubuntu/Debian
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg

# 验证安装
ffmpeg -version

API Key 错误

确保设置了正确的 API Key：

export OPENAI_API_KEY="sk-i9AwAgXDqqxsA9Ym4AjSPg"

端口被占用

如果端口 8000 被占用，可以更改端口：

export API_PORT=8080
python run_api_server.py

性能建议

• 图片生成通常需要 10-30 秒
• 视频拼接时间取决于图片数量（每张图片约 2-5 秒）
• 建议每个视频不超过 10 个场景
• 使用转场效果会增加处理时间

许可证

MIT License

作者

Video Generator Agent Team