Codex + HyperFrames 做视频时，很多错误看起来像模型问题。

比如：

画面没出来。
音频没播放。
字幕不显示。
渲染失败。
预览正常但 MP4 不正常。

但排查下来，最常见原因其实是：

路径错了。

AI 视频工作流里，路径比你想的更重要。

因为会同时涉及：

对标视频。
抽帧图片。
书封面。
旁白音频。
背景音乐。
字幕 transcript。
HyperFrames composition。
渲染输出目录。

只要其中一个路径错，整条链路就会断。

1. 路径错误为什么高发

因为 Codex、HyperFrames、渲染进程、浏览器预览，不一定在同一个工作目录。

你以为路径是：

./assets/cover.png

但渲染时当前目录可能变成：

project root
composition root
temporary render dir
tool cwd

再加上 Windows 路径：

C:\Users\admin\Downloads\cover.png

在 HTML、JSON、命令行里都可能需要不同写法。

所以路径问题一定要提前规范。

2. 第一条规则：素材必须进项目目录

不要让素材散落在：

Downloads。
Desktop。
微信缓存目录。
剪映导出目录。
浏览器下载目录。
临时文件夹。

建议每条视频都建一个项目目录：

video-project/
  assets/
    cover.png
    bgm.mp3
    voice.wav
    logo.png
  transcripts/
    voice.json
    voice.srt
  frames/
    shot-001.png
    shot-002.png
  composition/
    index.html
  output/
    final.mp4

Codex 生成 HyperFrames 时，只允许引用项目内路径。

不要引用桌面上的文件。

不要引用下载目录里的文件。

不要引用聊天工具缓存里的文件。

这样后面迁移、复用、批量跑才不会崩。

3. 第二条规则：HTML 里用相对路径

HyperFrames composition 本质上经常是 HTML。

HTML 引用素材时，推荐使用相对路径：

<img src="../assets/cover.png">
<audio src="../assets/voice.wav"></audio>

不要直接写：

<img src="C:\Users\admin\Desktop\cover.png">

这类路径在浏览器、渲染器、Linux、Docker、CI 里都可能失败。

如果必须用绝对路径，也要转换成安全的 file URL。

但生产流程里更推荐：

素材复制到项目 assets。
composition 只引用项目内相对路径。

4. 第三个坑：Windows 反斜杠

Windows 路径是：

C:\Users\admin\Documents\video\assets\cover.png

但在很多场景里，反斜杠会被当成转义符。

比如 JSON 里：

"path": "C:\Users\admin\cover.png"

这里 \U 可能出问题。

更稳的写法是：

"path": "C:\\Users\\admin\\cover.png"

或者统一转成：

C:/Users/admin/cover.png

给 Codex 的要求要写清楚：

所有 Windows 路径在 JSON 中必须双反斜杠，HTML 中优先使用项目相对路径或正斜杠。

这条能省很多时间。

5. 第四个坑：中文文件名和空格

中文文件名不是一定不能用。

但在视频流水线里，建议少用。

尤其是：

《某某书》封面 最终版 1.png
旁白 音频 剪映导出.mp4
背景音乐（低音版）.mp3

这些文件名对人友好，对工具链不一定友好。

建议统一改成：

cover.png
voice_raw.mp4
voice_processed.wav
bgm.mp3
logo.png
transcript.json
final.mp4

如果要保留中文说明，可以写 metadata：

{
  "book_title": "xxx",
  "cover": "assets/cover.png"
}

文件路径尽量短、稳定、英文、无空格。

6. 第五个坑：预览能看，渲染找不到

这是 HyperFrames 常见坑。

你在 preview 里能看到图片。

但 render MP4 时失败。

原因可能是：

preview 的 cwd 和 render 的 cwd 不同。
浏览器缓存了图片。
渲染进程没有访问外部目录权限。
路径是本机绝对路径，渲染容器里不存在。
文件在临时目录，渲染时已经被清理。

解决方式：

渲染前列出所有引用文件。
检查每个文件是否存在。
把素材复制到项目 assets。
用相对路径。
render 前重新 preview。

让 Codex 做一个 manifest：

entry: composition/index.html
assets:
  - assets/cover.png
  - assets/voice_processed.wav
  - assets/bgm.mp3
  - assets/logo.png
transcripts:
  - transcripts/voice.json
output:
  - output/final.mp4

没有 manifest，不要急着 render。

