# Sora 视频生成 MCP 服务器

这是一个基于云雾 API 的 Sora 视频生成 MCP 服务器，提供强大的 AI 视频生成能力。

## ✨ 功能特性

- 🎬 **文生视频**: 仅使用文本提示词即可生成精彩视频
- 🖼️ **图生视频**: 结合图片和提示词生成动态视频内容
- 📊 **任务查询**: 实时查询视频生成任务的状态和结果
- 🎯 **灵活配置**: 支持横屏/竖屏、多种清晰度和时长选择

## 📦 安装

```bash
# 安装依赖
npm install

# 构建项目
npm run build
```

## ⚙️ 配置

### 1. 创建环境变量文件

```bash
cp .env.example .env
```

### 2. 配置 API 密钥

编辑 `.env` 文件，填入 API 密钥和默认模型:

```env
VIDEO_API_KEY=your_api_key_here
VIDEO_BASE_URL=https://api.kie.ai
VIDEO_MODEL=bytedance/seedance-1.5-pro
```

> 💡 **获取 API 密钥**: 访问 [云雾 AI](https://yunwu.ai) 注册账号并获取 API 密钥

## 🚀 使用方法

### 在 Claude Desktop 中使用

1. 找到 Claude Desktop 配置文件:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. 添加以下配置:

```json
{
  "mcpServers": {
    "sora-video": {
      "command": "node",
      "args": ["/完整路径/视频生成/build/index.js"],
      "env": {
        "VIDEO_API_KEY": "your_api_key_here",
        "VIDEO_BASE_URL": "https://api.kie.ai",
        "VIDEO_MODEL": "bytedance/seedance-1.5-pro"
      }
    }
  }
}
```

3. 重启 Claude Desktop

### 命令行运行

```bash
# 设置环境变量
export VIDEO_API_KEY=your_api_key_here
export VIDEO_BASE_URL=https://api.kie.ai
export VIDEO_MODEL=bytedance/seedance-1.5-pro

# 运行服务器
npm start
```

## 🛠️ 可用工具

### 1. 创建文生视频 (create_video)

使用文本描述生成视频。

**参数说明:**

| 参数 | 类型 | 必需 | 说明 | 默认值 |
|------|------|------|------|--------|
| `prompt` | string | ✅ | 视频内容描述 | - |
| `size` | string | ❌ | 视频尺寸，格式 `宽x高` | `854x480` |

**使用示例:**

```json
{
  "prompt": "一只金色的拉布拉多犬在海滩上奔跑，夕阳西下，海浪拍打着沙滩",
  "size": "854x480"
}
```

模型通过环境变量 `VIDEO_MODEL` 控制。默认使用 `bytedance/seedance-1.5-pro`。视频参数已经写死为 `8 秒 / 480p / 开音频`，不会再让模型额外传递；为了保持现有 MCP 的返回结构不变，工具层返回字段未改。

### 2. 创建图生视频 (create_video_with_images)

使用图片和文本描述生成视频。

**参数说明:**

| 参数 | 类型 | 必需 | 说明 | 默认值 |
|------|------|------|------|--------|
| `prompt` | string | ✅ | 视频内容描述 | - |
| `input_reference` | string | ✅ | 参考图片 URL | - |
| `size` | string | ❌ | 视频尺寸，格式 `宽x高` | `854x480` |

**使用示例:**

```json
{
  "prompt": "让这些图片中的场景动起来，添加自然的过渡效果",
  "input_reference": "https://example.com/image1.jpg",
  "size": "720x1280"
}
```

图生视频默认也使用 `VIDEO_MODEL=bytedance/seedance-1.5-pro`，并通过 `input_urls` 传图。视频参数同样固定为 `8 秒 / 480p / 开音频`。如果后续供应商拆分图生/文生模型，可额外设置 `VIDEO_IMAGE_MODEL`。

### 3. 查询任务状态 (query_video_task)

查询视频生成任务的进度和结果。

**参数说明:**

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `id` | string | ✅ | 任务 ID (格式: `task_xxx`) |

**使用示例:**

```json
{
  "id": "task_01k6x15vhrff09dkkqjrzwhm60"
}
```

**任务状态说明:**

- `pending` - 任务处理中，请稍候
- `completed` - 任务已完成，可获取视频 URL
- `failed` - 任务失败

## 📚 工作流程

1. **创建任务**: 使用 `create_video` 或 `create_video_with_images` 创建视频生成任务
2. **获取任务 ID**: 任务创建成功后会返回任务 ID
3. **轮询查询**: 使用 `query_video_task` 定期查询任务状态
4. **获取结果**: 任务完成后，从返回结果中获取视频 URL

## 🔧 开发

```bash
# 开发模式 (监视文件变化，自动重新编译)
npm run dev

# 编译构建
npm run build

# 运行服务
npm start
```

## 📖 相关文档

- [云雾 API 文档](https://yunwu.apifox.cn)
- [查询任务 API](https://yunwu.apifox.cn/api-358068905)
- [创建视频(带图片) API](https://yunwu.apifox.cn/api-358068907)
- [创建视频 API](https://yunwu.apifox.cn/api-358068995)

## 💡 使用建议

1. **提示词优化**: 详细、具体的提示词能够生成更好的视频效果
2. **图片质量**: 使用清晰、高质量的图片作为输入可以获得更好的结果
3. **合理选择参数**: 根据需求选择合适的分辨率和时长，避免不必要的资源消耗
4. **任务查询频率**: 建议每 5-10 秒查询一次任务状态，避免过于频繁的请求

## ⚠️ 注意事项

- 确保 API 密钥有足够的余额
- 视频生成可能需要较长时间，请耐心等待
- 图片 URL 必须是公开可访问的
- 遵守云雾 API 的使用条款和限制

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**注意**: 本项目仅供学习和研究使用，请遵守相关法律法规和平台使用条款。