narrator-ai-cli 是一个用于自动创建 AI 旁白电影解说视频的 Python 命令行工具，可通过自然语言命令由 AI 智能体驱动使用。
用途
该工具旨在自动化生成 AI 旁白的电影解说视频，支持两种工作流：改编解说（Adapted Narration，使用已有电影片段，走 Fast Path）和原创解说（Original Narration，从头生成新内容，走 Standard Path）。
主要能力
- 内置资源库：约 100 部电影、146 条 BGM 音轨、63 种配音音色、90 多个模板。
- 资源查询：可列出或搜索电影、BGM、配音、模板。
- 脚本生成：可基于电影 ID 或主题生成解说脚本。
- 文件上传：上传脚本或生成的音频文件，获得 file_id。
- 视频任务：创建任务、轮询状态、下载成品视频。
- 独立操作：文本转语音（TTS）、声音克隆、任务列表查询。
- Python API：提供 NarratorClient 客户端，可直接调用 list_movies、generate_script、upload_file、create_task、get_task_status、download_file 等方法。
安装方式
通过 pip 从 GitHub 仓库安装：
pip install "narrator-ai-cli @ git+https://github.com/NarratorAI-Studio/narrator-ai-cli.git"
或克隆后本地安装：
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli.git
cd narrator-ai-cli
pip install -e .
要求 Python 3.10+，依赖 typer、httpx[socks]、httpx-sse、pyyaml、rich。
使用方式
首先配置 API key：
narrator-ai-cli config set app_key YOUR_APP_KEY
narrator-ai-cli config show
narrator-ai-cli config set proxy http://127.0.0.1:7890
配置保存在 ~/.narrator-ai-cli/config.yaml，也可使用环境变量 NARRATOR_APP_KEY。
核心概念包括 file_id（上传脚本或音频的标识）、task_id（视频生成任务标识）、task_order_num（任务进度序号）。
Fast Path（改编解说）流程：从 resources movies 选择电影 → 用 script generate --movie-id 生成脚本 → 用 file upload 上传 → 用 task create --mode hot_drama 创建任务 → 用 task status --wait 轮询完成。
Standard Path（原创解说）流程：用 script generate --topic 按主题生成脚本 → 上传 → 用 clip generate 生成片段数据 → 用 audio generate 生成音频 → 用 task create --mode original_mix 创建任务 → 轮询状态。
支持的模式包括 hot_drama（热门电影片段，需 movie_id）、original_mix（从零原创内容）、new_drama（新上映电影，需 movie_id）。
Python API 示例
from narrator_ai_cli.client import NarratorClient
from narrator_ai_cli.config import load_config
config = load_config()
client = NarratorClient(
app_key=config.get("app_key"),
proxy=config.get("proxy")
)
movies = client.list_movies()
script_response = client.generate_script(
movie_id="movie_123",
template_id="template_456"
)
upload_response = client.upload_file(
file_path="script.txt",
file_type="script"
)
task_response = client.create_task(
file_id=file_id,
movie_id="movie_123",
bgm_id="bgm_789",
dubbing_id="voice_012",
mode="hot_drama"
)
适用场景
适用于需要通过自然语言驱动的 AI 智能体来自动生成电影解说视频的场景，包括改编现有电影内容或创作原创解说，支持批量生成视频，并提供成本估算参考。
限制与注意事项
- 所有操作都需要 API key（app_key）。
- 视频生成为异步流程，通常耗时 5-15 分钟，必须轮询任务状态。
- file_id 是必需项，无法跳过上传步骤。
- BGM 和配音 ID 必须存在，需先用 resources 命令验证。
- 模式决定所需参数：hot_drama 需要 movie_id，original_mix 需要 clip_data。
- 脚本不会自动保存，上传前需显式保存到文件。
- 批量操作前应先与用户确认。
- 文档中提供了错误码说明（如 40001、40301、50001、50003）及相应处理建议。
- 文档中提供了成本估算的参考数值（基于 token，非实际收费价格）。
参考文件位于 references/ 目录，包括 resources.md、workflows.md、magic-video.md、operations.md。