higgsfield

Higgsfield MCP

一个连接器，30 多种模型。订阅费用以点数结算，无需为各个提供商单独配置 API 密钥。

何时使用此技能

仅当用户已经付费订阅 Higgsfield 时，才使用此技能。它的全部价值在于通过一次身份验证访问 30 多种模型，并使用用户已经付费购买的点数结算。不要劝未订阅的用户为了一个项目而订阅。

三项功能

此技能只做三件事，请将使用范围限定于此：

1. 探索模型 — 查看可用模型，以及每个模型接受的角色
2. 生成图像 — 单张或批量生成
3. 生成视频 — 包括图像→视频工作流

安装

有两种连接方式。 两种方式最终都一样：会话可以调用经过身份验证的 MCP。

终端（Claude Code）：

claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp

然后在会话中运行 /mcp，并使用拥有该订阅的 Higgsfield 账户完成 OAuth 身份验证。

Claude 桌面应用：

设置 → 连接器 → 添加自定义连接器 → 粘贴 https://mcp.higgsfield.ai/mcp → 登录。

完成身份验证后 — 必须执行的步骤：

select_workspace

选择工作区之前，生成调用会静默失败。请务必在每次会话开始时运行一次。

注意： 全新安装后，MCP 工具可能不会出现在正在运行的会话中 — 如果 /mcp 显示 Higgsfield 已连接，但看不到任何工具，请重启 Claude Code / Desktop。

无需管理 API 密钥，也无需 .env。身份验证由 MCP 处理。

生成前务必说明点数成本

不可妥协。 在调用任何 generate_image 或 generate_video 之前，说明以下内容：

• 模型和设置
• 预计点数成本（使用下方表格）
• 当前 balance
• 调用后的余额

等待用户明确回复“开始”后再执行。点数并非免费，悄悄消耗点数是最容易损害信任的做法。自动模式也不能跳过此步骤。

成本表（实测数据，并非来自文档）

models_explore 不会返回点数成本 — 这项数据不在 API 中。请使用以下内置表格：

模型	设置	点数
gpt_image_2	2K medium	~3
nano_banana_2	2K	~11
seedance_1_5	480p，4s	~2.4
seedance_1_5	480p，12s	~7.2
更高档位的视频	—	TBD（首次运行时测量）

数据可能会有变动。 如果运行结果看起来不对，请在 Higgsfield 控制面板中核实。测得新数据后，请更新此表。

套餐等级会静默限制模型

高端模型（例如 seedance_2_0）在 Starter 套餐中会被屏蔽，并返回笼统的“Something went wrong”错误 — 不会提供有用的错误信息。如果模型莫名报错，应先怀疑是套餐限制，再排查提示词。建议查看 balance，以推断用户的套餐等级。

工作流机制

上传分为 3 个步骤，而非一步。如果需要反复调用，请将其封装成一个辅助函数：

1. media_upload → 返回预签名 PUT URL 和 media_id
2. 使用 curl -X PUT 将文件字节上传到该 URL
3. media_confirm({ media_id }) → 将其标记为就绪

生成是异步的：

1. 调用 generate_image 或 generate_video → 返回 job_id
2. 轮询 job_status({ job_id, sync: true }) — 通常轮询 1–2 次即可完成（图像约 10–20s，视频耗时更长）

结果字段： 务必提取 rawUrl（PNG / 原始素材）。minUrl 只是 WebP 预览图。

一个参考素材，多次生成 — 上传后的 media_id 在整个会话期间都有效。请在多次调用中复用，而不是重复上传。

并行任务运行正常 — 可以发起多个 generate_image 调用并分别轮询。

传递参考素材

架构为 medias: [{ value, role }]（而非 reference_images）。value 接受以下三种形式：

• media_id — 来自 media_upload / media_confirm
• job_id — 先前生成任务的输出，可用作下一步的输入。图像→视频工作流的杀手级功能 — 生成静态图像后，直接将其 job_id 传给 generate_video，无需重新上传。
• https:// URL — 任何公开的图像 URL

不同模型的角色类型各不相同

在构造调用之前，务必先对模型运行 models_explore action=get。各模型支持的角色并不一致：

模型	支持的角色
Seedance 1.5	start_image、end_image
Seedance 2.0	全部角色（image、start_image、end_image、video、audio）
Kling 3.0	仅 start_image
Nano Banana Pro / GPT Image 2	image

传入错误的角色会导致调用被拒绝。

Seedance 1.5 的时长陷阱

如果省略 duration，Seedance 1.5 会悄悄默认使用 12 秒——成本是 4 秒片段的 3 倍。务必显式传入 duration。

定价说明

• **Plus 套餐：**每月 39 美元，1000 点数——适合广告工作负载
• 充值包（5 美元 / 100 点数）90 天后过期——不要囤积
• 在切换工作流之前，请先在 Higgsfield 控制面板中确认每次调用的确切点数成本

失败处理规则

• 不要悄悄从参考图转视频回退到文本转视频——失去视觉锚点会破坏工作流。应明确指出失败。
• 如果触发内容政策检查，不要在同一模型上用相同输入重试——建议修改输入或更换模型。
• 如果 MCP 出错，请检查 /mcp，确认连接仍然有效。订阅过期会导致身份验证失效。

提供的模型

30 多种模型，共用一个 URL。主要包括：

类别	模型
图像	Nano Banana Pro、GPT Image 2、Flux、Seedream
视频	Seedance 2.0、Sora 2、Veo、Kling、Hailuo
Higgsfield 独家模型	Soul（角色一致性）、Cinema Studio

**限制：**图像最高支持 4K，视频最长 15 秒。