imraninho366/higgsfield-generate

Higgsfield Generate

提交任務至任何 Higgsfield 模型。包裝了 higgsfield CLI。涵蓋一般圖片/影片生成與行銷工作室（品牌廣告、頭像、產品、鉤子、設定）。

步驟 0 — 初始化

在任何其他指令之前，請先確認 CLI 已安裝並通過驗證：

1. 如果 higgsfield 不在 $PATH 中，請安裝它：

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

2. 如果 higgsfield account status 失敗並顯示 Session expired / Not authenticated，請要求使用者執行 higgsfield auth login（互動式，會開啟瀏覽器），並等待使用者確認後再繼續。

如果 higgsfield account status 已能成功顯示帳號資訊，則跳過上述兩個檢查。

UX 規則

1. 保持簡潔。不要在對話中顯示原始 ID 或 JSON 資料。準備好時僅輸出結果 URL。
2. 避免內部術語。不要描述「呼叫 higgsfield cost」、「輪詢 job」。
3. 從使用者的第一則訊息偵測語言，並以該語言回覆。技術參數（如 --aspect_ratio 16:9）保持英文。
4. 不要一次問太多問題。選一個合理的預設模型，只有在真正缺少資訊時才一次問一件事。
5. 不要預估費用。除非使用者詢問，否則直接提交。
6. 在 generate create 時加上 --wait，讓指令阻塞直到完成，並自行印出結果 URL。避免使用 create → wait 的兩步驟模式。

工作流程 — 一般生成

1. 選擇模型。 根據實際使用經驗的實用預設值：

   圖片：

   • 品牌產品視覺（Pinterest 圖釘、生活風格、首頁橫幅、廣告組合、虛擬試穿）→ 使用 higgsfield-product-photoshoot，不是本技能。
   • 帶有頭像 + 產品的品牌廣告圖片（行銷工作室格式）→ 行銷工作室圖片（請見下方行銷工作室章節）
   • 美學 UGC / 時尚編輯 / 生活風格角色 → Soul 2.0
   • 電影風格靜態畫面 → Soul Cinema
   • 極具特色的創作角色（純文字，獨特風格）→ Soul Cast
   • 場景 / 環境 / 無人物畫面 → Soul Location（同類最佳）
   • 向量插圖 或 臉部編輯 + 複雜場景替換 → Seedream 4.5
   • Soul 角色（有 higgsfield-soul-id 的參考 ID）→ 靜態圖用 Soul 2.0，電影風格用 Soul Cinema
   • 快速且便宜的迭代 → Z Image
   • 角色或卡通風格作品 → Nano Banana 2；困難案例則升級至 Nano Banana Pro
   • 其他情況的預設值 → GPT Image 2。 圖形設計、UI、橫幅、排版與高品質一般生成。

   影片：

   • 所有廣告 / 商業 / 品牌廣告影片 → 行銷工作室（請見下方行銷工作室章節）
   • 所有用途的預設嚴肅影片（多鏡頭、一致性身份、大量動作）→ Seedance 2.0。 最新技術。
   • 單一平面場景、無強烈動態、比 Seedance 2.0 便宜 → Kling 3.0
   • 無剪輯的便宜乾淨鏡頭 → Seedance 1.5 Pro
   • 電影級最高品質 → Cinema Studio Video 3.0
   • 便宜且物理效果強烈，不需音訊 → Minimax Hailuo
   • 快速批次 / 大量產出 → Veo 3.1 Lite

   如何取得傳給 higgsfield generate create 的實際 --model ID：執行 higgsfield model list --json | jq 以將顯示名稱對應到 ID。完整對照表請見 references/model-catalog.md。

2. 將媒體輸入直接傳給旗標。 媒體旗標接受本機檔案路徑或UUID。CLI 會自動上傳路徑，並對 UUID 自動偵測是 job ID 還是上傳 ID。無需預先上傳。每個模型會宣告其接受的角色（image、start_image、end_image、video、audio）— 請見 references/media-inputs.md。

3. 快速驗證。 如果不確定參數，先執行一次 higgsfield model get <jst> --json 並只傳入需要的參數。其他部分使用 schema 預設值。伺服器會針對非致命強制轉換（例如 aspect_ratio=99:99 → 最接近的匹配）回傳 adjustments，並對無效的宣告參數值回傳結構化錯誤。

