把 Higgsfield 接進 Claude Code：MCP 與 CLI 兩條路，加上不亂燒 credits 的四個設定

瀏覽次數: 1

你在 Claude Code 裡做 landing page，程式碼十分鐘就寫完了，最後卡在一張 hero 圖、一段 5 秒的產品 loop 影片：切去瀏覽器開生成工具、下載、改檔名、拖回 public/，再叫 agent 改 <img src>。整條流程裡最花時間的，反而是你自己手動搬素材。

Higgsfield 最近把這段補上了：官方 help center 有一篇〈How do I connect Higgsfield to AI agent〉，給了兩種接法——遠端 MCP server，以及本機 higgsfield CLI + 官方 Skills。這篇不講 AI 影片產業趨勢，只講一件事：怎麼把 Higgsfield 接進你的 coding agent，而且不讓它亂燒 credits。

先講清楚：以下內容是讀官方 help center、Higgsfield 的 CLI repo（higgsfield-ai/cli）和 Skills repo（higgsfield-ai/skills，v0.12.0，MIT 授權）整理出來的，我沒有拿付費帳號實際跑過生成。會標出哪些是文件寫的，哪些「值得實測」。

本文大綱

一、它到底解決什麼問題

coding agent 很會寫程式，但產出多媒體素材一直是它的盲區。常見的替代方案不是寫 placeholder，就是你自己跑去別的工具生圖。Higgsfield 本身是影像／影片生成平台，官方 CLI 的 README 寫明底下有 40+ 個模型（Nano Banana Pro、GPT Image 2.5、Soul V2、Veo 3.1、Kling v3.0、Seedance 2.5 等）；MCP 頁面寫的是 30+。數字不一樣，比較可能是兩份文件更新時間不同，不用太在意。

對工程師來說，重點不在「有很多模型」，而在這三件事：

agent 可以自己下指令生成，拿到結果 URL 後直接寫進程式碼。
CLI 有 --json 輸出，可以跟 jq、腳本、CI 串起來。
有先估價的指令（generate cost），可以擋在真正扣錢的那一步前面。

二、兩條接法怎麼選

路線 A：MCP（遠端託管，OAuth）

官方 help center 給的 MCP 網址是 https://mcp.higgsfield.ai/mcp，登入走 OAuth，不用管 API key。各家客戶端的加法：

Claude（claude.ai / Claude Desktop）：Settings → Connectors → Add custom connector → 名稱填 Higgsfield、貼上 MCP URL → 用 Higgsfield 帳號授權。
Cursor：Customize → Marketplace → 找 Higgsfield → Add → 登入。
ChatGPT：Plugins Directory → Higgsfield → Add。help center 註明 ChatGPT 版沒有音訊生成，也沒有 Website Building skill。

Claude Code 的話，help center 分類在「CLI agents」底下，建議走路線 B。如果你還是想用 MCP，可以用 Claude Code 加 remote MCP 的標準寫法：

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

加完進 Claude Code 打 /mcp，照提示完成登入授權，順便看一下它實際開放了哪些 tool。help center 列出的能力有：圖片／影片生成與放大、去背、圖片 outpaint 與影片 reframe、Kling 3.0 Motion Control、Soul 角色、音訊（配音、聲音複製、配音翻譯）、查 credit 餘額。

路線 B：CLI + Skills（本機，推薦給 coding agent）

help center 給 CLI 型 agent 的指令只有三行：

npm i -g @higgsfield/cli
higgsfield auth login
npx skills add higgsfield-ai/skills

CLI repo 另外還提供了 curl 安裝腳本和 Homebrew（brew install higgsfield-ai/tap/higgsfield）。Skills 也有其他裝法，在 Claude Code 裡可以直接走 plugin marketplace：

/plugin marketplace add higgsfield-ai/skills
/plugin install higgsfield@higgsfield

裝好之後，你會拿到一組 /higgsfield:* 指令，例如 /higgsfield:generate（通用生成）、/higgsfield:soul-id（訓練人臉角色）、/higgsfield:product-photoshoot、/higgsfield:youtube-thumbnail、/higgsfield:websites。

我的建議是 coding agent 走路線 B，理由有三個：

看得見：每一步都是 shell 指令，會留在 transcript，出錯時可以直接複製重跑。
管得住：Bash 指令可以用 Claude Code 的權限規則逐條 allow 或 ask，下一節會示範。
能串接：--json 輸出可以交給 jq 處理，也可以寫進 Makefile 或 CI。

MCP 比較適合在聊天介面裡隨手產素材，不需要留下可重現流程的時候用。

三、運作原理：一次生成背後發生什麼事

CLI 的指令結構很規律。README 的 Commands 表裡，跟 agent 最相關的是這幾個：

