# 百炼 wan3（万相3.0）视频生成工作流参考

本文件取代原 `jimeng-workflow.md`，定义技能对接**阿里云百炼 · 万相 3.0（wan3.0-video）**的工程要点。技能所有"调用 AI 视频接口"的步骤都以本文件为准。

## 一、模型与能力边界（决定技能流程）

- **模型**：`wan3.0-video`（标准版）/ `wan3.0-video-prime`（高速版）。All-in-One，按 `input.media` 的 type 与 prompt 意图自动路由任务类型。
- **单段时长上限 30 秒 / 30fps**：直接满足技能"一个片段 ≤30 秒"的硬约束。
- **原生音视频**：一次调用即生成"画面 + 原生语音对白 + BGM + 音效"，且原生对口型。因此口播无需单独 TTS 再对口型——把口播写进 prompt 作为对白，音色文件作为 `reference_audio` 传入即可。
- **多模态参考（最多 20 个素材）**：图片 ≤10 张（单张 ≤20MB）、音频 ≤5 段（单段 ≤15s、≤15MB）、视频 ≤5 段。本技能只用"图片参考 + 音频参考"。
- **参考引用语法（重要坑·2026-09-18 修正）**：`media` 数组顺序在**内部**对应素材即可，**绝不能在 prompt 文本里写 `Image 1` / `Image 2` / `Audio 1` 这类标记**。实测 wan3 会把 prompt 中出现的 `Image N`/`Audio N` 文字当成对白**直接念出来**，形成"开头莫名其妙的一段话"（BUG B）。正确做法：用自然语言描述画面与音色，例如"一位女性…身处怡呵美门店内…""原生清晰女声普通话对白（音色参考随附音频）"，**不出现任何 `Image N`/`Audio N` 字样**。素材内容靠 media 数组顺序与画面/音色描述间接对应，不必显式编号。
- **不支持二次创作**：wan3 虽有视频编辑 / 延长模式，但技能第 8 条要求"每次修改都重新组装完整脚本重发"，故**只用文生/参考生视频一种模式，禁用 edit / extend**。

## 二、接口与鉴权

- **异步调用**：HTTP 仅支持异步，必须带请求头 `X-DashScope-Async: enable`。
- **端点**（注意 `{WorkspaceId}` 与 `region`）：
  - 北京：`https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis`
  - 新加坡：`https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/...`
  - 任务查询：`GET https://{WorkspaceId}.{region}.maas.aliyuncs.com/api/v1/tasks/{task_id}`
- **视频主机不带 `llm-` 前缀**：用户从百炼控制台拿到的 `…maas.aliyuncs.com/compatible-mode/v1` 是 **LLM 对话网关**（OpenAI 兼容模式），**视频生成不使用它**。视频主机为 `https://{WorkspaceId}.{region}.maas.aliyuncs.com`（无 `llm-` 前缀、`/api/v1` 之后才是视频路径）。脚本按 `config.workspace_id` + `config.region` 自动拼，或显式覆盖 `config.api_base`。
- **鉴权**：`Authorization: Bearer $DASHSCOPE_API_KEY`。**密钥必须走环境变量，禁止写死**。
- **地域一致**：模型、Endpoint、API Key 必须同地域，跨地域调用会失败（本片 workspace 在 cn-beijing，Key 也须为 cn-beijing 地域）。
- **流程**：创建任务 → 拿 `task_id`（24h 有效）→ 轮询 `tasks/{task_id}` 至 `SUCCEEDED` → 取 `output.video_url` → 下载。

## 三、素材 → wan3 参考映射（技能固定 4 项 + 自动 2 类）

