JayGPTPro/keyword-openers

关键词开场视频生成器

搜索了“热狗烤叉”的顾客和搜索了“蔬菜烤叉”的顾客，今天看到的是同一个视频，开头还是个棉花糖。这个技能给每个顾客一个匹配他们搜索词的开场。

它改变什么： 视频前2到6秒的画面，以及一个包含关键词的标题。 它从不改变： 音轨、时长，以及第一个剪辑点之后的所有内容。

Sponsored Brands 视频开始时没有声音，所以顾客实际看到的就是第一个画面和上面的文字。这就是为什么开场部分是值得匹配的。

卖家需要提供的材料

1. 一个完成的商品视频（mp4 或 mov）。16:9 或 9:16 画幅。
2. 关键词，3 到 10 个。如果卖家没有列表，主动提出协助：阅读商品详情页，提出能描述不同用途、食物、人物或地点的关键词（因为这些会改变画面）。跳过那些只重新排列相同词语的关键词，它们得到的场景是一样的。
3. 商品的 ASIN，这样开场场景才能展示真实的商品。

要求卖家在一条消息中提供以上所有信息。如果缺少某项，再问一次，然后继续。

第一步：读取视频

python3 scripts/openers.py inspect "<video>" "<workdir>" --keywords "kw one; kw two; kw three"

<workdir> 是视频旁边的一个新文件夹，命名为 keyword-openers。这个命令会生成 inspect.json、plan.json 和两张接触印样图。在 Windows 上，此处和第四步的命令应使用 python 而不是 python3。

打开 opening-sheet.jpg 并查看。 标记为 REPLACED 的方块就是将被替换掉的部分。如果那里有 logo、价格、声明或内嵌文字，请在继续之前告知卖家，并提供 cuts_first_20s 中更早的剪辑点（在 plan.json 中设置 "window"）。

同时打开 look-sheet.jpg。 您即将编写的场景必须看起来像是为这个视频拍摄的：相同的时间、相同的光线、相同类型的人物、相同的镜头质感。

如果 inspect.json 中的 notes 不为空，请按原样读给卖家听。当笔记要求重新导出（帧率超过 30、可变帧率、96 kHz 音频）时，主动提出用 ffmpeg 制作修正后的副本，并检查该副本。当 aspect 不是 16:9 时，在消耗任何积分之前告知卖家 Sponsored Brands 视频只接受 16:9 画幅，并且只在卖家希望为其他广告位制作版本时才继续。

第二步：为每个关键词编写一个开场场景

严格遵循 references/prompt-recipe.md 的指导。每个关键词一个提示词，每个提示词对应一个时长 opener_seconds_to_generate 的单镜头。用一行简短描述向卖家展示场景（例如“热狗烤叉：一位父亲和他的儿子手持两根热狗，在同一篝火上方烤制”），然后继续，除非卖家提出异议。除非被要求，否则不要粘贴完整的提示词。

第三步：定价，然后生成

产品参考图片：调用 scrape_video_reference_images_from_asin 获取 ASIN（如果商品所在市场不是 amazon.com，还需提供 domain），并等待图片 URL 返回。使用前四张图片。

如果一个关键词描述的是动态特性（可伸缩、可折叠、可打开的盖子），则需要动作参考，否则模型会凭空想象出该机构：这里制作的第一个可伸缩开场是自动增长的，就像魔法一样。首先在卖家自己的视频中寻找该特性，并用 ffmpeg 剪辑出那些秒数。仅当视频中没有展示时，才向卖家索要一段使用该特性的短视频（3 到 8 秒，至少 300 像素高；手机拍摄的片段亦可）。 使用 create_reference_asset_upload 能力（通过 search_capabilities 找到，用 PUT 方法将文件上传到返回的 URL）上传它，并将 assetUrl 传入 seedanceReferenceVideoUrls。在提示词中说明需要从该片段中借用什么（动作），以及忽略什么（它的桌子、光线、其他物体）。参考视频会增加价格，因此请将其包含在价格检查中。

