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

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"。