一张商品图生成广告大片：Codex Skill 实战课后笔记

这一期视频演示了一个很实用的 Codex Skill：给它一张商品图和一句需求，它会先像广告导演一样做方案，再生成分镜参考图，最后才去生成完整的商业广告视频。

你不需要先会写分镜、剪辑或配音。真正需要做的，是在两个关键节点认真确认，避免 AI 一路“自作主张”生成不符合商品和业务要求的内容。

这个 Skill 能帮你做什么

它适合把商品图片变成短视频广告，特别适合做 15 秒左右的竖版电商素材。

整个过程可以理解为三步：

步骤	你会看到什么	你需要做什么
1. 提交商品图和需求	AI 给出广告方案、分镜、口播和声音设计	看方向是否符合你的商品和受众
2. 确认生成参考图	AI 生成真正用于视频的商品主控图和分镜图	检查商品是否保真、人物和场景是否合适
3. 确认并生成视频	按确认过的图片和计划提交视频任务	确认次数、时长和成本上限后再生成

视频中用鞋子做了演示：从商品图片出发，AI 先设计复古街头感的广告方向，再做出多张分镜参考图，最后生成了带旁白、环境音和配乐思路的成片。

使用前要准备什么

一到几张清晰的商品图。正面、侧面、细节图越清楚，商品越不容易跑偏。
你想卖给谁，以及最重要的卖点。例如“通勤女性”“轻便、耐脏、米白色”。
Codex 和安装好的 ai-commerce-video Skill。
可用的视频模型 API。图片、视频模型 API 可以从 AI跃云配置；具体模型、接口地址、时长档位、图片数量和返回字段，要以视频模型 API 接口文档为准。
FFmpeg。它是一个本地音视频处理工具，用来拼接多段视频和做技术检查。

第一次怎么使用：照着视频做

先把商品图拖进 Codex，对它说一句清楚的任务。首次建议只让它出方案，不要立刻调用视频 API：

请使用 ai-commerce-video。
商品图：<把你的商品图片上传到这里>。
做一条 15 秒、9:16 的抖音商品广告视频，目标用户是通勤女性。
卖点只允许使用：轻便、米白色、耐脏。
需要一位年轻女模特自然穿搭，有中文旁白。
先给我完整方案，不要调用视频 API。

第一步：确认广告方案

正常情况下，Skill 会先给你一张“方案卡”，其中包括：

商品卖点和目标人群；
15 秒分镜和每次切镜的原因；
口播大意、声线、环境音和配乐方向；
需要生成哪些参考图；
每张图的提示词，以及后续视频提示词蓝图。

这一步没有进入付费生成。你只需要检查四件事：商品是否理解正确、模特和场景是否合适、口播有没有夸大、画面风格是否符合品牌。

如果你想要模特、指定穿搭、特定文案或画面文字效果，最好在第一次需求里就说清楚；视频演示中也特别强调了这一点。

方案满意后，回复：

方案确认，生成参考图。

第二步：确认参考图

这一步会生成参考图，常见是 3 到 5 张。它们分为三类：

素材类型	用途	默认能否直接提交给视频模型
证据图	你最初上传的商品图，用来确认事实	不直接提交
控制图	AI 按已确认方案重新生成的商品主控图、角色图和镜头图	可以提交
审核图	九宫格或分镜拼图，只方便人看	不提交

重点看“商品主控图”：商品的外形、颜色、材质和关键细节要和原图一致，但光影和构图要像专业广告。若商品已经变样，直接让它修改参考图，不要带着错误图片继续生成视频。

确认时，Skill 还应该列出真正会上传的图片顺序、每一段的含义、是否要加字幕，以及准确的付费请求次数。确认无误后，才回复：

确认并生成。

第三步：生成与验收成片

确认并生成后，Skill 会先做一次免费的接口探活，再按镜头提交视频任务、轮询任务状态、下载并拼接成片。

如果任务超时，不要直接重新点生成。正确做法是：先查询原任务。因为重新提交可能产生第二笔费用，也可能拿到两条不同的视频。

拿到 MP4 也不要急着交付，至少检查：

