百炼 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 段。本技能只用"图片参考 + 音频参考"。
参考引用语法：prompt 中用 Image 1 / Image 2 / Audio 1 按 media 数组顺序引用素材。例如 media[0]=人物五视角图 → prompt 里写"Image 1 中的女性"。
不支持二次创作：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
插画参考图 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	—	—	锁死、不可被自动生成覆盖

media 数组顺序即 prompt 中 Image/Audio 编号顺序，组装时务必对应。提交的是确认后的生成物料，不是原始 4 项文件本身。

media 数组顺序即 prompt 中 Image/Audio 编号顺序，组装时务必对应。

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

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

Image 1 中的女性（即这张已确认的人物完整形象照：与图中面孔、深栗色半扎长发、斜刘海一致，
身穿[米白]美容师制服，胸牌样式与确认稿一致、不可更改），
身处 Image 2 的怡呵美门店内（墙面有怡呵美立体 LOGO，背景虚化；店内可见[门店丰富元素：
前台 / 美容床 / 沙发 / 产品陈列架，可选其他店员从画面边缘虚化走过]）。

[人物行为动线 · 按口播长短设计，全程与场景互动、不站桩]：
开场她[从走动中入画 / 端坐于面诊桌前]自然引入[主题]；讲到中段时[起身缓步走向产品架 /
从走动落座于沙发]边走边说；结尾[回到中近景、手势收束]。说话间伴随[整理产品 / 手势比划 /
轻微点头]等真实肢体动作。

[运镜组合 · 随机穿插 2–3 种]：
开场[中近景固定 / 极轻微横摇]→ 人物走动时[跟随拍摄]→ 讲到核心点时[缓慢推近]→
结尾[缓慢拉远]收束。整体[手持微晃]保留真实手机拍摄质感。

她自然亲和地讲解[主题]：
"[口语化口播全文，含自然停顿]"

[插画展示方式 · 随机使用，不固化一种]（在[插画插入点：第 N 句]处触发，对应 Image 3 / Image 4）：
- 方式示例：[全屏铺盖插画] / [画面右侧圆形画中画嵌入插画] / [顶部条状画中画展示插画] /
  [侧边圆角区域 PiP] / [人物画中画式全屏：插画铺满整屏、口播人物以圆形或正方形 PiP 出现在画面某区域]；
  同一视频多次出现插画时可轮换不同方式。
（插画为抽象皮肤结构可视化：透明表皮层、缓慢流动光点、柔和结构变化，无真人皮肤、无血液、无文字）

原生生成清晰女声普通话对白（音色参考 Audio 1）、轻微环境音、无背景音乐。
绝对禁止：字幕/任何文字/卡通化/塑料皮肤/变脸/服装漂移/场景跳变/其他清晰正脸人物抢镜。

口播全文直接写进 prompt（作为对白台词），wan3 原生生成语音并对口型。
人物行为动线按口播时长设计：≤15 秒用 1–2 个动作切换，30 秒用 3–4 个动线（走动/坐/起/落座/整理）。
运镜每条约 2–3 种按时间轴穿插，不全程单一机位；插画展示方式一场内可混用多种，不恒定为一种；门店丰富元素随机点缀 2–3 个，增加景深与真实感。
时长参数 duration=30，ratio=9:16，resolution 按 config。
反向约束（硬性禁令）也写进 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"。

wan3-workflow.md 10 KB História Raw