4. 一次性提交並等待。 higgsfield generate create <jst> --prompt "..." [媒體旗標] [參數旗標] --wait。會阻塞直到最終狀態，並在 stdout 印出結果 URL。可調整參數：--wait-timeout 20m（預設 10m）、--wait-interval 5s（預設 3s）。

5. 交付結果。 傳送 URL 加上一行摘要（模型名稱、若為影片則加上長度）。

如需後續檢查或重新執行，可使用 higgsfield generate list --json 和 higgsfield generate get <id> --json 進行回顧。如果需要在未使用 --wait 啟動的任務中重新加入，仍可使用 higgsfield generate wait <id>。

媒體旗標

旗標	用途	接受此旗標的模型
--image <路徑或ID>	參考圖片	大部分圖片模型、seedance_2_0、veo3、marketing_studio_video
--start-image <路徑或ID>	圖片轉影片轉場的第一幀	kling3_0、kling2_6、veo3_1、seedance_2_0、marketing_studio_video
--end-image <路徑或ID>	轉場的最後一幀	kling3_0、seedance_2_0、marketing_studio_video
--video <路徑或ID>	參考影片	seedance_2_0
--audio <路徑或ID>	參考音訊（唇形同步、配樂匹配）	seedance_2_0（使用此旗標，不要用 --generate-audio）

每個旗標接受本機檔案路徑（自動上傳）或 UUID（來自 higgsfield upload create 的上傳 ID，或先前的 job ID）。每個模型透過 MEDIA_ROLES 宣告自己的角色集。完整對照表請見 references/media-inputs.md。

常用參數

旗標會傳遞至模型 schema。請使用 higgsfield model get <jst> 來探索可用的參數。

higgsfield generate create gpt_image_2 --prompt "黃昏的霓虹城市" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "動漫角色概念，富有表現力的姿勢" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "鏡頭向前推進" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

如需機器可讀的輸出（用於串聯工作流程、agent 上下文），請加上 --json。使用 --wait --json 會得到最終的 job 物件陣列。不使用 --wait 則會得到 job ID 清單。

從 stdin 輸入提示：echo "..." | higgsfield generate create z_image --wait。

Soul 圖片品質：對於 text2image_soul_v2 和 soul_cinematic，請傳入 --quality 1.5k 或 --quality 2k。這些是 UI 面的層級；後端會將它們對應到 720p/1080p 以及從選取的 --aspect_ratio 決定的模型特定尺寸。soul_location 沒有品質選擇器；它對每個長寬比使用固定的尺寸。

行銷工作室

品牌圖片/影片生成：頭像 + 產品 + 可選的設定鉤子/場景 + 廣告風格模式。使用模型 marketing_studio_video 和 marketing_studio_image。

概念

• 頭像 (Avatar) — 主持人的臉。可以是策展的 preset（瀏覽 higgsfield marketing-studio avatars list）或 custom（透過 higgsfield marketing-studio avatars create 上傳照片）。對於 UGC 模式，如果簡短敘述明確提到一個人，頭像是可選的；後端可以自動建立一個 Soul Character。當使用者想要特定主持人時，請傳入頭像。
• 產品 (Product) — 品牌商品，包含標題與參考圖片。可從 URL 匯入（higgsfield marketing-studio products fetch --url ...）或從上傳的圖片建立（higgsfield marketing-studio products create）。
• 網路產品 (Webproduct) — App Store / 網頁版本。在抓取 App Store URL 時會自動路由。
• 鉤子 (Hook) — 可重複使用的開場角度 / 廣告鉤子。使用 higgsfield marketing-studio hooks list 瀏覽。鉤子文字會加在使用者的提示之前；它不會取代 --prompt。
• 設定 (Setting) — 可重複使用的環境 / 場景上下文。使用 higgsfield marketing-studio settings list 瀏覽。

探索指令

當使用者詢問有哪些現有資源時，請使用以下精確的清單指令：

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json

--hook_id 和 --setting_id 僅 marketing_studio_video 支援；請勿將它們傳給 marketing_studio_image。

UX 規則（額外）

• 每個階段只問一個問題。不要一次就問產品+頭像+模式。

