Higgsfield CLI + Skills｜安裝與指令教學

官方倉庫：higgsfield-ai/cli（npm 套件 @higgsfield/cli）與 higgsfield-ai/skills。本頁指令全部取自官方 README／Skills 原文。cli-readme skills-repo

1. 安裝（三選一）

來源：cli-readme

給 Agent 的一鍵版（官方網誌）：讓 Claude Code／Codex 等執行 npm i -g @higgsfield/cli → higgsfield auth login（瀏覽器確認）→ npx skills add higgsfield-ai/skills。blog:generate-ai-videos-ai-agents-2026

2. 第一次使用：逐步

flowchart LR
  A[安裝 CLI] --> B[higgsfield auth login]
  B --> C[higgsfield account / workspace]
  C --> D[higgsfield model list]
  D --> E[higgsfield generate cost ...]
  E --> F[higgsfield generate create ... --wait]
  F --> G[generate get / list --json]

1. higgsfield auth login 登入（瀏覽器 OAuth）。
2. higgsfield model list 看可用模型 ID（例如 nano_banana_2、seedance_2_0、kling3_0）。各模型參數見本庫每個模型頁的「CLI 參數」表。
3. 先用 generate cost 估算 credits，再 generate create。
4. 加 --wait 會阻塞至完成（預設 --wait-timeout 10m、--wait-interval 3s）。
5. 用 --json 輸出給腳本或 Agent 解析。

cli-readme cli-models

3. 指令群組

來源：cli-readme（⚠️ 各子指令完整旗標請以 higgsfield <cmd> --help 為準，本庫未逐一執行驗證。）

4. 實用管線例子（官方 README 原文）

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

疑難排解：「Session expired」→ 重新 higgsfield auth login；「Unknown model」→ 用 higgsfield model list 查正確 ID。cli-readme

5. Skills（給 Agent 的結構化技能）

注意：說明中心只列出 3 個 Skill（generate、soul、product-photoshoot），GitHub 倉庫實際有更多；兩者以倉庫為準但標記為「版本差異」。「CLI Skills」與「Supercomputer Skills」是不同系統。help-cli skills-repo

Skills 內的提示工程規則、常見錯誤與 Cookbook 已整理到 ../automation/。

6. Cookbook 食譜（官方 skills 倉庫 COOKBOOK.md）skills-cookbook

哪個食譜做甚麼（原文表格）：

| Goal | Recipe | Skills used |
|---|---|---|
| Launch a campaign with the founder's face | #1 Brand Campaign | `higgsfield-soul-id` → `higgsfield-product-photoshoot` → `higgsfield-generate` |
| Generate paid-social ads from a URL | #2 UGC Ad Batch | `higgsfield-generate` (Marketing Studio) |
| Async team updates without recording | #3 Founder Video | `higgsfield-soul-id` → `higgsfield-generate` |
| Turn a topic or document into a narrated explainer | #4 Narrated Explainer | `higgsfield-video-explainer` |
| Build and deploy a playable browser game | #5 Browser Game | `higgsfield-websites` (`--type game`) |

例：由產品網址批量生成 4 種 UGC 廣告（Recipe 2，原文） —— 你對 Agent 說：

Make UGC ads for my product https://shop.example.com/sneakers — try 4 different
angles: organic UGC, unboxing reveal, presenter review, and a TV-spot version.
9:16 for TikTok and Reels. 15 seconds each.

Agent 實際執行的並行生成指令（原文）：

for mode in ugc ugc_unboxing product_review tv_spot; do
     higgsfield generate create marketing_studio_video \
       --prompt "<short hook tied to the mode>" \
       --avatars @"$AVATARS_JSON" \
       --product_ids @"$PRODUCT_IDS_JSON" \
       --mode $mode \
       --duration 15 \
       --resolution 720p \
       --aspect_ratio 9:16 \
       --output-dir ./ads/$mode \
       --wait &
   done
   wait

中文解說：--mode 決定廣告類型（ugc 像手機拍的自然內容、tv_spot 像電視廣告品質，官方提醒不要無意圖地混用）；& + wait 讓 4 個任務並行；--output-dir 按模式分資料夾。官方建議先測 4 個 hook × 1 個模式，再測 1 個 hook × 4 個模式，因為 hook 對成效影響比模式大。

食譜共通模式（原文）：

1. **Train identity once, reuse forever.** Soul training is 15–45 minutes one-time. Every future video that needs the founder's face is one prompt away.
2. **Let the backend assemble the prompt for branded work.** `product-photoshoot` enhances prompts before submitting to `gpt_image_2`. Don't write `gpt_image_2` prompts by hand.
3. **Cheap-first iteration on request.** When the user wants to iterate cheaply, draft on `z_image`, then switch to the default model (`gpt_image_2_5`) once the direction is confirmed.
4. **Filenames have timestamps.** Use `yyyy-mm-dd-hh-mm-ss-name.ext` so you can trace which generation came from which session.

中文重點：① Soul 身份訓練一次（15–45 分鐘）永久重用；② 品牌圖讓 product-photoshoot 後端組裝提示，不要手寫 gpt_image_2 提示；③ 便宜先行：先用 z_image 起稿，方向確定後再換預設模型 gpt_image_2_5；④ 檔名加時間戳 yyyy-mm-dd-hh-mm-ss-name.ext 方便追溯。

7. 更新與移除

# curl
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

# brew
brew update && brew upgrade higgsfield

# npm
npm install -g @higgsfield/cli@latest

本頁來源（存取日期 2026-10-08）