geo higgsfield AI MCP

Higgsfield AI MCP服务器

MCP（模型上下文协议）服务器 希格斯菲尔德人工智能 API-支持AI驱动的图像生成、视频创建和语音合成功能。

特性

🎨 文本到图像（灵魂模型）

• 根据文本提示生成高质量图像
• 多种图像大小和质量选项
• 自定义样式预设和角色参考
• 批量生成支持

🎬 图像到视频（DOP模型）

• 使用运动预设为静态图像设置动画
• 起始和结束框架支撑
• 可定制的运动强度

🗣️ 演讲转视频

• 生成对话头视频
• 自定义图像和音频输入
• 质量和持续时间可调

👤 角色管理

• 创建一致的字符引用
• 跨代使用
• 管理字符库

📊 作业管理

• 异步作业状态跟踪
• Webhook通知
• 结果检索

安装

先决条件

• Python 3.10或更高版本
• Higgsfield AI API证书(把他们带到这儿来)

通过pip安装

pip install higgsfield-mcp

从源代码安装

git clone 
cd higgsfield-mcp
pip install -e .

🚀 Claude代码的快速设置

使用克劳德代码CLI？看 CLAUDE_CODE_SETUP.md 获取分步说明。

太长，读不下去了

1. pip install higgsfield-mcp
2. 增添 .mcp.json:

{
  "mcpServers": {
    "higgsfield": {
      "command": "higgsfield-mcp",
      "env": {
        "HIGGSFIELD_API_KEY": "your-key",
        "HIGGSFIELD_SECRET": "your-secret"
      }
    }
  }
}

1. 重新启动Claude Code并开始生成！

配置

1.设置环境变量

创建一个 .env 项目目录中的文件：

HIGGSFIELD_API_KEY=your-api-key-here
HIGGSFIELD_SECRET=your-secret-here

或者将它们导出到您的shell中：

export HIGGSFIELD_API_KEY=your-api-key-here
export HIGGSFIELD_SECRET=your-secret-here

2.配置MCP客户端

添加到您的MCP客户端配置中（例如，Claude Desktop config.json):

{
  "mcpServers": {
    "higgsfield": {
      "command": "python",
      "args": ["-m", "higgsfield_mcp.server"],
      "env": {
        "HIGGSFIELD_API_KEY": "your-api-key-here",
        "HIGGSFIELD_SECRET": "your-secret-here"
      }
    }
  }
}

或者，如果通过pip安装：

{
  "mcpServers": {
    "higgsfield": {
      "command": "higgsfield-mcp",
      "env": {
        "HIGGSFIELD_API_KEY": "your-api-key-here",
        "HIGGSFIELD_SECRET": "your-secret-here"
      }
    }
  }
}

可用工具

文本到图像

generate_image_soul

使用Soul模型从文本提示生成图像。

参数：

• prompt （必填）：图像的文字描述
• width_and_height （可选）：图像尺寸（默认值：“1696x960”）

- 选项：“1152x2048”、“2048x1152”、“2040x1536”、“1536x2048“等。

• enhance_prompt （可选）：自动增强提示（默认值：true）
• quality （可选）：“720p”或“1080p”（默认为“720p”）
• batch_size （可选）：1或4（默认值：1）
• style_id （可选）：样式预设UUID
• style_strength （可选）：0-1（默认值：1.0）
• seed （可选）：再现性为1-1000000
• custom_reference_id （可选）：字符引用UUID
• custom_reference_strength （可选）：0-1（默认值：1.0）
• image_reference_url （可选）：参考图像URL
• webhook_url （可选）：用于完成通知的Webhook
• webhook_secret （可选）：Webhook秘密

例子：

{
  "prompt": "A serene mountain landscape at sunset",
  "width_and_height": "2048x1152",
  "quality": "1080p",
  "enhance_prompt": true
}

get_soul_styles

获取可用样式预设列表。

退货： 带有id、名称、描述和preview_url的样式列表

______________________________________________________________________

图像转视频

generate_video_dop

使用DOP模型从静态图像生成视频。

参数：

• input_image_url （必填）：源图像URL
• prompt （必填）：动画描述
• model （可选）：型号名称（默认：“dop-turbo”）
• seed （可选）：可重复性种子
• motions （可选）：运动预设数组〔｛id，strength｝〕
• input_image_end_url （可选）：结束帧URL
• enhance_prompt （可选）：自动增强（默认值：true）
• webhook_url （可选）：完成webhook
• webhook_secret （可选）：Webhook秘密

例子：

{
  "input_image_url": "https://example.com/image.jpg",
  "prompt": "The person slowly turns their head and smiles",
  "motions": [
    {"id": "motion-uuid", "strength": 0.7}
  ]
}

get_motions

获取可用运动预设列表。

退货： 带有id、名称、描述和preview_url的运动列表

______________________________________________________________________