在运行任何生成之前先报价。使用 video_generation 预设（模型 seedance_2_5_reference、720p、开场视频长度、videoCount = 关键词数量）调用 get_credit_balance_and_costs。720p 是任何视频生成的默认值：开场只在搜索结果的狭小方块中播放几秒钟，与 1080p 的差异几乎不可见。仅当卖家的视频是 1080p 或更高分辨率，并且他们明确要求最清晰的开场时，才另外提供 1080p 的报价。永远不要凭记忆报价。然后说一句话并等待肯定答复：

“5个开场，每个5秒，Seedance 2.5 @ 720p：[价格调用返回的数字] 积分。开始？”

如果卖家想要更便宜的方案，就提供 seedance_2_mini_reference 的价格。480p 的草稿适合判断场景质量，但对于 1080p 视频上的广告来说太过模糊。

然后为每个关键词调用一次 generate_video，所有调用同时发送：

• modelType: "fal_seedance"，seedanceModel，seedanceMode: "reference_to_video"
• seedanceReferenceImageUrls：产品图片
• seedanceDuration：opener_seconds_to_generate
• seedanceAspectRatio：来自 inspect.json 的 aspect
• seedanceResolution：按定价设置
• asin：ASIN（项目根据它创建或重用）
• promptEnhancement: "skip"（配方已经写好了最终的提示词）
• sceneTitle：关键词

使用 wait_for_operation / get_video_generation_result 等待完成。将每个完成的剪辑文件下载到 plan.json 中其对应行指定的路径：

curl -L -s -o "<workdir>/openers/<slug>.mp4" "<video url>"

生成失败或被拒绝：用一行文字报告，然后继续处理其余的。未经请求，重试不得超过一次；每次重试都会再次消耗积分。重新生成的场景会以新的 "label" 和文件名保存为一个新版本，绝不能覆盖已经付费的剪辑。

没有 Genrupt？ 该技能仍然可用。卖家将任何剪辑（拍摄的、素材库的、其他工具的）放入 plan.json 中指定的路径，然后直接进入第四步。

第四步：构建所有版本

python3 scripts/openers.py build "<workdir>/plan.json"

不消耗积分。每个版本在 720p 下大约需要 4 秒，1080p 下需要 10 秒，4K 下需要 25 秒，每完成一个版本会打印一行输出。运行命令时设置 10 分钟超时：通常的 2 分钟限制不足以处理长列表。对于每个关键词，它会替换开场画面、叠加标题，并检查写入的文件：确保长度与原视频相同、音轨逐位一致、画面其余部分未改动、开场实际上是新的、标题位于画面内。

要在修复后重新构建单个关键词并保留其他关键词不变，请添加 --only "hot dog roasting sticks"（多个关键词："kw one; kw two"）。

然后查看每个 out/check/<slug>-seam.jpg。您需要检查脚本无法判断的三件事：

1. 新场景中的产品是卖家的产品（形状、颜色、数量）。
2. 标题清晰可读，并且不位于人脸或关键词所描述的产品上。比较名为“title held”的方块和旁边的“under the title”方块：后者是同一时刻但没有文字的画面。auto 仅根据亮度和细节进行猜测；它无法识别人脸，在火光下最平静的区域往往是脸部所在区域。
3. 从“最后新帧”到“第一原始帧”的跳跃看起来像一个正常的剪辑点。

标题位置不合适可以免费修复，所以请在卖家看到之前修复：为该变体指定一个 place（top、bottom、top-left、top-right、bottom-left、bottom-right），并且当全尺寸下没有可用位置时，指定 title_scale（0.5 到 1）。重新构建并再次检查。场景中产品不符合的，需要用修正后的提示词重新生成（先询问卖家，因为会消耗积分）。

第五步：交付

为卖家打开 out/index.html。按此顺序告知他们：

1. 多少个版本已就绪，以及要上传的文件位于 out/upload/ 中：每个关键词一个文件，以关键词命名。
2. 您在接缝检查页面上看到的任何需要他们关注的问题。
3. 如何使用它们：references/amazon-upload.md（每个关键词一个广告组，每个广告组使用其对应的版本）。该页面也包含了相同的步骤。

