Sora 故障排查

# 故障排除 ## 作业因尺寸或秒数错误而失败 - 原因：模型不支持该尺寸，或秒数不在 4/8/12 范围内。 - 修复：使尺寸与模型匹配；仅使用 "4"、"8" 或 "12" 秒（参见 `references/video-api.md`）。 - 如果看到秒数 `invalid_type` 错误，请更新 `scripts/sora.py` 或为 `--seconds` 传递字符串值。 ## 未安装 openai SDK - 原因：在没有 OpenAI SDK 的情况下运行 `python "$SORA_CLI" ...`。 - 修复：使用 `uv run --with openai python "$SORA_CLI" ...` 运行，而不是直接使用 pip。 ## uv 缓存权限错误 - 原因：在 CI 或沙盒环境中 uv 缓存目录不可写。 - 修复：在运行 `uv` 之前设置 `UV_CACHE_DIR=/tmp/uv-cache`（或其他可写路径）。 ## 提示词 Shell 转义问题 - 原因：多行提示词或引号破坏了 shell 语法。 - 修复：使用 `--prompt-file prompt.txt`（示例参见 `references/cli.md`）。 ## 提示词看起来被双重包装 ("Primary request: Use case: ...") - 原因：你手动构建了提示词，但开启了 CLI 自动增强功能。 - 修复：在传递结构化提示词文件时添加 `--no-augment`，或者使用 CLI 字段（`--use-case`, `--scene` 等）而不是预先格式化。 ## 输入参考图被拒绝 - 原因：文件不是 jpg/png/webp，或者包含人脸，或者尺寸与目标尺寸不匹配。 - 修复：转换为 jpg/png/webp，移除人脸，并调整大小以匹配 `--size`。 ## 下载失败或返回过期 URL - 原因：下载 URL 在约 1 小时后过期。 - 修复：在链接有效时重新下载；保存到你自己的存储空间。 ## 视频完成但看起来不稳定或闪烁 - 原因：多个动作或激进的摄像机运动。 - 修复：减少到一个主要动作和一个摄像机移动；保持节拍简单；添加如“避免闪烁”或“稳定运动”之类的约束。 ## 文本不可读 - 原因：文本太长、太小或在移动。 - 修复：缩短文本，增加字号，保持摄像机固定，并避免快速运动。 ## 重混 (Remix) 偏离了原始效果 - 原因：一次请求了太多更改。 - 修复：明确说明不变量（“相同的镜头和摄像机移动”），每次重混只更改一个元素。 ## 作业长时间卡在 queued/in_progress - 原因：临时的队列延迟。 - 修复：增加轮询超时时间，或稍后重试；如果你受到速率限制，请避免高并发。 ## create-and-poll 在 CI/沙盒中超时 - 原因：长时间运行的 CLI 命令可能超过 CI 时间限制。 - 修复：分别运行 `create`（捕获 ID）和 `poll`，或者设置 `--timeout`。