时长是否接近计划；
商品是否仍然能辨认；
人物、服装和场景是否大体连续；
旁白是否清楚，声音是否真的存在；
是否误生成了字幕、价格、水印或不实宣传；
最终 delivery-manifest.json 是否为 pass。这是 Skill 的交付检查单通过标记，不只是“文件能播放”。

新手最容易踩的坑

一句话写得太笼统。 只说“生成广告视频”也能跑，但人物、口播、场景和文案会随机。至少补上人群、卖点、比例、是否需要模特和旁白。
把原商品图直接当视频控制图。 原图是事实依据；确认方案后应生成专门的控制图，画面更稳定，商品也更容易保真。
让视频模型画字幕或价格。 视频模型很容易把文字画错。先生成干净成片，字幕和价格用本地后期单独加。
超时就重试。 有任务 ID 时先继续查询原任务；Skill 的原则是每个镜头最多提交一次。
把“能播放”当成完成。 技术播放、声音听感、商品一致性和最终商业可用性，是不同的检查。

用 Codex 开发这个 Skill：完整提示词模板

下面是本期配套的开发提示词。复制到一个新的 Codex 项目里后，先填最上面的三项；没有读懂 API 文档前，Skill 必须停止，不能猜接口参数。

你是 Codex 工程 Agent。立刻读取并严格执行 skill-creator（以及 skill-design-principles）。必须用 skill-creator 的规范从零创建 Skill：SKILL.md 短、description 写清触发词、细节放 references/、确定性流程放 scripts/、配置放 assets/templates/。不要手写杂乱目录，不要 TODO/伪代码，不要再接外部 LLM 或生图 API。

智能层只用 Codex 多模态 + 内置 imagegen。视频生成只用学生提供的视频 API。Python 3.10+ 标准库 + FFmpeg。

## 0. 先填这三项，缺一即停止

VIDEO_API_BASE_URL=
VIDEO_API_KEY_ENV_NAME=AI_COMMERCE_VIDEO_API_KEY
VIDEO_API_DOCS=

# 粘贴接口文档或本地路径。必须能读出：创建/查询 URL、鉴权、模型 ID、图片字段、时长字段与合法档位、分辨率/画幅、参考图数量、提交/轮询 JSON、任务 ID 和视频 URL 字段。

Key 只允许之后用脚本写入 ~/.codex/ai-commerce-video.env（权限 600）。模型字段必须从文档映射进 model-config，禁止猜测。文档是多参考图就走参考图；只有单图就走合成首帧，不要假装支持多参考图。

## 1. 要做成什么

做一个 ai-commerce-video Skill：用户给商品图和一句需求，你当广告策划 + 视觉导演，产出可投放的短视频广告。

核心不是“能调视频 API”，而是：

- 普通用户只做两次决定。
- 原图当事实证据，确认方案后再生成真正上传的控制图。
- 每个镜头只付费一次，超时查原任务，禁止自动重发。
- 视频模型不画字幕；先干净成片，字幕本地后期。
- 有 MP4 不算完成，只有 delivery-manifest.json.status=pass 才算交付。

## 2. 用户流程（必须一致）

商品图 + 需求
→ 分析素材，自动选一个可投产方向（另给一个简短备选）
→ 阶段1方案卡：卖点、15秒分镜/口播大意、切镜动机、参考图计划、每张生图提示词、视频提示词蓝图
→ 等“方案确认，生成参考图”（不生图、不调视频 API）
→ imagegen 生成控制图（必须含专业商品主控图；分镜拼图只供人看）
→ prepare → 校验 → 免费预检（无 Key 也要过）
→ 阶段2：按上传顺序展示实际图、提示词含义、字幕选择、准确付费次数
→ 等“确认并生成”
→ confirm → 免费探活 → 每镜 POST 一次 → poll/resume → 拼接 → 审查 → 可选字幕 → finalize

不要拆成方案/脚本/图片/预检/付费一串小确认。阶段1不是付费授权。

默认：15 秒；短视频 9:16；可见数字人口播；普通商品不能自己动；字幕默认关；不编造价格/功效/资质。

## 3. 效果规则（删了就会变差）

