核心用法
narrator-ai-cli 是 Narrator AI 的官方命令行客户端，专为 AI Agent 和开发者设计，实现电影/短剧解说视频的自动化生产。核心工作流分为两条路径：
快速路径（Fast Path，推荐）：fast-writing → fast-clip-data → video-composing，成本更低、速度更快，支持纯解说（mode=1）、原声混剪（mode=2）、冷门新剧（mode=3）三种模式。
标准路径（Standard Path）：popular-learning（可选，或用预置模板替代） → generate-writing → clip-data → video-composing，质量更高、可控性更强，适合深度二创。
全流程资源管理包括：预置素材库（90+电影，带视频+字幕）、146首BGM、63种配音（11种语言）、90+解说风格模板。支持文件上传、任务状态轮询、点数预估、资源校验等辅助功能。
显著优点
- 端到端自动化：单条命令链完成从文案生成到成片输出的全流程，无需人工剪辑
- 丰富资源池：93部授权电影素材、146首分类BGM、63种多语种AI音色，开箱即用
- 双路径灵活选择：Fast Path 成本低速度快（5pts/字符），Standard Path 质量高可定制（15pts/字符）
- Agent 友好设计：所有命令支持
--json机器可读输出，SSE 流式进度推送，便于自动化编排 - 预置解说模板：90+风格模板覆盖12种类型（热血动作、烧脑悬疑、爆笑喜剧等），无需训练即可使用
- 完善的资源校验：
task verify和task budget前置检查，避免任务失败和点数浪费
潜在缺点与局限性
- 商业授权依赖：预置电影素材需平台授权，用户自有素材需自行解决版权问题
- API 密钥门槛：需联系客服（微信/邮件）获取
NARRATOR_APP_KEY，非即时自助开通 - 异步任务等待：视频合成耗时较长，需轮询查询状态，无法实时返回
- search-movie 延迟：冷门影片检索依赖 Gradio 后端，可能耗时60秒以上
- 中文服务为主：API 文档、客服支持、部分资源标注以中文为主，国际化体验有限
- 点数计费制：按字符/任务消耗点数，高频使用需持续充值，无免费额度
适合人群
- 短视频创作者/MCN 机构：批量生产电影解说、短剧二创内容
- 跨境内容出海团队：利用多语种配音（英/日/韩/西/阿/泰/印尼等）快速本地化
- AI Agent 开发者：构建自动化视频生产工作流，集成到内容生产管道
- 独立制片人/小型工作室：降低解说视频制作门槛，无需专业剪辑技能
常规风险
| 风险类型 | 说明 | 缓释措施 |
|---------|------|---------|
| 版权合规 | 预置素材授权范围、用户上传内容的版权归属需明确 | 仅使用平台明确授权素材，自有素材确保版权清晰 |
| API 密钥泄露 | 密钥存储于本地 YAML，权限 0600 但仍可能被窃取 | 使用子密钥功能，定期轮换，避免硬编码 |
| 任务失败成本 | 异步任务可能因参数错误失败，已扣点数不退 | 创建前先用 `task verify` 和 `task budget` 验证 |
| 余额耗尽 | 点数不足导致任务中断，影响自动化流程 | 集成 `user balance` 检查，设置余额预警 |
| 数据隐私 | 上传视频/字幕存储于平台 OSS，存在云端滞留风险 | 敏感内容脱敏处理，任务完成后及时删除文件 |
| 供应商锁定 | 深度集成后迁移成本高，API 格式和计费体系绑定 | 封装抽象层，保留素材和模板的本地备份能力 |