| 素材 | 来源 | media type | prompt 引用 | 约束 |
|---|---|---|---|---|
| 人物完整形象照 | **生成物料**：以 `character_5view` + `uniform_detail`（固定素材）为参考生成并确认（见 `asset-collection.md` 第二节） | `reference_image` | `Image 1` | 全片同脸/同发型/同年龄感/同制服；**胸牌样式与确认稿一致、不可变更** |
| 门店内景照片（含 LOGO） | **生成物料**：以 `logo_3d`（固定素材）为 LOGO 参考生成含 LOGO 并确认（见第二节） | `reference_image` | `Image 2` | 前台墙面须出现怡呵美立体 LOGO |
| 门店空间实景图（zone 参考，技能内置） | **技能内置资源**：`assets/store-spatial-index/` 下的 `Z0X_0Y_*.png`（10 张 9:16 实景图，区域/机位/可用-禁用区见 `references/store-spatial-index.md`） | `reference_image` | 自然语言描述 | 按脚本各 Shot 所在 zone 选取对应实景图传入；与「门店内景照片」二选一、**实景优先**；U01–U03 禁用；人物真实经过的过渡空间（如走廊 Z05）必须传对应图，只靠俯瞰图+文字会脑补「幽灵硬件」 |
| 插画参考图 1/2 | 自动生成（抽象可视化风格启发） | `reference_image` | `Image 3` / `Image 4` | 无真人皮肤/血液/文字 |
| 音色文件 | 公网 URL `config.brand_assets.voice_ref.url`（优先）或本地 `assets/brand/voice_ref.*`（兜底） | `reference_audio` | `Audio 1` | 单段 ≤15s；超长则裁剪一段代表音色 |
| （生成输入，不提交）人物五视角图 / 制服细节图 / 立体 LOGO | 固定素材，仅用于生成 Image 1 / Image 2，本身不提交 wan3 | — | — | 锁死、不可被自动生成覆盖 |

> ⚠️ 表中"prompt 引用"列的 `Image 1`/`Image 2`/`Image 3`/`Image 4`/`Audio 1` **只是素材顺序的内部代号，绝不能原样写进 prompt 文本**（否则会被 wan3 当对白念出，见第一节）。prompt 里用自然语言描述画面与音色即可，素材靠 media 数组顺序间接对应。

> 提交的是**确认后的生成物料**，不是原始 4 项文件本身。

## 四、单段 30 秒 prompt 范式（编导分镜版）

一个 prompt 描述**整段 30 秒**的连续画面（不要拆成多个 Shot 分开发请求）。要把它当作一条**专业编导分镜**来写——人物必须在门店场景里"活"起来，不能一直正对镜头站桩。必须覆盖四块：**人物行为动线 / 运镜组合 / 插画展示方式 / 门店丰富元素**（对应 `elements.md` 元素 25/26/27/12）。结构范式：

> 范式按官方「总体描述 + 镜头序号 + 时间戳 + 分镜内容」公式组织；时间戳用英文 `Shot N [x-y s]`，台词用花括号 `{}` 圈出。⚠️ **绝不在 prompt 里写 `Image N`/`Audio N`**（会被当对白念出）；用自然语言描述画面与音色。