指令	作用
`higgsfield account status`	目前帳號、方案、剩餘 credits
`higgsfield model list` / `model get <id>`	列出模型、查某個模型的參數 schema
`higgsfield generate cost <id> ...`	估算這次要花多少 credits，不會送出
`higgsfield generate create <id> ...`	送出生成任務
`higgsfield generate wait / get / list`	等待、查詢、列出任務
`higgsfield workflow list / get`	較高階的流程（例如 `reframe`、`draw_to_video`）

生成是非同步的：create 會先送出一個 job，影片通常要等一陣子。加上全域 flag --wait，指令會一直等到 job 結束，然後直接印出結果 URL。預設最多等 10m（--wait-timeout），每 3s 輪詢一次（--wait-interval）。Skill 檔裡也要求 agent 一律用 create ... --wait 一次做完，不要拆成 create 再 wait 兩步。

媒體輸入也做得很省事：--image、--start-image、--end-image、--video、--audio 可以直接給本機路徑，CLI 會自動上傳，不需要先手動 upload。

一個典型的圖生影片指令長這樣（取自 CLI README）：

higgsfield generate create kling3_0 \
  --prompt "slow camera push through a forest clearing at dawn" \
  --start-image ./first.png \
  --duration 5 --mode pro --sound off \
  --wait

Skill 怎麼讓 agent「會選模型」

higgsfield-generate/SKILL.md 本質上是一份給 agent 看的路由表。frontmatter 寫了 allowed-tools: Bash，內文依任務類型指定預設模型：

一般圖片、設計圖、圖上有文字 → GPT Image 2.5
正式影片、圖生影片 → Seedance 2.5（文件寫支援 4–30 秒，最高 1080p）
單一場景、動態不強、想省錢 → Kling 3.0
快速便宜的迭代 → Z Image
廣告、UGC → Marketing Studio

另外還有一條「Discovery guardrail」：agent 找不到某個模型時，不能只靠語意搜尋或 --help，要先跑一次不加過濾的 model list。這點很實用，模型 ID 常常跟顯示名稱對不上（例如 Virality Predictor 的技術名稱是 brain_activity）。

四、實戰設定：讓 agent 產素材，但不亂花錢

這一節是全文重點。先說一個容易被忽略的衝突：

官方 help center 建議你事先跟 agent 講好「Do not spend more than X credits」。
但 higgsfield-generate/SKILL.md 的 UX Rules 第 5 條寫的是：除非使用者主動問，否則不要事先估價，也不要為了省錢改選便宜模型，優先用品質最好的預設。

也就是說，裝完官方 skill 什麼都不改的話，agent 預設會「直接用好模型生成」。做個人創作可能沒問題，但放在一個會重試、會批次跑的 coding agent loop 裡，就得自己加一道閘門。

招式 1：用 Claude Code 權限規則把「扣錢」設成要你點頭

在專案的 .claude/settings.json 加上：

{
  "permissions": {
    "allow": [
      "Bash(higgsfield account status:*)",
      "Bash(higgsfield model:*)",
      "Bash(higgsfield generate cost:*)",
      "Bash(higgsfield generate get:*)",
      "Bash(higgsfield generate list:*)"
    ],
    "ask": [
      "Bash(higgsfield generate create:*)",
      "Bash(higgsfield generate workflow:*)",
      "Bash(higgsfield soul-id:*)",
      "Bash(higgsfield website:*)"
    ]
  }
}

只讀、不花錢的指令全部放行，會扣 credits 或對外部署的指令一律先問你。規則採前綴比對，如果 agent 把指令包進 sh -c 或管線裡，可能比對不到，所以要搭配招式 2 一起用。

招式 2：在 CLAUDE.md 寫下預算規則，覆蓋 skill 的預設

## Higgsfield 使用規則
- 送出任何 `higgsfield generate create` 之前，先用同樣參數跑 `higgsfield generate cost`，把估價跟我回報。
- 單次估價超過 20 credits，或本次 session 累計超過 100 credits：停下來問我，不要自己改用便宜模型重試。
- 草稿階段用 z_image 或 kling3_0；我說「定稿」之後才用預設的高品質模型。
- 失敗後最多重試 1 次；遇到 nsfw / ip_detected 要先改 prompt，再問我要不要重送。
- 產出的 URL 寫進 `assets/manifest.json`（記錄 model、prompt、job id），不要只貼在對話裡。

上面的數字請換成你自己方案能接受的額度。重點是把規則寫明，避免 agent 照 skill 預設的「品質優先」去跑。

招式 3：把結果變成可重現的資產清單

CLI 的 --json 就是用在這裡。README 範例：

higgsfield generate list --json | jq -r '.[] | select(.status=="completed") | .result_url'