7. 第六个坑：音频路径和字幕路径不同步

很多视频第一次失败，是因为：

字幕来自旧旁白。
音频来自新 TTS。
composition 引的是旧音频。
transcript 引的是另一个文件。

这类问题非常隐蔽。

因为画面能出来，字幕也能出来，但时间不对。

建议每次音频变更后，都生成一个新的版本号：

voice_v1.wav
transcript_v1.json
voice_v2.wav
transcript_v2.json

composition 中明确引用同一版本：

audio: assets/voice_v2.wav
transcript: transcripts/voice_v2.json

不要混用。

也不要用“最终版”“最终最终版”这种文件名。

8. 第七个坑：Codex 不知道素材在哪里

如果你只说：

用这个封面。
用刚才那个音频。

Codex 不一定知道“这个”和“刚才那个”对应哪个路径。

要给明确路径清单：

书封面：C:/.../assets/cover.png
旁白音频：C:/.../assets/voice_processed.wav
背景音乐：C:/.../assets/bgm.mp3
字幕 transcript：C:/.../transcripts/voice.json
输出目录：C:/.../output/

更好的是让 Codex 先复制整理：

请把所有素材复制到项目 assets 目录，并输出最终路径 manifest。
之后 HyperFrames 只能引用 manifest 里的路径。

这样能避免幻觉路径。

9. 第八个坑：把 URL 当成本地文件

有些素材来自网络。

比如：

书封面 URL。
背景图 URL。
远程音频 URL。

直接在 composition 里引用远程 URL 有风险：

网络不稳定。
跨域。
下载慢。
渲染时断网。
远程资源被替换。

更稳的做法：

先下载到 assets。
记录来源 URL。
渲染时只用本地文件。

metadata 里可以保留：

source_url
downloaded_at
local_path
license_note

这样既稳定，也方便合规检查。

10. 路径排查命令清单

让 Codex 在 render 前做这些检查：

列出 composition 中所有 src/href/url()。
检查每个相对路径解析后的绝对路径。
检查文件是否存在。
检查文件大小是否大于 0。
检查音频能否读取 duration。
检查 transcript 是否和音频版本一致。
检查 output 目录是否存在。
检查文件名是否有空格、括号、特殊符号。

给 AI 的 Prompt：

你是 HyperFrames 路径排查助手。

请在渲染前检查项目中的所有素材路径：
- HTML img/audio/video/link/script
- CSS url()
- transcript JSON/SRT
- output 目录

要求：
1. 输出每个引用路径、解析后的绝对路径、是否存在。
2. 标出 Windows 反斜杠、中文文件名、空格、远程 URL。
3. 如果 preview 和 render cwd 不一致，给出修正方案。
4. 不要直接 render，先输出路径 manifest。

11. 4SAPI 和路径有什么关系

路径错误看起来和 4SAPI 没关系。

但批量生产时，它们必须一起看。

因为一次失败的 render，前面可能已经花了模型成本：

拆视频花了一次。
写脚本花了一次。
生成代码花了一次。
审查又花了一次。
最后因为路径错渲染失败。

如果没有日志，你只知道“失败了”。

如果接入 4SAPI，这里就不只是“调用一个模型”。

它更像一个企业级API网关，把每次模型调用、每次失败阶段、每次成本消耗都串起来。

你至少能记录：

run_id
task_type
model
request_id
cost
key_group
operator
failure_stage: render_path_check
missing_file

这样后面才能复盘：

到底是模型问题。
还是路径规范问题。
还是素材管理问题。
是哪一个账号、哪一个模板、哪一个 Key 组的失败率最高。

这就是 4SAPI 在 Agent 视频工作流里的价值：

统一模型入口。
统一 Key 权限管理。
统一调用追踪。
统一成本治理。
统一失败日志。

路径检查应该尽量程序化，避免重复消耗高级模型。 如果路径校验都没过，就不要再让高级模型反复重写脚本。 先把工程问题挡在模型调用前面，预算才守得住。

12. 总结

HyperFrames 视频失败，很多时候不是模型不会做。

而是路径没管住。

常见坑是：

素材散落。
相对路径解析错误。
Windows 反斜杠。
中文文件名和空格。
preview 和 render cwd 不一致。
音频和 transcript 版本不一致。
Codex 幻觉路径。
远程 URL 不稳定。

一句话：

AI 视频生产线要先管路径，再谈批量；路径不稳定，模型越强，浪费越大。