```
【总体描述】
一位身穿[米白]美容师制服、[深栗色半扎长发 + 斜刘海]、胸牌样式与参考形象照一致的女美容师，
在怡呵美门店内（墙面有怡呵美立体 LOGO，背景虚化，可见前台、美容床、沙发、产品陈列架，
一名店员从画面边缘虚化走过）拍摄。画面中的女美容师、门店与插画均依据随附参考图生成，
须保持人物脸型/发型/制服/胸牌一致，门店须含怡呵美立体 LOGO，插画为卡通动漫风抽象可视化（无真人、无文字）。

整体动线：[开场端坐于面诊桌前自然引入话题，中段起身缓步走向产品陈列架、边走边说，
结尾保持站立、抬手手势收束]；说话间以自然手势比划、轻微点头等真实肢体动作呈现。

镜头语言：[开场中近景极轻微横摇，人物走动时跟随拍摄，讲到核心点时缓慢推近，结尾缓慢拉远收束]；
整体手持微晃保留真实手机拍摄质感。

语气与节奏：她自然亲和地讲解，像真人面对面聊天一样有温度有起伏——问句好奇上扬、肯定句沉稳、
列举句轻快有层次、收束句温和坚定；整体语速比自然对话放慢约一半、从容舒缓，让内容自然撑满约[30s]，
句与句之间留约[0.5s]自然气口，不赶。

声音：原生清晰女声普通话对白（音色参考随附音频）、轻微环境音、无背景音乐；
口播须有自然语调起伏与停顿，禁止平淡匀速念稿。

硬性约束：口播须严格限于下列分镜台词，禁止添加、删改或自由发挥任何文案之外的语句、语气词；
插画仅以局部形式出现（圆形/圆角画中画），禁止全屏覆盖；绝对禁止出现字幕、任何画面文字、
卡通化人物、塑料皮肤、变脸、服装漂移、场景跳变、或其他清晰正脸人物抢镜。

结构说明：以下「Shot序号 + 时间戳 + 分镜内容」为本片分镜脚本；Shot序号与时间戳是给模型的
节奏结构指令，不是台词，禁止当作语音读出；也禁止在任意空白时段补加台词或语气词。

【分镜脚本】
Shot 1 [0-4s]：[开场中近景，女美容师端坐面诊桌前，手持微晃手机质感，镜头极轻微横摇]；
她好奇上扬地提问{[口播句1]}，句末留自然气口。

Shot 2 [4-7.5s]：[仍端坐，中近景]；她自然沉稳肯定{[[订期]去角质的→按用户文案填，见下方多音字提示]}，语气笃定、不赶。

Shot 3 [7.5-12.5s]：[她起身缓步走向产品陈列架、边走边说，镜头跟随拍摄]；列举句轻快有层次{[口播句3]}。

Shot 4 [12.5-19.5s]：[走到陈列架前站立，讲到核心点时镜头缓慢推近；此处画面右侧嵌入圆形画中画
展示[插画1]（抽象可视化，无真人无文字，禁全屏）]。该句放慢加重带警示，讲到「[核心重音点]」时
稍作重音并留自然停顿{[口播句4]}。

Shot 5 [19.5-26s]：[切换为画面侧边圆角区域画中画展示[插画2]（同风格，不铺满整屏）]；她自然亲和{[口播句5]}。

Shot 6 [26-30s]：[结尾缓慢拉远收束，她保持站立、抬手手势收束，中近景]；收束句温和坚定{[口播句6]}，留足停顿感。
```

- 口播台词用花括号 `{}` 圈出、逐句写进各 Shot 的「分镜内容」，wan3 原生生成语音并对口型；`{}` 之外的是画面/运镜描述，不会被当台词。
- **人物行为动线**按口播时长设计：≤15 秒用 1–2 个动作切换，30 秒用 3–4 个动线（走动/坐/起/落座/整理）。
- **运镜**每条约 2–3 种按时间轴穿插，不全程单一机位；**插画展示方式**一场内可混用多种，不恒定为一种；**门店丰富元素**随机点缀 2–3 个，增加景深与真实感。
- **时间戳即控速锚点（关键）**：`Shot N [x-y s]` 连续铺满目标时长（如 0–30s），既是分镜结构也是节奏约束。wan3 实测在「强制时长 > 口播实际长度」的空白时段会**自动编造废话填充**（padding 幻觉），故内容必须真实撑满时间戳区间——靠放慢语速 + 句间留足气口，而非空撑时长。宁可 `duration` 用 `−1` 智能时长（按内容自动定长，上限 30s）也不要硬撑。
- 时长参数 `duration` 默认 `30`，`ratio=9:16`，`resolution` 按 config；若口播偏短或要规避 padding，可显式缩短 `duration` 或设 `−1`。
- 反向约束（硬性禁令）也写进 prompt 负向描述：无字幕/无文字/无卡通化/无塑料皮肤/无变脸/无服装漂移/无场景跳变。

## 五、LOGO 落位（保证成片一定出现 LOGO）

只靠 prompt 文字描述"前台有 LOGO"不可靠，必须在**生成门店内景照片**时就把 LOGO 锚定：

1. 在 `asset-collection.md` 第二节第 2 步生成门店内景照片时，把固定素材 `logo_3d.*`（立体 LOGO 源文件，来自 URL 或本地）作为**图像生成参考**，要求模型在前台/墙面生成与参考一致的怡呵美立体 LOGO。
2. 若生成模型对 LOGO 还原仍不精确，可在生成后对采用稿做图像贴图精修（PIL 合成），确保 LOGO 清晰一致。
3. 确认后的门店内景照片（含 LOGO）作为 **Image 2** 传入 wan3；原始 `logo_3d` 本身不单独提交。

## 六、调用脚本

技能在用户确认脚本后，调用 `scripts/generate_video.py`：