如果一个关键词有多个版本，在选定一个版本之前，out/upload/ 中不会有文件。询问卖家选择哪个版本，在该变体上设置 "pick": true，然后再次构建。

plan.json

{
  "video": "/path/to/video.mp4",
  "window": 3.875,
  "style": "pop",
  "font": "bold",
  "accent": "CD763C",
  "title": true,
  "opener_audio": "off",
  "variants": [
    {"keyword": "hot dog roasting sticks", "opener": "openers/hot-dog-roasting-sticks.mp4"}
  ]
}

• window：要替换的画面秒数。inspect 选择视频本身最接近 4 秒的剪辑点。仅可更改为 cuts_first_20s 中的其他值。
• style：关键词在屏幕上的显示方式。
  • pop（默认）：大写字母。使该关键词区别于其他关键词的词汇落在一个高亮条上，高亮条扫入；其余词汇逐个弹出。专为搜索结果中无声的小方块而设计。
  • sticker：关键词位于一个倾斜的白色搜索贴纸上，贴纸盖印进入屏幕，不同的词汇被标记出来。
  • kinetic、line、search：安静的下三分之一标题，适合追求平和风格的品牌。
• punch：对于 pop 和 sticker 样式，在标题落地的节拍上，画面会切入一个 1.08 倍的更紧构图。设为 false 可关闭；punch_zoom 可以设置其他缩放比例。
• place（仅用于 pop 和 sticker）：auto（默认）自动猜测画面中较为平静的区域（顶部或底部），如果某侧明显更平静，则选择该侧。top、bottom、top-left、top-right、bottom-left 或 bottom-right 可强制指定位置。三种安静样式始终位于底部。
• title_scale（仅用于 pop 和 sticker）：0.5 到 1。当全尺寸下画面没有可用位置时，使用较小的标题。可应用于文件中所有版本，或仅针对某个变体。
• font：bold、round、serif、clean。与视频中已有的字体风格匹配。
• accent：取自视频本身的颜色。如果已知品牌色，可覆盖。
• title：设为 false 则屏幕上不显示文字。
• opener_audio："off" 保持音轨逐位不变。一个数字（例如 -18）会以该分贝值将新场景自身的声音混入其下方。
• take：开场场景通常比 window 稍长。end（默认）保留其最后几秒，此时场景已趋于稳定。start 保留其最初几秒，适用于动作立即开始的场景（如棍子伸出、盖子打开）。
• 同一关键词的多个版本：重复该变体，使用相同的 keyword、不同的 opener 和 "label"（"A"、"B"）。每个版本都会构建到自己的文件和卡片中，以便卖家通过查看来选择。当某个关键词很重要时，提供第二个版本；说明其成本。在选定版本上设置 "pick": true 会将其复制到 out/upload/<keyword>.mp4。
• 一个变体可以自行携带 "title_text"（当屏幕上显示的文字应与关键词不同时）、"take"、"emphasis"（要标记的单词；默认情况下是各关键词中不共用的单词，例如“hot dog”在“hot dog roasting sticks”中）、"place"、"title_scale"、"pick" 和其自己的 "window"。

当出现问题时的处理方法

build 会先检查 plan.json 并用文字说明需要修复的内容。如果关键词包含内置字体无法绘制的字母（希伯来语、中文、阿拉伯语），会以该句子报错：为该变体提供一个拉丁字母的 "title_text"，或设置 "title": false。表情符号会从标题中移除。超过 5 个单词的关键词会渲染得很小；为其提供一个较短的 "title_text"。如果视频在 2 到 6 秒之间没有剪辑点，则使用一个短的溶解过渡而不是直接剪辑。

规则

• 永远不要延长视频长度，也永远不要修改其音轨。如果某个请求需要其中任何一项，那就是不同的任务；请明确告知。
• 永远不要在场景中虚构产品特性。场景应根据产品实际情况展示关键词描述的用途。
• 如果原始视频中有人物，新场景中的人物应与之匹配。
• 除非卖家批准，否则每个关键词只付费生成一次。