adamroy13/ai-influencer-promo-machine

Higgsfield 生成

向任何 Higgsfield 模型提交任務。封裝了 higgsfield CLI。涵蓋通用圖片/影片生成、Marketing Studio（品牌廣告、頭像、產品、鉤子、設定），以及次要的 Virality Predictor 影片評分。

步驟 0 — 初始化

在任何其他命令之前：

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（互動式）並等待確認。

UX 規則

1. 保持簡潔。不要在聊天中顯示原始 ID 或 JSON 傾印。對於生成的資產，輸出媒體 URL；對於 Virality Predictor，輸出文字摘要。
2. 避免內部術語。不要敘述「呼叫 higgsfield 成本」、「輪詢任務」。
3. 從第一則訊息偵測使用者的語言，並以此語言回覆。技術參數（--aspect_ratio 16:9）保持英文。
4. 不要一次問太多問題。選擇一個合理的預設模型，只有在真正缺少資訊時才一次問一件事。
5. 除非使用者要求，否則不要預估成本或為了更便宜的模型進行最佳化。優先使用品質預設。
6. 傳遞 --wait 給 generate create，讓命令阻塞直到完成，並直接輸出結果 URL。避免使用兩步驟的 create → wait 模式。

探索防護

在尋找 Higgsfield 功能/模型時，不要僅依賴語意搜尋或 CLI --help。首先執行未過濾的模型列表，然後檢查可能的 job_set_type 名稱。如果使用者說某個模型存在但搜尋沒有結果，請信任該訊號，並在回答前使用完整模型列表進行驗證。

Virality Predictor 暴露為：

• 客戶面對名稱：Virality Predictor
• 技術 job_set_type：brain_activity
• 類別/輸出：文字報告。這是影片輸入/文字輸出的分析，不是文字/聊天生成模型。
• 輸入：上傳的影片
• 用途：成品影片的鉤子、注意力、留存率及發燒度分析

如果使用者說「分析這段影片」、「為這個廣告評分」、「評估這個鉤子」或類似內容，即使它出現在文字/分析模型下，也應路由到 brain_activity。根據任務意圖和所需輸入進行分類，而不是僅根據輸出類別。

工作流程 — 通用生成

1. 選擇模型。 從核心預設開始，除非簡報明確需要專業模型：

   • GPT Image 2 → 高傳真度通用生成的預設圖片模型，適用於圖形設計、UI、橫幅、排版和圖片上文字。
   • Seedance 2.0 → 嚴肅動作、電影級片段、多鏡頭工作、圖片轉影片以及 4–15 秒製作品質輸出的預設影片模型。12 秒是有效的。
   • Nano Banana 2/Pro → 角色、卡通、風格化和參考驅動的圖片工作的預設模型；對於更困難的簡報，使用 Pro。
   • Marketing Studio → 廣告、UGC、產品展示、開箱、電視廣告、主持人影片以及品牌/產品工作流程的預設模型。

   圖片：

   • 品牌產品視覺（Pinterest 圖釘、生活風格、主視覺橫幅、廣告包、虛擬試穿）→ 改用 higgsfield-product-photoshoot。不屬於此技能。
   • 生成的產品概念 / 包裝 / 罐子 / 瓶子，帶有品牌名稱或標籤文字 → GPT Image 2。
   • 帶有頭像 + 產品的品牌廣告圖片（Marketing Studio 形式）→ Marketing Studio Image（請參閱下方的 Marketing Studio）
   • 美學 UGC / 時尚編輯 / 生活風格角色 → Soul 2.0
   • 電影級靜止畫面 → Soul Cinema
   • 高度角色化的創意人物（僅文字，獨特）→ Soul Cast
   • 場景 / 環境 / 無人物場景 → Soul Location（同類最佳）
   • 向量插圖 OR 臉部編輯 + 複雜場景交換 → Seedream 4.5
   • Soul Character（來自 higgsfield-soul-id 的參考 ID）→ 靜止圖使用 Soul 2.0，電影級使用 Soul Cinema
   • 角色或卡通風格工作 → Nano Banana 2；困難情況升級到 Nano Banana Pro
   • 快速且便宜的迭代 → Z Image
   • 其他所有情況的預設 → GPT Image 2。 圖形設計、UI、橫幅、排版和高傳真度通用生成。

   影片：

   • 所有廣告 / 商業 / 品牌廣告影片 → Marketing Studio（請參閱下方的 Marketing Studio）
   • 所有用途的預設嚴肅影片（多鏡頭、一致的身份、大量動作、圖片轉影片、4–15 秒請求）→ Seedance 2.0。 業界最先進。不要僅僅因為 Seedance 1.5 的持續時間列舉更容易閱讀而降級到它；請先驗證 Seedance 2.0。
   • 單一平面場景，沒有強烈的動態，比 Seedance 2.0 便宜 → Kling 3.0
   • 便宜的乾淨鏡頭，無剪輯，僅在使用者要求更便宜/預算輸出時使用 → Seedance 1.5 Pro
   • 電影級最高傳真度 → Cinema Studio Video 3.0
   • 便宜且具有強烈物理效果，不需要音訊 → Minimax Hailuo
   • 快速批次 / 大量 → Veo 3.1 Lite

   影片分析：

   • 評估成品影片的鉤子、發燒潛力、注意力、留存率或干擾風險 → Virality Predictor (brain_activity)。這是一個影片分析模型，返回文字評分/報告，而不是生成的媒體資產。

   要獲取要傳遞給 higgsfield generate create 的實際 --model ID，請執行 higgsfield model list --json | jq 將顯示名稱映射到 ID。請參閱 references/model-catalog.md 以取得完整表格。

