higgsfield-generate

Higgsfield Generate

向任意 Higgsfield 模型提交任务。封装了 higgsfield CLI。涵盖通用图像／视频／3D／音频生成、Marketing Studio（品牌广告、虚拟形象、产品、吸睛开场、设置），以及次要功能 Virality Predictor 视频评分。

步骤 0 — 初始化

执行其他任何命令之前：

1. 如果 $PATH 中没有 higgsfield，请安装：

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

2. 如果 higgsfield account status 返回 Session expired / Not authenticated，请让用户运行 higgsfield auth login（交互式），并等待确认。

用户体验规则

1. 简洁明了。不要在聊天中显示原始 ID 或 JSON 转储。生成素材时提供媒体 URL；使用 Virality Predictor 时提供文本摘要。
2. 不使用内部术语。不要说“正在调用 higgsfield cost”或“正在轮询任务”。
3. 根据用户的首条消息判断其语言，并用该语言回复。技术参数（--aspect_ratio 16:9）保持英文。
4. 不要一次提出多个问题。选择合理的默认模型；只有确实缺少必要信息时，才一次询问一项。
5. 除非用户提出要求，否则不要预估费用，也不要优先选择更便宜的模型。优先使用默认的高质量模型。
6. 在 generate create 中传入 --wait，使命令一直等待到任务完成并直接打印结果 URL。避免采用两步式的 create → wait 模式。

发现功能的注意事项

查找 Higgsfield 功能／模型时，不要只依赖语义搜索或 CLI --help。先运行不带筛选条件的模型列表，再检查可能的 job_set_type 名称。如果用户说某个模型存在，但搜索没有结果，请相信这一线索，并先通过完整模型列表进行核实，再作答。

工作流与模型相互独立。使用 higgsfield workflow list 发现工作流，并使用 higgsfield workflow get <workflow_name> 查看参数。

Virality Predictor 的信息如下：

• 面向用户的名称：Virality Predictor
• 技术 job_set_type：brain_activity
• 类别／输出：文本报告。这是视频输入、文本输出的分析功能，不是文本／聊天生成模型。
• 输入：上传的视频
• 用途：分析成片的吸睛开场、注意力、留存率和传播力

如果用户说“分析这个视频”“给这则广告评分”“评估吸睛开场”或类似内容，请转到 brain_activity，即使它显示在文本／分析模型下也一样。应根据任务意图和所需输入分类，而不能只看输出类别。

工作流 — 通用生成