你可以叫 agent 在每次生成後把 job id 和 prompt 記進 manifest。之後要重做、要換模型比較，都有依據。

招式 4：影片的運鏡寫法

Higgsfield 網頁版的 Camera Controls 頁面主打 50+ 種運鏡預設，包括 Dolly In/Out、Crane、FPV Drone、Bullet Time、360 Orbit、Snorricam 等，頁面上標示的後端有 Kling、Minimax Hailuo、Wan2.5。不過從 CLI 文件看，大多數影片模型沒有「選運鏡預設」這個參數，運鏡要寫在 prompt 裡。Skill 附的 prompt-engineering.md 提供了具體寫法：

有 --start-image 時，prompt 只描述動態，不要重新描述畫面，因為模型已經拿到首幀了。
動詞用 zooms in、dollies left、sweeping pan、slow push、fast whip。
prompt 控制在約 200 tokens 以內，太長反而會失真。
大多數模型不支援 negative prompt，要改成正面描述：不寫「no blur」，寫「tack sharp」。

給 agent 的 prompt 範例：

用 /higgsfield:generate 把 ./public/hero.png 做成 5 秒 16:9 的圖生影片。
運鏡：slow push in，鏡頭緩慢推近螢幕上的 dashboard，不要重新描述畫面內容。
先用 kling3_0 出草稿並回報估價；我確認後再用 seedance_2_5 出 1080p 定稿。

另外，MODELS.md 裡的 Cinematic Studio 3.0 和 Cinematic Studio Video V2 有 --preset_id 和 --speedramp（例如 slowmo、impact）參數。但我在文件中沒找到怎麼列出這兩個模型可用的 preset id，值得實測的做法是先跑 higgsfield model get cinematic_studio_3_0 --json，再搭配 higgsfield preset list --help 查查看。

五、數據與限制（誠實版）

計費：help center 寫明所有生成都依「standard rates」扣 credits，MCP 不提供「unlimited model access」和免費生成，而且需要有效的付費訂閱。Higgsfield 自家 blog 另一篇 MCP 教學則提到新帳號有 signup free credits。兩份文件說法不一致，以你帳號的實際狀態為準，開始前先跑 higgsfield account status。
能力上限：CLI／MCP 頁面寫圖片最高 4K、影片最長 15 秒。但 SKILL.md 寫 Seedance 2.5 支援 4–30 秒。上限會因模型而不同，以 model get 查到的 schema 為準。
成品出現時間：help center 寫結果會在 60 秒內出現在 Assets。這指的是出現在素材庫的時間，不是生成時間；影片生成時間依模型和長度而定。
Token 很短命：README 的 Troubleshooting 寫明 token 是 short-lived，遇到 Session expired 就重跑 higgsfield auth login。這一步需要開瀏覽器，agent 沒辦法自己完成，長時間無人值守的 loop 要考慮到這點。
文件小矛盾：Skill 的 troubleshooting.md 寫逾時可以用 --timeout 30m，但 CLI README 列的全域 flag 是 --wait-timeout。以 CLI README 為準。
估價有例外：README 註明 voice-change 和 dubbing 這兩個 workflow 不支援估價，招式 2 的預算規則碰到它們要改成直接問你。
其他常見錯誤：HTTP 429 代表請求太頻繁，要退避；如果回應是 captcha 頁面（DataDome），官方建議等 30 秒再試。

六、什麼時候該用、什麼時候別用

適合：

做網站或 app 時，需要 hero 圖、OG 圖、產品 loop 影片，而且想讓 agent 產完直接寫進 repo。
要大量產出規格相近的素材（多尺寸、多比例），可以用腳本加 --json 批次處理。
已經是 Higgsfield 付費用戶，想把現有 credits 用在開發流程裡。

不適合：

需要精準數據或固定排版的圖（圖表、比較表）。生成模型不保證數字正確，用 HTML／SVG 產比較可靠。
沒有付費訂閱、只想試玩：MCP 需要付費方案。
完全無人值守的 CI：OAuth 要人工登入、token 又短命，這點值得先實測，確認你的帳號在 CI 上能不能穩定運作。

七、給工程團隊的落地清單

個人先裝路線 B，跑一次 higgsfield generate create z_image --prompt "test" --wait（官方 INSTALL_FOR_AGENTS.md 的驗證步驟），確認拿得到 URL。
把招式 1 的 permissions 寫進 repo 的 .claude/settings.json 並 commit，讓團隊共用同一套閘門。
把招式 2 的預算規則寫進 CLAUDE.md，額度依方案調整。
約定素材一律記進 manifest（model、prompt、job id），PR review 時才看得到素材是怎麼產出來的。
草稿用便宜模型，定稿才用高品質模型，這條規則要寫明，不要依賴 skill 的預設行為。