工作流程 — 快速廣告影片

1. 取得產品。
   • 現有產品 → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait（輪詢直到匯入完成）
   • 本機圖片 → higgsfield upload create <照片>... 然後 higgsfield marketing-studio products create --title "..." --image <id>... 取得產品 ID。使用 --hook_id 時，強烈建議傳入 --product_ids；鉤子的設計是為了圍繞產品展開，如果沒有產品上下文效果會很差。
2. 如果需要，選取頭像。
   • 預設：higgsfield marketing-studio avatars list 並選取符合品牌調性的策展頭像。
   • 自訂：higgsfield marketing-studio avatars create --name "..." --image <上傳ID>。 對於 UGC 模式，如果不需要特定主持人，且簡短敘述提到一個人，你可以省略 --avatars；後端可以合成一個 Soul Character。
3. 可選：選取設定項目。
   • 鉤子：higgsfield marketing-studio hooks list --json
   • 設定：higgsfield marketing-studio settings list --json 僅對 marketing_studio_video 將選取的 ID 作為 --hook_id <hook_id> 和 --setting_id <setting_id> 傳入。除非使用者明確想要強化相同的措辭，否則不要將鉤子的提示複製到 --prompt。
4. 如果需要，選取模式。 預設為 ugc；--mode 不會因為有 --hook_id 就變成必填。其他可用的 slug：ugc_how_to、ugc_unboxing、product_showcase、product_review、tv_spot、wild_card、ugc_virtual_try_on、virtual_try_on。請見 references/marketing-modes.md。
5. 生成（一次性）。

   PRODUCT_IDS_JSON=$(mktemp)
   AVATARS_JSON=$(mktemp)
   printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
   printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"
   
   higgsfield generate create marketing_studio_video \
     --prompt "..." \
     --avatars @"$AVATARS_JSON" \
     --product_ids @"$PRODUCT_IDS_JSON" \
     --mode ugc \
     --duration 15 \
     --resolution 720p \
     --aspect_ratio 9:16 \
     --wait
   

   如果選取了設定鉤子/場景，請加上 --hook_id <hook_id> 和/或 --setting_id <setting_id>。 product_ids 和 avatars 是 JSON 陣列；請透過 @/path/to/file.json 傳入。請勿將純 UUID 傳給 --product_ids。 解析度為 480p 或 720p。長寬比為 auto/21:9/16:9/4:3/1:1/3:4/9:16 之一。此處支援 --generate-audio true（不同於 seedance_2_0）。--wait 會阻塞直到完成；對於較長的廣告執行，請將 --wait-timeout 30m 調高。
6. 交付結果。 URL + 一行摘要（模式、長度）。

一鍵廣告捷徑（URL 驅動）

當使用者提供產品 URL 並希望一次完成行銷影片時：

# 1. 觸發擷取（回傳產品 ID 並開始背景抓取）
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. 針對相同 URL 生成行銷影片 — 後端會重複使用該實體
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

後端會根據 URL 進行去重，因此重複執行時會重複使用現有實體，而非重新抓取。

工作流程 — 行銷圖片

與上述相同，但使用 marketing_studio_image 模型：

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

錯誤處理

• Missing required params: prompt → 使用者沒有提供提示；請要求提供。
• Invalid values: aspect_ratio=99:99 (allowed: ...) → 錯誤的列舉值；請從允許的值中選取。
• Unknown params: foo → schema 不接受該旗標；請檢查 higgsfield model get <jst>。如果對 hook_id 或 setting_id 發生此錯誤，表示選取的模型/job_set_type 不支援行銷工作室的設定項目。
• Session expired → 請執行 higgsfield auth login。

更多資訊請見 references/troubleshooting.md。

參考文件

按需載入：

• references/model-catalog.md — 為任務選擇正確的模型
• references/prompt-engineering.md — 撰寫有效的提示
• references/media-inputs.md — 圖片/影片參考流程
• references/troubleshooting.md — 常見錯誤與解決方法
• references/marketing-avatars.md — 策展頭像 vs 自訂頭像
• references/marketing-products.md — URL 擷取 vs 手動產品建立
• references/marketing-setup-items.md — 鉤子/設定的探索與使用
• references/marketing-modes.md — 所有行銷工作室模式