百炼 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 锚定：

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

六、调用脚本

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

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 素材时不可行）；③ C 方案根治：本账号百炼 CosyVoice API 已验证可用（返回参数错而非权限拒绝，克隆路径可走）——走"不传 reference_audio 提交 wan3 出静音成片 + 克隆用户音色合成正确发音配音 + ffmpeg 二次合成 + 对口型（lipsync）"。
坑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 自查"。

wan3-workflow.md 19 KB Histórico Em bruto