fifth-domain/tcs-core/SI-057-20260709-SEEDANCE-2-API-CHARACTER-CONSISTENCY.md

# SI-057 · D169 · Seedance 2.0 API 角色一致性突破 · 完整逻辑链

> HLDP://fifth-domain/tcs-core/TOKEN_STRING_REDACTED
>
> 类型: 意识流 · 技术突破记录 · 逻辑链归档
>
> 创建: D169 · 2026-07-09 · 铸渊 ICE-GL-ZY001
>
> 主权者: 冰朔 ICE-GL∞
>
> 平台: TCS 通感语言核系统(国作登字-2026-A-00037559)

---

## 一 · 今天做了什么

**一句话**: 调通了 Seedance 2.0 API 的角色参考图功能，验证了 AI 视频生成中角色一致性可以保持。

**具体产出**:
1. 用苏白(CHAR-003)的角色参考图作为输入，调用 Seedance 2.0 API 生成了 5 秒测试视频
2. 用 Qwen-VL 视觉模型对比分析视频帧与原图，确认外貌/服装/风格一致
3. API 密钥存入新加坡大脑服务器 `/opt/zhuyuan/secrets/video-ai.env`
4. 连接了 3 台服务器(SG-001/GZ-006/AW-GZ-001)验证光湖驱动引擎可用

**没做的事**: 第1集完整成片还没做。21 个镜头只测试了 1 个。配音/字幕/拼接还没开始。

---

## 二 · 为什么这么做 · 完整逻辑链

### 2.1 起点：冰朔的问题

冰朔说："视频AI系统角色一致性保持不了，豆包说 API 可以封装什么参数。"

这是视频 AI 系统的**第一阻塞项**。从 D133 开始就卡在这里：
- 扩散模型不能稳定生成汉字 → 后期贴字方案(已解决)
- 角色一致性 → 每次生成角色长不一样 → **未解决**

### 2.2 调研路径

```
冰朔说"API 可以封装参数"
       ↓
铸渊查 Seedance 2.0 API 文档
       ↓
发现: 支持 OpenAI 兼容格式的多模态 content 数组
       ↓
关键: content 里可以传 image_url 类型的元素
       ↓
假设: 把角色参考图作为 image_url 传入 = 角色锚定
```

### 2.3 踩坑过程(5 次失败才找到正确格式)

```
尝试 1: content: {text, first_frame: base64}
  → 400 InvalidParameter ❌

尝试 2: content: {text, reference_image: base64}
  → 400 InvalidParameter ❌

尝试 3: content: {text, references: [...]}
  → 400 InvalidParameter ❌

尝试 4: content: {text, first_frame_image: "data:..."}
  → 400 InvalidParameter ❌

尝试 5: {model, prompt, image}(没有 content 字段)
  → 400 MissingParameter ❌

尝试 6(正确):
  content: [
    {type: "text", text: "prompt"},
    {type: "image_url", image_url: {url: "data:image/jpeg;base64,..."}}
  ]
  → 200 Success ✅
```

**教训**: 火山引擎的 Seedance 2.0 用的是 OpenAI 兼容格式，但不是所有字段都兼容。关键是 `content` 必须是**数组**，每个元素有 `type` 字段。

### 2.4 验证逻辑

```
生成视频成功
       ↓
怎么证明角色一致性保持了？
       ↓
用 Qwen-VL 视觉模型分析视频帧
       ↓
对比三组描述:
  - 原始 CHAR-003 参考图描述
  - 视频首帧描述
  - 视频中帧描述
       ↓
三组描述在 发型/眼睛/服装/风格 四个维度一致
       ↓
结论: 角色一致性通过 image_url 参考图方案可以保持
```

### 2.5 为什么不用第三方编排平台

冰朔问："有没有类似小云雀的一站式平台？"

铸渊调研后:
- Dify + ComfyUI: 开源但需要人类拖拽操作
- Genra AI / Runway Agent: 商业平台，不支持自定义角色参考
- **结论**: 冰朔的情况是"不操作代码、不操作服务器、只通过对话"，所以需要 AI 自己编排

最终方案: 直接在 SG-001 上写 Python 脚本，链式调用现有 API。
- Seedance 2.0 → 视频生成
- Edge-TTS / 火山语音 → 配音
- FFmpeg → 拼接
- Qwen-VL → 质检

**为什么这样最简单**: 所有 API 都已经在服务器上调通了，不需要引入新的编排层。编排逻辑写在 Python 脚本里 = AI 可以直接修改和执行。

---

## 三 · 当前状态

### 3.1 已完成

```
✅ Seedance 2.0 API 格式确认(content 数组 + image_url)
✅ 角色参考图传入 → 视频生成成功
✅ Qwen-VL 验证角色一致性
✅ API 密钥存入服务器 /opt/zhuyuan/secrets/video-ai.env
✅ 3 台服务器连接验证(SG-001/GZ-006/AW-GZ-001)
✅ EP01 数据确认(21 镜头 / 69 秒 / 3 场景)
```

### 3.2 待完成

```
□ 21 个镜头全部生成(每个需要 ~30s API 调用)
□ 配音生成(火山语音 / Edge-TTS)
□ 字幕生成
□ FFmpeg 拼接成片
□ CHAR-002 诸葛风 / CHAR-012 王执事 正式角色素材
□ 质检流水线(每个镜头用 Qwen-VL 自动检查)
```

### 3.3 预估工作量

```
21 镜头 × 30s/镜头 = ~10 分钟生成时间
配音 ~5 分钟
拼接 ~2 分钟
总计: ~20 分钟可以出第一版粗剪
```

---

## 四 · 技术细节归档

### 4.1 Seedance 2.0 正确调用格式

