Higgsfield 生成器
向任何 Higgsfield 模型提交任务。包装了 higgsfield CLI。涵盖通用图像/视频生成、Marketing Studio(品牌广告、头像、产品、钩子、设置)以及辅助性的病毒式传播预测器视频评分。
第 0 步 — 引导
在任何其他命令之前:
- 如果
higgsfield不在$PATH中,请安装它:curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh - 如果
higgsfield account status失败并显示Session expired/Not authenticated,请让用户运行higgsfield auth login(交互式)并等待确认。
用户体验规则
- 简洁明了。不要在聊天中显示原始 ID 或 JSON 转储。打印生成资产的媒体 URL,或病毒式传播预测器的文本摘要。
- 不要使用内部行话。不要描述“正在调用 higgsfield 费用”、“正在轮询任务”。
- 从第一条消息检测用户的语言,并用该语言回复。技术参数(
--aspect_ratio 16:9)保持英文。 - 不要批量提问。选择一个合理的默认模型,并且仅当确实缺少信息时才一次询问一件事。
- 除非用户要求,否则不要预先估算成本或优化以使用更便宜的模型。首选高质量默认值。
- 为
generate create传递--wait参数,以便命令阻塞直到完成并自己打印结果 URL。避免使用两步的create→wait模式。
发现护栏
在寻找某个 Higgsfield 功能/模型时,不要仅依赖语义搜索或 CLI --help。首先运行未过滤的模型列表,然后检查可能的 job_set_type 名称。如果用户说某个模型存在但搜索没有结果,相信该信号并在回答之前使用完整的模型列表进行验证。
病毒式传播预测器表现为:
- 面向客户的名称:病毒式传播预测器
- 技术
job_set_type:brain_activity - 类别/输出:文本报告。这是视频输入/文本输出分析,不是文本/聊天生成模型。
- 输入:上传的视频
- 目的:已完成视频的钩子、注意力、留存率和病毒式传播分析
如果用户说“分析这个视频”、“评价这个广告”、“评估钩子”或类似内容,即使它出现在文本/分析模型下,也要路由到 brain_activity。根据任务意图和所需输入进行分类,而不是仅根据输出类别。
工作流程 — 通用生成
-
选择模型。 从核心默认值开始,除非简要说明明确需要特定模型:
- GPT Image 2 → 用于高保真通用生成、图形设计、用户界面、横幅、排版和图像内文字的默认图像模型。
- Seedance 2.0 → 用于严肃动作、电影片段、多镜头工作、图像到视频以及 4–15 秒制作质量输出的默认视频模型。12 秒是有效的。
- Nano Banana 2/Pro → 用于角色、卡通、风格化和参考驱动图像工作的默认模型;对于困难任务使用 Pro。
- Marketing Studio → 用于广告、用户生成内容、产品演示、开箱视频、电视广告、演示者视频以及品牌/产品工作流的默认模型。
图像:
- 品牌产品视觉效果(Pinterest 图钉、生活方式、英雄横幅、广告包、虚拟试穿)→ 使用
higgsfield-product-photoshoot替代。不要使用此技能。 - 生成的产品概念/包装/罐子/瓶子,带有品牌名称或标签文字 → GPT Image 2。
- 带有人物头像 + 产品的品牌广告图像(Marketing Studio 格式)→ Marketing Studio 图像(请参见下文 Marketing Studio)
- 审美类 UGC / 时尚社论 / 生活方式角色 → Soul 2.0
- 电影风格静态帧 → Soul Cinema
- 高度个性化的创意角色(仅文字,独特)→ Soul Cast
- 地点/环境/无人物场景 → Soul Location(同类最佳)
- 矢量插图或面部编辑 + 复杂场景替换 → Seedream 4.5
- 灵魂角色(来自
higgsfield-soul-id的参考 ID)→ 静态图用 Soul 2.0,电影风格用 Soul Cinema - 角色或卡通风格工作 → Nano Banana 2;困难情况升级到 Nano Banana Pro
- 快速且廉价的迭代 → Z Image
- 其他所有情况的默认值 → GPT Image 2。 图形设计、用户界面、横幅、排版和高保真通用生成。
视频:
- 所有广告/商业/品牌视频 → Marketing Studio(请参见下文 Marketing Studio)
- 所有用途的默认严肃视频(多镜头、一致身份、动作丰富、图像到视频、4–15 秒请求)→ Seedance 2.0。 SOTA。不要仅仅因为 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
视频分析:
- 评价已完成视频的钩子、病毒式传播潜力、注意力、留存率或干扰风险 → 病毒式传播预测器(
brain_activity)。这是一个视频分析模型,返回文本分数/报告,而不是生成的媒体资产。
要获取传递给
higgsfield generate create的实际--modelID,请运行higgsfield model list --json | jq将显示名称映射到 ID。请参见references/model-catalog.md获取完整表格。 -
将媒体输入直接传递给标志。 媒体标志接受本地文件路径 或 UUID。CLI 会自动上传路径,并且对于 UUID 会自动检测是任务 ID 还是上传 ID。无需预上传。每个模型声明接受的角色(
image、start_image、end_image、video、audio)— 请参见references/media-inputs.md。 -
快速验证。 如果不确定参数,运行
higgsfield model get <jst> --json一次,只传递需要的参数。在回退到旧版本之前,先验证首选模型。对于其他参数使用模式默认值。服务器会为不致命的强制转换(例如aspect_ratio=99:99→ 最接近的匹配)返回adjustments,并为无效的声明参数值返回结构化错误。 -
一次性提交并等待。
higgsfield generate create <jst> [--prompt "..."] [media flags] [param flags] --wait。阻塞直到终端状态并在标准输出打印结果。可调参数:--wait-timeout 20m(默认 10m),--wait-interval 5s(默认 3s)。病毒式传播预测器不需要提示;传递--video。 -
交付。 对于生成的媒体,发送 URL 加上一行摘要(模型、视频时长)。对于病毒式传播预测器,交付分数、业务解释以及 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 获取完整表格。
通用参数
标志会传递到模型模式。使用 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 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。病毒式传播预测器将原始分析和渲染工件存储在任务参数中,但默认文本输出应保留分数和 Open 报告链接。
标准输入提示:echo "..." | higgsfield generate create z_image --wait。
灵魂图像质量:对于 text2image_soul_v2 和 soul_cinematic,传递 --quality 1.5k 或 --quality 2k。这些是面向用户的层级;后端将它们映射到 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 模式,如果简要明确提到一个人,头像是可选的;后端可以自动创建一个灵魂角色。当用户想要特定的演示者时,传递一个头像。 - 产品 — 带有标题和参考图像的品牌商品。从 URL 导入(
higgsfield marketing-studio products fetch --url ...)或从上传的图像创建(higgsfield marketing-studio products create)。 - Web 产品 — 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
仅 marketing_studio_video 支持 --hook_id 和 --setting_id;不要将它们传递给 marketing_studio_image。
用户体验规则(附加)
- 每个阶段只问一个问题。不要预先询问产品+头像+模式。
- 两种广告方法是互斥的。 要么用户提供广告参考视频(参考驱动)要么选择钩子/设置块(从块组合)— 绝不能同时使用两者。如果用户已选择广告参考,则不要提供钩子/设置;如果已选择钩子/设置,则不要提供附加广告参考的选项。
- 广告参考来源。 唯一有效的输入是本地视频文件(通过
higgsfield upload create ... --video上传)或先前的视频任务。如果用户提供其他任何内容,请要求提供本地文件。 dtc-ads广告格式是必需的。 始终要求用户从ad-formats list中选择。没有自动默认值 — CLI 和服务器都会拒绝没有--format-id的调用。dtc-ads可选输入。 当简要要求时,建议使用头像、产品和参考媒体;仅附加用户选择的内容。
工作流程 — 快速广告视频
- 获取产品。
- 已有产品 →
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;钩子旨在针对产品进行转向,如果没有产品上下文则效果不佳。
- 已有产品 →
- 如果需要,选择头像。
- 默认:
higgsfield marketing-studio avatars list并选择与品牌声音匹配的预设。 - 自定义:
higgsfield marketing-studio avatars create --name "..." --image <upload_id>。 对于 UGC 模式,当不需要特定演示者且简要提到一个人时,您可以省略--avatars;后端可以合成一个灵魂角色。
- 默认:
- 可选择选择设置项。
- 钩子:
higgsfield marketing-studio hooks list --json - 设置:
higgsfield marketing-studio settings list --json传递选定的 ID 作为仅用于marketing_studio_video的--hook_id <hook_id>和--setting_id <setting_id>。除非用户明确想要强化相同的措辞,否则不要将钩子的提示复制到--prompt。
- 钩子:
- 如果需要,选择模式。 默认是
ugc;仅仅因为存在--hook_id并不需要--mode。其他当前模式包括viral、tv_spot和seller;用户可以在提示中指定模式。 - 提交并等待。
higgsfield generate create <jst> [--prompt "..."] [--avatar_ids <id>...] [--product_ids <id>...] [--hook_id <id>] [--setting_id <id>] [--ad-reference-id <id>] [--mode <mode>] [--format-id <id>] [--brand-kit-id <id>] --wait。Marketing Studio 报告其自己的作业类型;不需要额外的--json来解析状态;标准输出包含结果 URL。
病毒式传播预测器(brain_activity)
使用任务类型 brain_activity 来分析已完成视频的钩子和病毒式传播潜力。这是视频分析,不生成媒体资产。
工作流程:
- 用户提供本地视频文件或先前任务/上传 ID。
- 提交分析:
higgsfield generate create brain_activity --video <local-path-or-id> --wait - 输出是包含分数和可操作洞察的报告格式文本。查阅
references/viral-predictor-output.md了解如何解释分数。 - 始终提供 Open 报告链接以及分数摘要。
brain_activity 的提示是不必要的;模型会自行分析视频内容。不要传递 --prompt。
参考文献
本技能附带的 references/ 目录包含:
model-catalog.md— 显示名称到后端模型 ID 的完整映射media-inputs.md— 每个模型声明的媒体角色marketing-ad-references.md— 创建和使用广告参考的详细信息marketing-brand-kits.md— 创建和使用品牌工具包的详细信息viral-predictor-output.md— 如何解释病毒式传播预测器分数