imraninho366/higgsfield-generate

Higgsfield Generate

向任意 Higgsfield 模型提交任务。此技能封装了 higgsfield CLI。涵盖通用图像/视频生成以及 Marketing Studio（品牌广告、头像、产品、钩子、设置）。

步骤 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 已经打印了账户信息，则跳过上述两项检查。

用户体验规则

1. 简洁明了。不要在对话中暴露原始ID或JSON数据。任务完成后，直接打印结果URL。
2. 避免内部术语。不要描述“正在调用higgsfield cost”、“正在轮询任务”。
3. 从用户的第一条消息中检测语言并用该语言回复。技术参数（如 --aspect_ratio 16:9）保持英文。
4. 不要一次性询问多个问题。选择一个合理的默认模型，仅在确实缺少信息时才逐一提问。
5. 不要预先估算成本。除非用户询问，否则直接提交任务。
6. 在 generate create 命令中传递 --wait 参数，这样命令会阻塞直到完成，并自动打印结果URL。避免使用先 create 再 wait 的两步模式。

工作流 — 通用生成

1. 选择模型。 以下是基于生产环境使用的实用默认值：

   图像：

   • 品牌产品视觉效果（Pinterest 图钉、生活方式、主视觉横幅、广告包、虚拟试穿）→ 使用 higgsfield-product-photoshoot，而不是此技能。
   • 带有头像+产品的品牌广告图像（Marketing Studio 形式）→ 图营销工作室图像（参见下方的 Marketing Studio）
   • 美观的 UGC / 时尚摄影 / 生活方式角色 → Soul 2.0
   • 电影感静帧 → Soul Cinema
   • 极具个性的创意人物（仅文本描述，特征鲜明） → Soul Cast
   • 场景 / 环境 / 无人画面 → Soul Location（同类最佳）
   • 矢量插图或面部编辑+复杂场景替换 → Seedream 4.5
   • Soul 角色（参考ID来自 higgsfield-soul-id） → 静态图用 Soul 2.0，电影感图用 Soul Cinema
   • 快速且低成本的迭代 → Z Image
   • 角色或卡通风格作品 → Nano Banana 2；复杂案例升级到 Nano Banana Pro
   • 所有其他情况的默认选项 → GPT Image 2。 平面设计、UI、横幅、排版以及高保真通用生成。

   视频：

   • 所有广告/商业/品牌广告视频 → Marketing Studio（参见下方的 Marketing Studio）
   • 默认所有用途的严肃视频（多镜头、一致的ID、运动量大）→ 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 是任务ID还是上传ID。无需预先上传。每个模型声明其接受的媒体角色（image, start_image, end_image, video, audio）——请参阅 references/media-inputs.md。

3. 快速验证参数。 如果不确定参数，请运行 higgsfield model get <jst> --json 查看一次，只传递必需的参数。对于其他参数，使用模式默认值。服务器会返回 adjustments 用于非致命的参数修正（例如 aspect_ratio=99:99 → 最接近的值），并为无效的声明参数值返回结构化错误。

4. 一步提交并等待。 higgsfield generate create <jst> --prompt "..." [media flags] [param flags] --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 <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
--audio <path-or-id>	参考音频（唇形同步、配乐匹配）	seedance_2_0（使用此标志，而非 --generate-audio）

每个标志接受本地文件路径（自动上传）或 UUID（来自 higgsfield upload create 的上传ID，或先前的任务ID）。每个模型通过 MEDIA_ROLES 声明自己的角色集。完整表格请参阅 references/media-inputs.md。

常用参数

标志会透传到模型模式。请使用 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 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

对于机器可读输出（链式管道、智能体上下文），添加 --json。使用 --wait --json 可以获取最终的任务对象数组。不使用 --wait 则获取任务ID。

标准输入提示词：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。

概念

• 头像（Avatar） — 主持人面部。可以是精选的 preset（通过 higgsfield marketing-studio avatars list 浏览）或 custom（通过 higgsfield marketing-studio avatars create 上传的照片）。对于UGC模式，如果简报明确提到了人物，头像为可选项；后端可以自动创建一个Soul角色。当用户想要一个特定的主持人时，请传递头像。
• 产品（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。

用户体验规则（附加）

• 每个阶段只问一个问题。不要一次性询问产品+头像+模式。

工作流 — 快速广告视频

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角色。
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；不代表存在 --hook_id 就必须指定 --mode。其他当前可用的模式 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 + 一行摘要（模式、时长）。

Click-to-Ad 快捷方式（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 → 模式不接受此标志；请检查 higgsfield model get <jst>。如果 hook_id 或 setting_id 出现此错误，则表示所选模型/job_set_type 不支持 Marketing Studio 的设置项目。
• 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 — 预设头像与自定义头像
• references/marketing-products.md — URL获取与手动创建产品
• references/marketing-setup-items.md — 钩子/设置的发现与使用
• references/marketing-modes.md — 所有 Marketing Studio 模式