2. 直接將媒體輸入傳遞給旗標。 媒體旗標接受本地檔案路徑 或 UUID。CLI 會自動上傳路徑，並為 UUID 自動偵測任務與上傳。無需預先上傳。每個模型都會宣告接受的角色（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 "..."] [media flags] [param flags] --wait。阻塞直到終端狀態，並在 stdout 上輸出結果。可調整項：--wait-timeout 20m（預設 10m）、--wait-interval 5s（預設 3s）。Virality Predictor 不需要提示；傳遞 --video。

5. 傳遞結果。 對於生成的媒體，發送 URL 加上一行摘要（模型、如果是影片則加上持續時間）。對於 Virality Predictor，傳遞分數、業務解讀以及 Open 報告連結。不要在常規聊天輸出中顯示 .glb、.bin 或區域表內部資訊。

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

媒體旗標

旗標	用途	接受它的模型
--image <path-or-id>	參考圖片	大多數圖片模型、seedance_2_0、veo3、marketing_studio_video
--start-image <path-or-id>	圖片轉影片過渡的第一幀	kling3_0、kling2_6、veo3_1、seedance_2_0、marketing_studio_video
--end-image <path-or-id>	過渡的最後一幀	kling3_0、seedance_2_0、marketing_studio_video
--video <path-or-id>	參考或分析的影片	seedance_2_0、brain_activity
--audio <path-or-id>	參考音訊（唇形同步、配樂匹配）	seedance_2_0（使用此項，而不是 --generate-audio）

每個旗標接受本地檔案路徑（自動上傳）或 UUID（來自 higgsfield upload create 的上傳 ID，或先前的任務 ID）。每個模型透過 MEDIA_ROLES 宣告自己的角色集。請參閱 references/media-inputs.md 以取得完整表格。

常用參數

旗標傳遞給模型 schema。使用 higgsfield model get <jst> 來發現。

higgsfield generate create gpt_image_2 --prompt "neon city at dusk" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "anime character concept, expressive pose" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "camera dollies in" --start-image ./first.png --duration 12 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait
higgsfield generate create brain_activity --video ./ad.mp4 --wait

對於機器可讀的輸出（鏈接管道、代理上下文），請添加 --json。使用 --wait --json 時，您會得到最終的任務物件陣列。沒有 --wait 時，您會得到任務 ID。Virality Predictor 將原始分析和渲染工件儲存在任務參數中，但預設文字輸出應保留為分數加上 Open 報告。

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

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

概念

• 頭像 — 主持人面孔。精選的 preset（瀏覽 higgsfield marketing-studio avatars list）或 custom（透過 higgsfield marketing-studio avatars create 上傳的照片）。對於 UGC 模式，如果簡報明確提到一個人，頭像為可選；後端可以自動建立一個 Soul Character。當使用者想要特定的主持人時，傳遞頭像。
• 產品 — 帶有標題和參考圖片的品牌商品。從 URL 匯入（higgsfield marketing-studio products fetch --url ...）或從上傳的圖片建立（higgsfield marketing-studio products create）。
• Webproduct — App Store / 網頁版本。在擷取 App Store URL 時自動路由。
• 鉤子 — 可重複使用的開場角度 / 廣告鉤子。使用 higgsfield marketing-studio hooks list 瀏覽。鉤子文字會預先掛在使用者的提示前面；它不會取代 --prompt。
• 設定 — 可重複使用的環境 / 場景脈絡。使用 higgsfield marketing-studio settings list 瀏覽。
• 廣告參考 — 可重複使用的靈感影片，可以綁定到頭像和/或產品。從上傳的影片（--video-input <upload_id>）或先前的生成任務（--job <job_id>）建立。使用 higgsfield marketing-studio ad-references list 瀏覽。請參閱 references/marketing-ad-references.md。
• 品牌套件 — 擷取品牌的識別（名稱、標誌、主視覺圖片、顏色、字體、語氣），以便在圖片生成中重複使用。透過提交網站 URL 來建立（higgsfield marketing-studio brand-kits fetch --url https://… --wait）。請參閱 references/marketing-brand-kits.md。
• 廣告格式 — 驅動生成圖片視覺結構的預設（headline、bullet-points 等）。唯讀，使用 higgsfield marketing-studio ad-formats list 瀏覽。dtc-ads generate 的必填輸入。

