Higgsfield AI MCP服务器
🔧 最近修复（2025年11月2日）
视频生成现在可以正常工作了！ 这 generate_video 函数已修复为使用正确的API格式：
- 已添加必填项
prompt参数（可选，如果未提供，则自动生成） - 来自的固定API有效负载结构
image_url到input_images数组格式 - 添加了全面的文档和示例
看 HIGGSFIELD_VIDEO_GENERATION_GUIDE.md 在父目录中查看详细用法。
特性
- 文本到图像生成：使用Soul模型创建高质量图像
- 图像转视频：将静态图像转换为具有运动预设的5秒电影视频
- 字符一致性：创建可重用的字符引用，以实现跨代一致的外观
- 样式预先设定：浏览和应用电影风格预设
- 运动库：访问预先设计的运动效果以生成视频
安装
先决条件
- Python 3.10或更高版本
- pip（Python包安装程序）
- 拥有API证书的Higgsfield AI账户(注册)
设置
- 克隆或下载此存储库
- 安装依赖项 （选择一种方法）：
选项A：使用pip（为简单起见建议使用）
cd higgsfield_ai_mcp
pip install -r requirements.txt选项B：使用诗歌
cd higgsfield_ai_mcp
poetry install- 配置API凭据 （选择一种方法）：
选项A：环境变量（建议用于.env文件）
cp .env.example .env编辑 .env 并添加您的Higgsfield AI凭据：
HF_API_KEY=your-api-key-here
HF_SECRET=your-secret-key-here选项B：命令行参数
运行服务器时直接传递凭据：
python -m higgsfield_mcp.server --api-key YOUR_KEY --secret YOUR_SECRET从以下位置获取API密钥：https://cloud.higgsfield.ai/api-keys
用法
本地开发和测试
测试服务器：
# Run directly with Python
python -m higgsfield_mcp.server
# Or with command line arguments
python -m higgsfield_mcp.server --api-key YOUR_KEY --secret YOUR_SECRET
# Run in development mode with auto-reload (if using Poetry)
poetry shell
fastmcp dev src/higgsfield_mcp/server.pyClaude桌面集成
将此服务器添加到您的Claude Desktop配置中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json
方法1：直接使用Python和环境变量（推荐）
{
"mcpServers": {
"higgsfield": {
"command": "python",
"args": [
"-m",
"higgsfield_mcp.server"
],
"cwd": "/absolute/path/to/higgsfield_ai_mcp",
"env": {
"HF_API_KEY": "${HF_API_KEY}",
"HF_SECRET": "${HF_SECRET}"
}
}
}
}方法2：使用命令行参数
{
"mcpServers": {
"higgsfield": {
"command": "python",
"args": [
"-m",
"higgsfield_mcp.server",
"--api-key",
"${HF_API_KEY}",
"--secret",
"${HF_SECRET}"
],
"cwd": "/absolute/path/to/higgsfield_ai_mcp"
}
}
}方法3：使用诗歌（如果您安装了诗歌）
{
"mcpServers": {
"higgsfield": {
"command": "/Users/YOUR_USERNAME/.local/bin/poetry",
"args": [
"run",
"python",
"-m",
"higgsfield_mcp.server"
],
"cwd": "/absolute/path/to/higgsfield_ai_mcp",
"env": {
"HF_API_KEY": "${HF_API_KEY}",
"HF_SECRET": "${HF_SECRET}"
}
}
}
}备注:
- 替换
/absolute/path/to/higgsfield_ai_mcp此目录的实际路径 - 对于方法1和2，确保
HF_API_KEY和HF_SECRET在shell环境中设置 - 对于诗歌的方法3，使用完整路径（否
~扩展） - 添加配置后，重新启动Claude Desktop
FastMCP云部署
部署到FastMCP Cloud进行远程访问：
# Install FastMCP CLI
pip install fastmcp
# Deploy (requires FastMCP Cloud account)
fastmcp deploy src/higgsfield_mcp/server.py可用工具
generate_image
根据文本提示生成高质量图像。
参数:
prompt（必填）：详细的文本描述quality：“720p”或“1080p”（默认）character_id：用于一致性的可选字符引用IDstyle_id：可选样式预设ID
示例:
Generate an image: "A woman with sharp eyes sitting on a minimalist bench in a desert garden, wearing a sand-colored suit, late afternoon sunlight"generate_video
将图像转换为具有运动效果的电影视频。
参数:
image_url（必填）：源图像URL（必须通过HTTPS公开访问）motion_id（必填）：运动预设ID（使用浏览higgsfield://motions资源）prompt（可选）：图像/场景的描述。如果未提供，则自动生成。quality：“lite”、“turbo”或“standard”（默认）
示例:
generate_video(
image_url="https://cdn.example.com/beach-selfie.png",
motion_id="31177282-bde3-4870-b283-1135ca0a201a",
prompt="A woman taking a selfie at a beach construction site",
quality="turbo"
)重要说明:
- 图像URL必须可公开访问（Higgsfield服务器需要下载它）
- 处理需要20-60秒，具体取决于质量
- 投票
get_generation_status每10秒检查一次完成情况 - 结果将缓存7天
create_character
创建可重用的字符引用以实现一致的生成。
参数:
name（必填）：字符的描述性名称image_urls（必填）：显示面部的1-5个图像URL列表
成本：40学分（2.50美元）
get_generation_status
检查作业状态并检索结果。
参数:
job_set_id（必填）：generate_image/generate_video中的作业ID
作业状态:
queued：正在等待启动in_progress：目前正在生成completed：完成！结果可用failed：生成失败nsfw：内容筛选器已触发
list_characters
列出所有创建的带有ID和状态的角色引用。
可用资源
使用MCP资源浏览数据源：
higgsfield://styles：可用的灵魂图像样式预设higgsfield://motions：DoP型号的视频运动预设higgsfield://characters：您创建的角色引用
工作流示例
- 浏览可用样式:
- 访问 higgsfield://styles 查看样式选项的资源
- 生成图像:
generate_image(
prompt="Professional headshot in modern office",
quality="1080p",
style_id="1cb4b936-77bf-4f9a-9039-f3d349a4cdbe"
)→ 退货 job_set_id
- 检查状态并获取结果:
get_generation_status(job_set_id="...")→ 完成后返回下载URL
- 创建一致性字符 （可选）：
create_character(
name="Jane Doe",
image_urls=["https://example.com/face1.jpg", "https://example.com/face2.jpg"]
)→ 退货 character_id
- 用字符生成:
generate_image(
prompt="Same person in a different scene",
character_id="3eb3ad49-775d-40bd-b5e5-38b105108780"
)- 将结果动画化:
- 浏览 higgsfield://motions 用于运动预设
generate_video(
image_url="https://result-from-step-5.jpg",
motion_id="motion-preset-id",
quality="standard"
)定价
当发电成功完成时（而不是在故障时）收取积分：
- 图像生成（灵魂）:
- 720p：每张图片1.5学分（0.09美元） - 1080p：每张图片3个学分（0.19美元） - 前1000代：1080p 1学分（0.06美元）
- 视频生成（DoP）:
- 精简版：2学分（0.125美元） - 涡轮增压：6.5学分（0.406美元）-2倍速度 - 标准：9学分（0.563美元）-最高质量
- 角色创建：一次性40个学分（2.50美元）
价格：$1=16学分 在以下位置添加学分：https://cloud.higgsfield.ai/credits
故障排除
“缺少必需的环境变量”
- 确保
.env文件存在HF_API_KEY和HF_SECRET - 或者在shell或Claude Desktop配置中设置环境变量
“401未经授权”
- 验证您的API密钥和机密是否正确
- 检查它们是否已过期或被撤销
“402需要付款”
- 将积分添加到您的Higgsfield帐户
- 访问：https://cloud.higgsfield.ai/credits
服务器未出现在Claude Desktop中
- 检查
cwd路径是绝对的，不是相对的 - 验证诗歌是否已安装且可访问
- 配置更改后重新启动Claude Desktop
- 检查Claude Desktop日志是否有错误
一代人陷入“排队”状态
- 等待几秒钟，然后再次轮询
- 检查您的帐户是否有足够的信用额度
- 在高负载期间，作业可能需要更长的时间
项目结构
mcp_creator/
├── src/
│ └── higgsfield_mcp/
│ ├── __init__.py
│ ├── server.py # FastMCP server with tools & resources
│ └── client.py # Async Higgsfield API wrapper
├── pyproject.toml # Poetry configuration
├── .env.example # Credential template
├── .env # Your credentials (gitignored)
├── .gitignore
└── README.md发展
运行测试
poetry shell
fastmcp dev src/higgsfield_mcp/server.py添加新工具
编辑 src/higgsfield_mcp/server.py 并添加新 @mcp.tool 装饰功能。
添加新的API方法
编辑 src/higgsfield_mcp/client.py 以添加新的API客户端方法。
资源
许可证
MIT许可证-有关详细信息，请参阅许可证文件
贡献
欢迎投稿！请打开问题或拉取请求。
支持
- Higgsfield人工智能支持：https://cloud.higgsfield.ai/support
- MCP文件：https://modelcontextprotocol.io
- 文件问题：在此存储库中创建问题