```bash
export DASHSCOPE_API_KEY="sk-xxx"
python scripts/generate_video.py \
  --config scripts/config.json \
  --prompt "<脚本模板第五节：整段 prompt>" \
  --media \
    /abs/人物_完整形象照.jpg:reference_image \   # Image 1（由 character_5view + uniform_detail 生成、确认）
    /abs/门店_内景_采用.jpg:reference_image \     # Image 2（由 logo_3d 生成含 LOGO、确认）
    /abs/插画_参考1.jpg:reference_image \        # Image 3
    /abs/插画_参考2.jpg:reference_image \        # Image 4
    "https://cdn.x/voice_ref.mp3:reference_audio" \  # Audio 1（config URL 透传，或本地路径）
  --duration 30 --ratio 9:16 --resolution 720P \
  --output /abs/成片.mp4
```

脚本会自动：公网 URL 素材直接透传（config.reupload_external_urls=true 时先下载再编码 base64 直传）、本地生成素材（人物形象照/门店内景/插画）读取后编码 base64 直传→建任务→轮询→下载到 `output_dir`，并把结果打印到 stdout（`VIDEO_PATH=...`）。技能捕获后把视频 present 给用户确认。

## 七、常见坑

- 模型/Endpoint/Key 跨地域 → 直接失败，务必同地域。本片 workspace 在 cn-beijing，Key 也须 cn-beijing 地域。
- `media[].url` 支持**公网 URL 直传**，也支持**图像 base64 直传**（`data:{mime};base64,{b64}`）。固定 4 项若填了公网 URL（config.brand_assets），脚本默认直接透传；若 wan3 不接受站外 URL，把 `config.reupload_external_urls` 设为 `true`，脚本会先下载再编码 base64 直传。本地生成的图（人物形象照/门店内景/插画）一律编码 base64 直传，无需文件上传端点。
- 用户所给 `llm-….maas.aliyuncs.com/compatible-mode/v1` 是 LLM 网关，**视频端点主机不带 `llm-` 前缀**。若视频调用报 404，确认 `config.workspace_id`/`region` 是否拼出 `https://{ws}.{region}.maas.aliyuncs.com`；可显式填 `config.api_base` 覆盖。
- `reference_audio` 单段 ≤15s、≤15MB；音色样本过长先裁剪。
- `duration` 必须 ≤30，超了先在技能侧精简口播（见 SKILL.md 第 5 步硬卡循环）。
- 不传 `X-DashScope-Async: enable` 会报"current user api does not support synchronous calls"。

### 实测新增坑（2026-09-17 ~ 09-18，去角质频率项目验证）

- **坑1 · `Image N`/`Audio N` 被当对白念出（BUG B）**：在 prompt 文本里出现的 `Image 1`/`Audio 1` 等素材编号会被 wan3 当成台词念出来，表现为"片头莫名其妙的一段话"。**解法：prompt 中绝不写 `Image N`/`Audio N`，改用自然语言描述画面与音色**（如"一位女性…门店内…""音色参考随附音频"）。已验证删掉编号后片头干净。
- **坑2 · 强制时长 > 口播长度 → padding 幻听**：当 `duration` 大于口播真实时长，wan3 会在空白段**自动编造语句填充**（如结尾冒出"也沒衣服看管的"）。**解法：让口播内容真实撑满时间戳区间（放慢语速 + 句间气口），或改用 `duration=-1` 智能时长**；不要硬撑空时长。
- **坑3 · 多音字误读（如"定期"→"顶期"）**：wan3 端到端 TTS 对多音字消歧不稳定，纯文本时好时坏；**拼音标注（如"定(dìng)期"）反而会被整段念错（实测读成"定定妻"），不可用**。可用近义替换规避：把"定期"换成"订期"（同音 dìng、无歧义、语义贴），或"按周期"/"有规律地"。**提交前不要回改用户文案**，该替换本身就是防错手段。
- **推荐流程 · 生成后 ASR 自查**：成片下载后用本地 ASR（funasr / faster-whisper，不外传素材）提取音频转文字，逐字核对：①片头是否乱读 ②时间数字/Shot序号是否被念出 ③多音字读音 ④片尾是否 padding 废话。先自查再交付，避免来回试错。详见技能 `scripts/` 下的 `extract_audio.py` + `asr_wordlevel.py` 用法（从 mp4 抽音频→逐词时间戳）。
- **参考音频语义前置**：`reference_audio` 本是提取音色，但若样本本身带口播语义，可能被前置到片头。建议从音色源音频的**中段**裁一段（避开句首）作 ≤15s 样本。