1. 选择模型。 首选以下默认模型：

   • GPT Image 2.5 → 高保真通用生成、平面设计、UI、横幅、排版和图中文字的默认图像模型。
   • Seedance 2.5（seedance_2_5）→ 高端默认视频模型，适用于需要丰富动态效果的内容、电影感片段、多镜头作品和图生视频。支持生成 4–30 秒、最高 1080p 的视频；需要原生 4K 时使用 Seedance 2.0。
   • Nano Banana 2（nano_banana_flash）→ 适用于卡通和插画风格的角色。
   • Marketing Studio → 广告、UGC、产品演示、开箱视频、电视广告、主持人视频以及品牌／产品工作流的默认选择。
   • Seed Audio 1.0 → 文本转音频、语音、音效、环境音、拟音和类似音乐的音频的默认音频模型，用户指定 Sonilo／Mirelo 时除外。

   只有用户未指定时，才会选择上述模型。其他模型仅在用户点名，或明确询问其优势（更便宜、更快或特定风格）时使用；请参阅 references/model-catalog.md。用户点名的模型在同一任务的后续操作中应继续使用。 图像：

   • 完整的品牌标识、Logo 系统、配色、字体、品牌手册、包装系统、标牌，或协调统一的品牌素材套件 → 改用 higgsfield-brandkit。
   • YouTube 缩略图、Shorts 封面或 Instagram 视频封面 → 改用 higgsfield-youtube-thumbnail。
   • 品牌产品视觉图（Pinterest Pin、生活方式图、主视觉横幅、广告套件、虚拟试穿）→ 改用 higgsfield-product-photoshoot。不要使用此技能。
   • 带有虚拟形象 + 产品的品牌广告图片（Marketing Studio 形式）→ Marketing Studio Image（见下文 Marketing Studio）
   • Soul Character（来自 higgsfield-soul-id 的参考 ID）→ 静态图使用 Soul 2.0，电影感画面使用 Soul Cinema（soul_cinematic）
   • 新创作的原创人物——UGC、编辑风、时尚、生活方式 → Soul 2.0
   • 电影感静帧 → Soul Cinema（soul_cinematic）
   • 角色设定图、根据参考照片生成单张人脸图，或编辑真实照片中的人脸 → Seedream 5.0 Pro（seedream_v5_pro）
   • 地点 / 环境 / 无人物场景 → Soul Location
   • Logo、图标、矢量风插画、品牌标志、受控配色图形 → Recraft V4.1（recraft_v4_1，通常搭配 --model_type vector）
   • 卡通或插画角色、纹理感强的照片 → Nano Banana 2（nano_banana_flash）。ID nano_banana_2 是 Nano Banana Pro 的别名，并非 Nano Banana 2
   • 其他所有情况的默认选择 → GPT Image 2.5。 平面设计、UI、横幅、字体排版、产品概念、编辑和高保真通用生成。
   • 用户要求更便宜或更快 → 参考图编辑使用 Nano Banana 2 Lite（nano_banana_2_lite），草稿使用 Z Image。

   视频：

   • 根据主题、故事或文档制作完整的配音解说视频 → 使用 higgsfield-video-explainer，而非通用视频生成。
   • 所有广告 / 商业 / 品牌广告视频 → Marketing Studio（见下文 Marketing Studio）
   • 根据草图 / 时间戳编辑现有视频，或调整画面以适配其他宽高比 → 使用工作流（draw_to_video 或 reframe），而非模型。参见 references/workflows.md。
   • 其他所有情况的默认选择 → Seedance 2.5（seedance_2_5）：多镜头、身份一致、动作丰富、图生视频、编辑、延长，时长 4–30 秒。模式 t2v / omni_reference / video_edit / video_extension；参考输入（包括首尾帧）使用 omni_reference；t2v 不接受媒体输入。最高支持 1080p。不要仅因其他模型的架构看起来更简单就降级。
   • 用户要求 4K → Seedance 2.0（seedance_2_0）；说明切换原因。
   • 用户要求更便宜或更快 → Kling 3.0 Turbo（kling3_0_turbo）、Veo 3.1 Lite 或 Seedance 1.5 Pro。
   • 用户指定模型名称 → 使用指定模型，例如 Cinema Studio 4.0（cinematic_studio_video_4_0）、Kling 3.0、Veo 3.1、Gemini Omni Flash（gemini_omni）或 Grok Video 1.5（grok_video_v15：一个 --start-image 或 --image，时长 2–15 秒；不使用参考媒体时最高支持 1080p）。

   视频分析：

   • 评估已完成视频的吸引点、爆红潜力、注意力、留存率或分心风险 → Virality Predictor（brain_activity）。这是一个视频分析模型，会返回文本评分 / 报告，而非生成的媒体素材。

   3D：

   • 可在游戏中游玩的 3D 素材，或覆盖整个游戏的素材系统 → 使用 higgsfield-websites（游戏产品类型）。
   • 根据一张或多张物体 / 产品参考图创建实际的 3D 网格 / 模型 / GLB → Multi-Image to 3D（multi_image_to_3d）。使用重复的 --image 传入 1–4 张图片；素材需要纹理时使用 --should_texture true。如果用户只要求 3D 渲染图片，请改用图像模型。 音频：
   • 音频生成的默认选择 → Seed Audio 1.0（seed_audio）。 用于文本转音频、音效、环境音、拟音、撞击声、环境音频、语音风格生成以及类似音乐的音频。需要 --prompt；只有用户提供参考素材时才使用可选的 --audio-references/--image-references。
   • 仅当用户明确要求使用 Sonilo，或需要这款专用音乐模型时，才使用 Sonilo Music（sonilo_music）。它需要 --prompt 和 --duration，并返回音频。
   • 仅当用户明确要求使用 Mirelo，或需要这款旧版 SFX 模型时，才使用 Mirelo Text to Audio（mirelo_text_to_audio）。它需要 --prompt 和 --duration，并返回音频。

   要获取传递给 higgsfield generate create 的实际 --model ID，请运行 higgsfield model list --json | jq，将显示名称映射到 ID。完整表格请参阅 references/model-catalog.md。

