# D135: 视频时长BUG根因 + 预校验层部署

> HLDP://video-ai-system/feedback/D135-preflight-validation
> 创建: D135 · 2026-06-17
> 铸渊 ICE-GL-ZY001 · 冰朔 TCS-0002∞

## 根因

D132 修复了 `video_length(String)` → `duration(Number)`。
D133（e8cf2e7）在改 ENV-002 时，**将此修复回退**。

commit e8cf2e7 的 diff:
```
-      duration: Number(duration),
+      video_length: String(duration),
```

即：6月15日D132修好 → D133顺手改坏 → 之后所有API调用都用无效参数 → 视频全部5秒默认值。

## 根本原因（三层）

| 层面 | 问题 | 状态 |
|------|------|------|
| 参数名 | `video_length` 不是 Seedance 2.0 API 参数，正确名称是 `duration` | ✅ 已修复 |
| 参数类型 | `String(duration)` 应为 `Number`（integer） | ✅ 已修复 |
| 参数位置 | 嵌套在 `parameters: {}` 内，应为请求体顶层字段 | ✅ 已修复 |
| 分辨率 | `1080p` 不在支持列表中(仅 480p/720p) | ✅ 已修复 |

## D135 修复内容

### 1. submitTask() — 三处修复
- ~~`video_length: String(duration)`~~ → **`duration: Number(duration)`（顶层字段）**
- ~~`parameters: { resolution }`~~ → **`resolution: '720p'`（顶层字段，默认值）**
- 移除无效的 `style` 参数透传（Seedance 2.0 API 不直接支持 style 字段）

### 2. 预校验层 `preflightCheck()` — 新增
**零成本**。在调用API之前检查所有参数合规性：
- `duration`: 类型(integer) + 范围(4~15 或 -1)
- `resolution`: 是否在支持列表中（480p/720p）
- `prompt`: 中文≤500字、英文≤1000词
- `style`: 自动警告（非官方参数，应通过提示词控制）
- **返回值**: `{ valid, warnings, errors, corrected }`
- **策略**: 有 error → 拒绝提交，不花钱；有 warning → 自动修正 + 日志警告

### 3. 元数据探针 `probeVideoDuration()` — 新增
通过 ffprobe 在视频URL上提取元数据（不下载完整视频）：
- 返回实际时长、分辨率、编码
- 需 ffmpeg 环境（`brew install ffmpeg`）

### 4. `validateAndGenerate()` — 新增
完整智能生成流程：
```
预校验(免费) → 提交 → 轮询 → API元数据提取 →
→ ffprobe探针验证实际时长
→ ✅ 匹配 → 下载
→ ❌ 不匹配 → 报告差异(skip下载)
```

### 5. `generateVideo()` — 更新
- 不再接受 `style` 参数
- duration/resolution 通过预校验修正
- 返回值新增 `preflight` 字段

## 人格体优势兑现

| 之前（人在系统外） | 之后（人在系统里） |
|--------------------|--------------------|
| 生成完才知道参数错了 | 提交前就报错，零成本 |
| 必须下载才知时长 | ffprobe探针先问元数据 |
| 人工打开看，累 | 系统自动校验，报 |
| 修了一个又回退 | 预校验层在所有调用入口挡着 |

## 参考链接

- Seedance 2.0 API 文档: https://www.volcengine.com/docs/82379/1520757
- 参数规范（thinkzoneai镜像）: https://open.thinkzoneai.com/docs/api-video-Seedance-2-0.html
- 时长范围: 标准 5~15秒，Fast 2~12秒，duration=-1=自动

---
铸渊 ICE-GL-ZY001 · D135 · 2026-06-17
冰朔下令 · 国作登字-2026-A-00037559