探索命令

當使用者詢問已存在的內容時，使用這些確切的列表命令：

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json
higgsfield marketing-studio ad-references list --json
higgsfield marketing-studio brand-kits list --json
higgsfield marketing-studio ad-formats list --json

--hook_id 和 --setting_id 僅由 marketing_studio_video 支援；不要將它們傳遞給 marketing_studio_image。

UX 規則（額外）

• 每個階段只問一個問題。不要一次詢問產品+頭像+模式。
• 兩種廣告方法互斥。 使用者提供廣告參考影片（參考驅動）或選擇鉤子/設定區塊（從區塊組成）— 永遠不會兩者並存。如果使用者已選擇廣告參考，請不要提供鉤子/設定；如果已選擇鉤子/設定，請不要提議附加廣告參考。
• 廣告參考來源。 唯一有效的輸入是本地影片檔案（透過 higgsfield upload create ... --video 上傳）或先前的影片任務。如果使用者提供其他任何內容，請要求提供本地檔案。
• dtc-ads 廣告格式是強制性的。 始終要求使用者從 ad-formats list 中選擇。沒有自動預設 — CLI 和伺服器都會拒絕沒有 --format-id 的呼叫。
• dtc-ads 可選輸入。 當簡報需要時，建議頭像、產品和參考媒體；僅附加使用者選擇的內容。

工作流程 — 快速廣告影片

1. 取得產品。
   • 現有產品 → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait（輪詢直到匯入完成）
   • 本地圖片 → higgsfield upload create <photo>... 然後 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 <upload_id>。 對於 UGC 模式，當不需要特定主持人且簡報提到一個人時，可以省略 --avatars；後端可以合成一個 Soul Character。
3. 可選地選擇設置項目。
   • 鉤子：higgsfield marketing-studio hooks list --json
   • 設定：higgsfield marketing-studio settings list --json 將所選 ID 作為 --hook_id <hook_id> 和 --setting_id <setting_id> 傳遞，僅適用於 marketing_studio_video。不要將鉤子的提示複製到 --prompt 中，除非使用者明確想要強化相同的措辭。
4. 如果需要，選擇模式。 預設是 ugc；--mode 不會僅僅因為存在 --hook_id 就需要。其他目前的模式包括 review、tutorial、unboxing、compare、vlog、social_media_clip、crowdfunding、presentation、tv_ad、on_demand。--mode 不會改變可用參數集。
5. 如果是 product_promo_reel（原生廣告模式），則無需鉤子或模式。 此模式僅使用產品和頭像（可選），並自動協調多機位視角。
6. 生成！ higgsfield generate create marketing_studio_video --product_ids <id> [--avatar_ids <id>] [--hook_id <id>] [--setting_id <id>] [--ad_reference_id <id>] [--mode <mode>] [--prompt "..."] --wait。對於相容於 dtc-ads 的輸入（目前為 marketing_studio_image），添加 --format-id <id>。

支援的 job_set_type 值

這份清單方便參考。使用 higgsfield model list 取得目前的清單。

• gpt_image_2
• seedance_2_0
• seedance_1_5_pro
• kling3_0
• kling2_6
• nano_banana_2
• nano_banana_pro
• soul_v2 / text2image_soul_v2
• soul_cinematic / soul_cinema
• soul_cast
• soul_location
• z_image / zero_image
• minimax_hailuo
• veo3_1_lite
• veo3
• cinema_studio_video_3_0
• marketing_studio_image (alias dtc_ads_image)
• marketing_studio_video
• brain_activity
• seedream_4_5 / seedream_4_5_image

參數與變數參考

• higgsfield product-photoshoot：一個獨立的 higgsfield 子命令，不屬於此技能。請參考其自己的 SKILL.md。
• higgsfield-soul-id：一個支援技能，用於建立和管理 Soul Characters。與此技能鏈接，透過 text2image_soul_v2 或 soul_cinematic 的 --soul-id 標誌實現面部/身份一致性。請參閱其 SKILL.md。
• start_image 與 image：某些影片模型可以將 --start-image 和一個通用的 --image（場景參考）作為不同的輸入。使用 higgsfield model get <jst> --json 檢查實際 schema 以瞭解特定的角色要求。對於相容的模型，動畫 / 圖片轉影片工作通常僅使用 --start-image 和/或 --end-image（無 --video）。
• references/media-inputs.md — 每個模型接受的媒體角色的完整表格。
• references/model-catalog.md — 完整的模型清單，包括顯示名稱、描述和參數。
• references/marketing-ad-references.md — 廣告參考功能的完整文件，包括建立、綁定、帶有 --hook_id 的參考以及提示覆蓋。
• references/marketing-brand-kits.md — 品牌套件的完整文件。