项目介绍
基于火山引擎的图像生成服务
基于火山引擎（抖音豆包）的图像生成服务，特别设计用于与Cursor MCP服务集成。支持自定义图像纵横比、保存路径等功能，提供高质量的图像生成能力。
特性
- 支持高质量图像生成
- 支持多种常见纵横比（1:1, 4:3, 16:9, 3:4, 9:16）
- 使用火山引擎豆包模型（doubao-seedream-3-0-t2i-250415）
- 自动重试和详细的错误处理
- 完整的路径和权限验证
- 详细的错误提示和日志
- 支持异步处理
环境准备
1. Python环境
- Python 3.10+
- 下载链接：https://www.python.org/downloads/
- 推荐使用pyenv管理Python版本：
# macOS安装pyenv
brew install pyenv
# 安装Python
pyenv install 3.13.2
pyenv global 3.13.2
2. Node.js环境
3. UV包管理工具
UV是一个快速的Python包管理器，需要安装以下内容：
# macOS安装uv
brew install uv
# 或者使用pip安装
pip install uv
4. 火山引擎API密钥
- 访问火山引擎Ark大模型服务
- 注册/登录账户
- 创建一个新的API密钥
- 复制密钥并以以下格式保存：
YOUR_API_KEY
5. Cursor
- 下载并安装Cursor IDE
- 确保已正确配置Cursor的Python环境
安装与配置
1. 克隆项目
git clone https://github.com/chenyeju295/mcp_generate_images.git
cd mcp_generate_images
2. 安装依赖项（进入mcp_generate_images安装目录）
python3 -m pip install fastmcp requests 'volcengine-python-sdk[ark]'
或者使用requirements.txt文件：
pip install -r requirements.txt
如果遇到证书问题，可以使用：
python3 -m pip install fastmcp requests 'volcengine-python-sdk[ark]' --trusted-host pypi.org --trusted-host files.pythonhosted.org --upgrade --force-reinstall --no-cache-dir
提示：确保成功安装，否则配置MCP服务时会出现红色警告。
3. 配置API密钥
设置环境变量（推荐方法）：
export ARK_API_KEY=your_api_key_here
或在~/.bashrc或~/.zshrc中添加：
echo 'export ARK_API_KEY=your_api_key_here' >> ~/.zshrc
source ~/.zshrc
验证环境变量是否已设置：
echo $ARK_API_KEY
4. 配置服务
在mcp_server.py中可修改以下配置：
CONFIG = {
"api": {
"base_url": "https://ark.cn-beijing.volces.com/api/v3",
"model": "doubao-seedream-3-0-t2i-250415",
"timeout": 120,
"max_retries": 3,
"retry_delay": 5
},
"image": {
"max_width": 1024,
"max_height": 1024,
"default_width": 1024,
"default_height": 1024,
"max_batch_size": 1
},
"output": {
"base_folder": "你的默认保存路径",
"allowed_extensions": [".png", ".jpg", ".jpeg"],
"default_extension": ".png"
}
}
运行服务
开发模式操作（带有调试接口）：
uv run --with fastmcp fastmcp dev /Users/username/Documents/mcp_generate_images/mcp_server.py
在Cursor中的使用
1. 在Cursor中引入MCP服务
添加：
{
"mcpServers": {
"generate_images": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"/Users/chenyeju/Documents/github/mcp_generate_images/mcp_server.py"
]
}
}
}
3. 成功服务运行示例
4. 在Cursor Composer代理模式下的使用
参数描述
图像生成工具支持以下参数：
| 参数名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| Prompt | 字符串 | 是 | 图像生成提示词，建议不超过500字符 |
| FileName | 字符串 | 是 | 保存文件名（不含路径，默认无后缀为.png） |
| Savefolder | 字符串 | 是 | 保存目录的绝对路径 |
| Aspect_ratio | 字符串 | 否 | 图像纵横比，支持'1:1','4:3','16:9','3:4','9:16'。默认为'1:1' |
使用示例
生成一张宽高比为16:9的风景图片：
generate_image(
prompt="美丽的落日山景",
file_name="landscape.png",
save_folder="/Users/username/Documents/images",
aspect_ratio="16:9"
)
使用注意事项
- 模型使用火山引擎豆包模型（doubao-seeddream-3-0-t2i-250415），支持的最大尺寸为1024x1024。
- 纵横比建议使用1:1的纵横比（正方形图像），如512x512或1024x1024，以获得最佳效果和生成速度。
- 提示词简洁明了的提示词通常能获得更好的结果，最大长度为500字符。支持中文提示词。
- 超时问题对于复杂的提示词或非正方形图像，生成可能耗时较长，有时会导致超时错误。
- API限制火山引擎API每次只生成一张图像，这与之前的批量生成不同。
故障排除
如果遇到问题，请检查：
- 服务是否正常运行
- 保存路径是否正确（必须是绝对路径）
- 目录权限是否正确
- 网络连接是否正常
- API密钥是否有效
- Python环境是否配置正确
- UV是否安装正确
- 依赖包是否完全安装
常见错误及解决方案
| 错误信息 | 可能原因 | 解决方案 |
|---|---|---|
| 无法生成图像：API请求超时 " | 网络问题或请求时间过长 | 使用更简单的提示词，检查网络连接 |
| 无法生成图像：API调用频率受限 " | 火山引擎API频率限制 | 等待几分钟后重试 |
| 无法生成图像：API认证失败 " | 无效的API密钥 | 检查并更新火山引擎API密钥 |
| 没有权限保存图像到... " | 目录权限问题 | 确保目录存在且具有写入权限 |
| 不支持的纵横比 " | 使用了不支持的纵横比 | 使用支持的纵横比：'1:1', '4:3', '16:9', '3:4', '9:16' |
| 无法下载生成的图像 " | 图像下载失败 | 检查网络连接，确保可以访问火山引擎的图像URL |