演讲转视频

generate_speech_video

从文本生成对话头视频。

参数：

• prompt （必填）：语音文本
• input_image_url （可选）：人脸图像URL
• input_audio_url （可选）：音频URL
• quality （可选）：质量设置（默认值：“高”）
• enhance_prompt （可选）：自动增强（默认值：false）
• seed （可选）：可重复性种子
• duration （可选）：持续时间（秒）
• webhook_url （可选）：完成webhook
• webhook_secret （可选）：Webhook秘密

例子：

{
  "prompt": "Hello, welcome to our presentation!",
  "input_image_url": "https://example.com/face.jpg",
  "quality": "high"
}

______________________________________________________________________

角色管理

create_character

创建自定义字符引用以实现一致的生成。

参数：

• name （必填）：字符名称（最多100个字符）
• image_urls （必填）：1-100个图像URL的数组

例子：

{
  "name": "My Character",
  "image_urls": [
    "https://example.com/photo1.jpg",
    "https://example.com/photo2.jpg"
  ]
}

退货： 角色对象 id 使用于 custom_reference_id

get_character

获取角色详细信息和处理状态。

参数：

• reference_id （必填）：字符UUID

delete_character

删除字符引用。

参数：

• reference_id （必填）：字符UUID

______________________________________________________________________

作业管理

get_job_status

检查生成作业的状态并检索结果。

参数：

• job_set_id （必需）：作业集UUID（从生成调用返回）

退货： 带有状态和结果URL的作业详细信息

______________________________________________________________________

使用示例

示例1：生成图像

# Using MCP client
result = await client.call_tool(
    "generate_image_soul",
    {
        "prompt": "A cyberpunk city at night with neon lights",
        "width_and_height": "2048x1152",
        "quality": "1080p"
    }
)

# Get the job_set_id from result
job_set_id = result["id"]

# Check status
status = await client.call_tool(
    "get_job_status",
    {"job_set_id": job_set_id}
)

示例2：创建角色并在生成中使用

# Create character
character = await client.call_tool(
    "create_character",
    {
        "name": "John Doe",
        "image_urls": ["https://example.com/john.jpg"]
    }
)

character_id = character["id"]

# Wait for character to be ready
while True:
    status = await client.call_tool(
        "get_character",
        {"reference_id": character_id}
    )
    if status["status"] == "completed":
        break
    await asyncio.sleep(5)

# Generate image with character
result = await client.call_tool(
    "generate_image_soul",
    {
        "prompt": "Professional headshot in a suit",
        "custom_reference_id": character_id,
        "custom_reference_strength": 0.8
    }
)

示例3：为图像设置动画

# Get available motions
motions = await client.call_tool("get_motions", {})

# Generate video
result = await client.call_tool(
    "generate_video_dop",
    {
        "input_image_url": "https://example.com/portrait.jpg",
        "prompt": "Person looks around with a gentle smile",
        "motions": [
            {"id": motions[0]["id"], "strength": 0.6}
        ]
    }
)

API响应格式

生成请求返回作业集对象：

{
  "id": "job-set-uuid",
  "type": "text2image_soul",
  "created_at": "2023-11-07T05:31:56Z",
  "jobs": [
    {
      "id": "job-uuid",
      "job_set_type": "text2image_soul",
      "status": "queued",
      "results": {
        "min": {
          "type": "image_url",
          "url": "https://..."
        },
        "raw": {
          "type": "image_url",
          "url": "https://..."
        }
      }
    }
  ],
  "input_params": {}
}

作业状态：

• queued -作业正在等待开始
• in_progress -作业正在处理中
• completed -作业已成功完成
• failed -作业失败
• nsfw -内容已过滤

网络钩子

对于异步工作流，请提供一个webhook URL，以便在作业完成时接收通知：

{
  "prompt": "...",
  "webhook_url": "https://your-server.com/webhook",
  "webhook_secret": "your-secret"
}

Webhook负载将作业集格式与完成的结果相匹配。

错误处理

服务器返回描述性错误消息：

{
  "error": "Higgsfield API Error: API request failed with status 422: ..."
}

常见错误：

• 401：API凭据无效
• 422：无效参数
• 500：生成失败

发展

设置开发环境

# Clone repository
git clone 
cd higgsfield-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check .

项目结构

higgsfield-mcp/
├── src/
│   └── higgsfield_mcp/
│       ├── __init__.py
│       ├── client.py       # Higgsfield API client
│       └── server.py       # MCP server implementation
├── tests/
│   └── test_client.py
├── pyproject.toml
├── README.md
└── .env.example

资源

• Higgsfield人工智能文档
• MCP协议规范
• 获取API凭据

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

• API希格斯菲尔德： docs.higgsfield.ai
• MCP服务器：在GitHub上打开一个问题

______________________________________________________________________

由...制作❤️ 对于MCP生态系统