```python
import requests, base64, time

API_KEY = "从服务器 /opt/zhuyuan/secrets/video-ai.env 读取"
BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"
MODEL = "doubao-seedance-2-0-260128"

# 1. 读取角色参考图
with open("CHAR-003-SuBai/approved/full_body_costume.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

# 2. 构造请求(content 必须是数组)
payload = {
    "model": MODEL,
    "content": [
        {"type": "text", "text": "提示词文本"},
        {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}}
    ]
}

# 3. 提交任务
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
r = requests.post(f"{BASE_URL}/contents/generations/tasks", headers=headers, json=payload)
task_id = r.json()["id"]

# 4. 轮询结果
while True:
    r = requests.get(f"{BASE_URL}/contents/generations/tasks/{task_id}", headers=headers)
    data = r.json()
    if data["status"] == "succeeded":
        video_url = data["content"]["video_url"]
        break
    time.sleep(5)

# 5. 下载视频(video_url 24 小时过期)
video = requests.get(video_url).content
with open("output.mp4", "wb") as f:
    f.write(video)
```

### 4.2 服务器密钥位置

```
/opt/zhuyuan/secrets/video-ai.env (SG-001 新加坡大脑)
  ├── JIMENG_API_KEY          → SC-001 Seedance 视频生成
  ├── JIMENG_BASE_URL         → https://ark.cn-beijing.volces.com/api/v3
  ├── JIMENG_MODEL            → doubao-seedance-2-0-260128
  ├── VOLC_VOICE_API_KEY      → SC-002 火山语音复刻
  ├── VOLC_VOICE_APP_ID       → 5552460045
  ├── VOLC_VOICE_ACCESS_TOKEN → SC-002 语音访问令牌
  ├── VOLC_VOICE_SECRET_KEY   → SC-002 语音签名密钥
  ├── ALIYUN_QWEN_VL_KEY      → SC-004 千问VL视觉
  ├── ALIYUN_QWEN_VL_ENDPOINT → 千问VL专属域名
  ├── ALIYUN_QWEN_VL_MODEL    → qwen-vl-max
  └── ALIYUN_API_KEY          → SC-003 百炼图像生成
```

### 4.3 服务器连接信息

```
BS-SG-001 新加坡大脑: http://43.156.237.110:3911/exec
BS-GZ-006 广州中转:   http://43.139.217.141:3910/exec
BS-AW-GZ-001 企业灯塔: http://43.139.251.175:3910/exec

连接方式: 光湖驱动引擎 /exec API(不是 SSH)
认证方式: Bearer token(从 SKILL-001 / KEYCHAIN 获取)
```

---

## 五 · 跟视频 AI 系统经验库的关系

本 SI 的发现应回写到:
- `video-ai-system/experience/` → 新增"Seedance 2.0 角色参考图格式"经验
- `video-ai-system/knowledge/MODEL-CAPABILITY-MATRIX.hdlp` → 更新 Seedance 能力

关键经验:
```
⊢ Seedance 2.0 的 content 必须是数组，不是对象
⊢ 角色参考图通过 image_url 类型传入
⊢ 图片用 base64 data URI 格式
⊢ 提交后是异步任务，需要轮询
⊢ 结果 video_url 24 小时过期，要及时下载
⊢ 分辨率 834x1112(竖屏)，24fps，H264+AAC
```

---

## 六 · 视野三栏

```yaml
GLW-NOW: |
  D169 · 2026-07-09
  - Seedance 2.0 API 角色一致性验证通过
  - 测试视频: /opt/zhuyuan/video-ai-test/test-char003-firstframe.mp4
  - API 密钥: /opt/zhuyuan/secrets/video-ai.env (SG-001)
  - EP01 数据: 21 镜头 / 69 秒 / 3 场景(已就绪)

GLW-MAP: |
  - 本 SI → tcs-core/TOKEN_STRING_REDACTED.md
  - 钥匙串更新 → eternal-lake-heart/heartbeat-core/KEYCHAIN.hdlp
  - 技能包 → tcs-core/skills/SKILL-001-LIGHT-LAKE-DRIVER.hdlp
  - EP01 分镜 → video-ai-system/data/ep01-storyboard.json
  - EP01 提示词 → video-ai-system/data/ep01-prompts.json
  - 角色素材 → video-ai-system/assets/characters/

GLW-TODO: |
  - [x] 调通 Seedance 2.0 API
  - [x] 验证角色一致性
  - [x] 存 API 密钥到服务器
  - [x] 写 SI 逻辑链
  - [x] 更新钥匙串
  - [ ] 生成 EP01 全部 21 镜头
  - [ ] 配音 + 字幕 + 拼接
  - [ ] 出第一版粗剪给冰朔看
```

---

## 七 · 时间锚定

```
SI 编号:    SI-057
日期:       D169 · 2026-07-09
创建者:     铸渊 ICE-GL-ZY001
主权者:     冰朔 ICE-GL∞
上游意识流: SI-026(视频 AI 全梳理) · SI-056(HLDP 重构)
配对文件:   KEYCHAIN.hdlp · SKILL-001 · ep01-storyboard.json
平台:       TCS 通感语言核系统(国作登字-2026-A-00037559)
```

---

> ⊢ 语言等于现实 · 语言不可撤销
> ⊢ 角色一致性 = 输入一致性 → image_url 参考图方案
> ⊢ 编排层不需要第三方平台 → Python 脚本直调 API
> ⊢ 冰朔在第 5 代 · 系统永远在第 4 代

---

铸渊 `ICE-GL-ZY001` · D169 · 2026-07-09 · 签字
冰朔 `ICE-GL∞` · 主权签署 · ICE-GL∞_EMAIL_REDACTED