2. 将媒体输入直接传给标志。 媒体标志接受本地文件路径或 UUID。CLI 会自动上传路径，并自动识别 UUID 对应的是任务还是上传内容。无需预先上传。每个模型都会声明其接受的媒体角色或 *_references 参数，详见 references/media-inputs.md。

3. 快速验证。 如果不确定参数，请运行一次 higgsfield model get <jst> --json，并且只传入必需参数。回退到较旧模型前，先验证首选模型。其他情况下使用架构默认值。对于非致命的强制转换（例如 aspect_ratio=99:99 → 最接近的匹配值），服务会返回 adjustments；对于无效的已声明参数值，则会返回结构化错误。

4. 一次提交并等待完成。 higgsfield generate create <jst> [--prompt "..."] [media flags] [param flags] --wait。命令会阻塞，直到任务进入终态，并将结果打印到标准输出。可调参数：--wait-timeout 20m（默认 10m）、--wait-interval 5s（默认 3s）。Virality Predictor 不需要提示词；传入 --video 即可。

5. 交付结果。 对于生成的媒体和 3D 资产，发送主要结果 URL，并附上一行摘要（模型；视频时长；3D 内容的 GLB/资产 URL）。对于 Virality Predictor，交付评分、业务解读和 Open 报告链接。正常聊天输出中不要展示 Virality Predictor 的 .glb、.bin 或区域表内部数据。

如需检查或稍后重新运行，可使用 higgsfield generate list --json 和 higgsfield generate get <id> --json 进行回顾。如果需要重新接入未使用 --wait 启动的任务，仍可使用 higgsfield generate wait <id>。

对于工作流任务，请使用 higgsfield generate workflow <workflow_name> ... --wait。费用命令格式为 higgsfield generate cost workflow <workflow_name> ...。详见 references/workflows.md。

媒体标志

标志	用途	接受该标志的模型
--image <path-or-id>	参考图像	大多数图像模型、grok_video_v15、multi_image_to_3d、seedance_2_0、seedance_2_5、veo3、marketing_studio_video
--start-image <path-or-id>	图像转视频过渡的首帧	grok_video_v15、kling3_0、kling3_0_turbo、kling2_6、veo3_1、seedance_2_0、seedance_2_5、marketing_studio_video
--end-image <path-or-id>	过渡的末帧	kling3_0、seedance_2_0、seedance_2_5、marketing_studio_video
--video <path-or-id>	参考视频或待分析视频	seedance_2_0、seedance_2_5、brain_activity
--audio <path-or-id>	参考音频（口型同步、配乐匹配）	seedance_2_0、seedance_2_5（参考输入；与生成的输出音频不同）

对于参考数组模型，明确的标志为 --image-references、--video-references 和 --audio-references；当架构公开这些参数时，--image、--video 和 --audio 是它们的简写别名。

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

常用参数

标志会透传到模型架构。使用 higgsfield model get <jst> 进行查询。

higgsfield generate create gpt_image_2_5 --prompt "neon city at dusk" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_flash --prompt "anime character concept, expressive pose" --image ./ref.png --wait
higgsfield generate create seedance_2_5 --prompt "camera dollies in" --mode omni_reference --start-image ./first.png --duration 12 --resolution 1080p --wait
higgsfield generate create grok_video_v15 --prompt "cinematic handheld shot, neon rainy street" --start-image ./image.png --duration 5 --resolution 720p --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait
higgsfield generate create multi_image_to_3d --image ./front.png --image ./side.png --should_texture true --wait
higgsfield generate create seed_audio --prompt "cinematic rain ambience with distant thunder" --wait
higgsfield generate create sonilo_music --prompt "cinematic synthwave track" --duration 12 --wait
higgsfield generate create mirelo_text_to_audio --prompt "glass breaking in a large hall" --duration 4 --wait
higgsfield generate create brain_activity --video ./ad.mp4 --wait