三层素材：
- 证据：用户原商品/人物/场景图，默认不能上传视频模型。
- 控制图：方案确认后生成，每张一个职责，可以上传视频模型。
- 审核图：分镜/九宫格，只供人看，不能上传视频模型。

通常 3–5 张，上限按 API。必须有 product 主控图：外形颜色材质保真，构图光影按广告重做。禁止把原图拷贝冒充生成图。要精确每段第一帧：改分段图生视频，并重新展示付费次数。

提示词编译器（任意商品同一结构）：
1. 视觉方向（禁止手写 <IMAGE_n>，token 按实际上传顺序由编译器追加）。
2. 本段任务 + 口播原文恰好一次（或明确无对白）。
3. 创意结构：商品 → 证明 → 购买理由 → CTA。
4. 只用用户提供的事实。
5. 参考图角色映射。
6. 干净画面 + 口播模式 + 商品运动政策。

禁止让视频模型生成字幕/价格/CTA/水印。超预算就改短视觉方向，不准截断口播和安全规则。

付费闸门：
- 付费次数 = 基础镜头数，自动修复次数 = 0。
- 预检冻结合同（计划/时长/模型/图片哈希/dry-run）。
- POST 前重放载荷，漂移就停。
- HTTP 前先记一次提交；有任务 ID 只能继续查；无 ID 但已提交则阻断。
- 首次付费前用文档里的免费接口探活（如 GET /models）；失败则 attempts=0，确认仍有效。
- 探活和正式请求走同一网络路径；可用 Skill 专用代理环境变量，禁止改 Clash/系统代理。

时长与成片：
- 只用文档合法档位的最少次数。上限 15 秒时：25=15+10，30=15+15。
- 非末段口播必须完整句结尾。
- 多段拼接：中间音频 PCM，口播之间不淡化，最后一次 AAC。
- 需要语音却没有音轨：失败，不准补静音冒充。
- 验收从宽：完整连贯、商品可识别、人物/服装/场景大体一致、语音清楚、卖点大意在；不要求逐字复现口播。

字段名固定：digital-human-spoken / static-inanimate / commerce_direct / multi_reference_commercial；账本 planned → attempted → submitted → polling → downloaded → verified。

## 4. 按 skill-creator 落地

ai-commerce-video/
├── SKILL.md
├── README.zh-CN.md
├── assets/templates/
├── references/
├── scripts/
├── tests/
└── evals/evals.json

脚本要真能跑，stdout 为 JSON：
setup_private_env.py prepare_project.py validate_config.py validate_platform_plan.py preflight_project.py workflow_engine.py check_provider_readiness.py generate_video.py poll_video.py duration_planning.py stitch_clips.py review_render.py generate_subtitles.py burn_subtitles.py finalize_project.py

prepare_project.py 写出 generation-plan.json（合同、编译后 prompt、素材角色、付费上限、字幕计划）。运行产物放到 projects/<时间戳>-<名>/，不要把示例视频打进 Skill。

需要项目发现时，建 .agents/skills/ai-commerce-video 相对软链接，不要复制第二份。

## 5. 测试、修复、交付

先检查 Python 3.10+ 和 FFmpeg。然后实现完整功能，不是 Demo。

离线测试至少覆盖：无确认不能 submit；原图/分镜图不能当上传图；手动 token 失败；口播只出现一次且无字幕词；预检无 Key；合同漂移阻断；同一镜不能二次 POST；探活失败 attempts=0；mock 提交-轮询-下载；finalize 缺审查不能 pass。

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -q
python3 scripts/validate_config.py --config assets/templates/model-config.example.json

失败就改再跑，直到通过。默认禁止真实扣费。

完成后告诉学生：Skill 路径、如何发现、如何用 setup 脚本存 Key、第一次只做免费预检。调用示例：

请使用 ai-commerce-video。商品图：<路径>。做 15 秒抖音带货，数字人口播。先给完整方案，不要调用视频 API。
方案确认，生成参考图。
确认并生成。
上次提交超时了，不要再发新请求，继续查原来的任务。

验收：两次确认、三层素材、编译器、每镜一次、干净成片、delivery pass、Key 不进源码、模型字段来自学生文档、离线测试通过。