### 实测新增坑（2026-09-21 · 四季防晒 DDKP-013 系列实战）

- **坑4 · 场景背景漂移（长镜头/走位段背景被换房间）**：wan3 在 25–30s 长镜头或人物走位段，会把已锚定的门店背景自行换成陌生房间（品牌墙、吊灯、门全部消失，沙发变样）。**解法**：在「总体描述」+ 每个 Shot 里**逐段锚定该 zone 的参考图元素清单**（例如门厅 Z01：品牌墙「YIHEMEI 你的水光肌肤管理师」+ 丝带吊灯 + 白门 + 圆几绿植 + 白沙发；产品区 Z02：怡呵美发光字展柜 + 灯带层板 + 绿植），并在硬规则里写"人物未走位时背景禁止漂移成其他房间"。**关键**：人物真实经过的过渡空间（如走廊 Z05）**必须传实景图**，只靠俯瞰图 + 文字描述不够，否则模型会脑补出"幽灵硬件/第二个前台"。**zone 实景图与 Z01–Z09 可用区 / U01–U03 禁用区 / V4 开放公共区关系 / 6 条空间锚定硬规则见 `references/store-spatial-index.md`，图片在 `assets/store-spatial-index/`，按 zone 文件名选取对应图传入。**
- **坑5 · 口播幻觉加词（句间/句末自行补词）**：TTS 会在口播文本外自行补词/补句（如"做好防晒"后凭空补"干皮"，或把 prompt 表格里的"插画持续""窗口拉满"等元文本当台词念出）。**解法**：① prompt 内联**完整「口播定本」**作唯一台词依据（不止是引用文件名）；② 显式负面示例"尤其禁止在『X』之后追加『Y』类词；禁止根据画面/主题自行补词"；③ 明确写"prompt 其他文字（章节标题 / 表格表头 / 规格标注 / 结构说明）一律不出声"。
- **坑6 · 单字发音缺陷（非多音字也读错）**：参考音频只克隆音色、**不控制单字发音**，个别字会稳定读错（例："晒"shài→shi）。与坑3（多音字）不同，这连拼音标注都救不了。**解法**：① **改字绕过（最快，推荐救急）**——把易错字换成近义/同音字且字数不变（例：末句"不是只有大太阳才需要**防晒的**"→"…需要**防护的**"），不动节奏/时长；② 重截参考音频基本无效（wan3 本就不控发音，且无原 30s 素材时不可行）。
- **坑7 · 插画内出现人物（两个主角并置）**：PIP 插画里若出现任何人物/人形轮廓，会与口播真人并置成"两个女主角"。**解法**：红线——插画只画机理示意 / 物品 / 皮肤特写 / 光线氛围，**不得出现任何人物、人形轮廓、手势、人影**（生成插画的 prompt 必须显式写"画面中严禁出现任何完整人物或人物形象"）。
- **坑8 · 生成超时续轮询**：`scripts/generate_video.py` 默认 `poll timeout=1200s`，30s 视频偶发耗时 >20 分钟仍 `RUNNING` → 脚本因超时而 `RuntimeError` 退出，但**阿里云 task 并未失败**。**解法**：保留 stdout 回显的 `[轮询] task_id=...`，用脚本周期性 `GET {api_base}/api/v1/tasks/{task_id}` 续轮询；`status=SUCCEEDED` 后 `extract_video_url` + `download`，**不必重提任务**。
- **补 · 本账号百炼云端 ASR 不可用**：`qwen3-asr-flash`（SDK / 兼容模式 / 原生端点，均 400）与 `paraformer-v2` 文件转写（403 "current user api does not support synchronous calls"，账号未开通）全部拒绝。**音频核对只能走本地 ASR**（funasr / faster-whisper，不外传素材），见上方"推荐流程·生成后 ASR 自查"。