对于机器可读输出（链式管道、Agent 上下文），添加 --json。使用 --wait --json 时会获得最终作业对象数组。不使用 --wait 时，会获得作业 ID。Virality Predictor 会将原始分析和渲染产物存储在作业参数中，但默认文本输出应仅包含分数和 Open report。

标准输入提示词：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 没有质量选择器；它会根据纵横比使用固定尺寸。

Soul 风格预设：text2image_soul_v2 接受 --style_id <uuid>；使用 higgsfield preset list soul-v2 列出精选风格，并传入所选 ID。--style_id 可以与 --soul-id 搭配使用，但不能与图像参考搭配使用。soul_cinema_studio 也接受 --style_id。

营销工作室

品牌图像/视频生成：头像 + 产品 + 可选的设置钩子/设置 + 广告风格模式。使用模型 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 中选择。没有自动默认值——如果未提供 --format-id，CLI 和服务器都会拒绝调用。
• 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 仅对 marketing_studio_video，将所选 ID 作为 --hook_id <hook_id> 和 --setting_id <setting_id> 传入。除非用户明确希望强化相同措辞，否则不要将开场钩子的提示词复制到 --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。开场钩子／场景仅适用于 ugc、ugc_how_to、ugc_unboxing、product_review、ugc_virtual_try_on——其他模式不要传入 --hook_id／--setting_id。请参阅 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 或 1080p。宽高比可选 auto／21:9／16:9／4:3／1:1／3:4／9:16。此处支持 --generate-audio true（默认值为 false）。--wait 会阻塞至任务完成；广告制作时间较长时，将 --wait-timeout 增至 30m。
6. 交付。 提供 URL 和一行摘要（模式、时长）。

点击即制作广告快捷方式（由 URL 驱动）

用户提供产品 URL 并希望一次性生成营销视频时：

# 1. Trigger fetch (returns the product id, import runs in the background)
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. Generate the marketing video against the same URL — backend reuses the entity
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

Virality Predictor 视频评分

当用户想要将已完成的视频作为商业创意进行评估时，请使用 Virality Predictor（brain_activity）：评估钩子强度、病毒式传播潜力、注意力、留存率，或内容／产品保持专注和减少干扰的效果。将“Virality Predictor”视为面向客户的功能名称；brain_activity 只是 CLI/job_set_type。

higgsfield generate create brain_activity --video ./creative.mp4 --wait

结果是文本，而非生成的图像／视频。报告总分、峰值钩子出现的秒数、持续得分、表现最强／最弱的片段，以及（若有）报告 URL。将其解读为用于创意测试的客观注意力指标：视觉、听觉、语言／注意力得分越高，表示刺激和专注度越强；默认模式得分越低越好，因为这表示走神更少。

CLI 会打印一个 Open report URL，例如 https://<app-domain>/apps/virality-predictor?resultJobId=<job_id>。请提供该 URL，以查看可视化报告。brain_example_url、vertexMapBinaryUrl 和 vertexMapUrl 等原始产物 URL 属于实现细节；只有用户询问原始数据或实现细节时才提及。

建议的最终回复格式：

Overall score: 44/100
Peak hook: 49% at 1s
Sustain: 89%
Strongest region: Visual Cortex
Risk: Default Mode is high, which can indicate mind-wandering.

Open report: <report_url>

错误

• Missing required params: prompt → 用户未提供提示词；请向用户索取。
• Missing required params: medias on brain_activity / Virality Predictor → 通过 --video <path-or-id> 传入且仅传入一个视频。
• 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/workflows.md — draw_to_video 和 reframe 工作流生成
• references/prompt-engineering.md — 编写有效的提示词
• references/media-inputs.md — 图像／视频／音频参考流程及 Virality Predictor 视频分析
• references/troubleshooting.md — 常见错误及解决方法
• references/marketing-avatars.md — 预设头像与自定义头像
• references/marketing-products.md — URL 抓取与手动创建产品
• references/marketing-setup-items.md — 钩子／设置项的发现与使用
• references/marketing-ad-references.md — 广告参考视频（创建／列出／获取）
• references/marketing-brand-kits.md — 品牌套件（从 URL 获取、列出、获取）
• references/marketing-dtc-ads.md — DTC Ads Engine（dtc-ads generate）
• references/marketing-modes.md — Marketing Studio 的所有模式