narrator-ai-cli

narrator-ai-cli — AI 视频旁白 CLI 技能

Narrator AI 视频旁白 API 的 CLI 客户端。专为 AI Agent 和开发者设计。

• CLI 仓库：https://github.com/NarratorAI-Studio/narrator-ai-cli
• 资源预览（BGM / 配音 / 模板）：https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc

参考索引

本文介绍决策流程、常见工作流及相关参考。详细查询内容位于 references/：

主题	文件
资源选择（素材 / BGM / 配音 / 模板）——列表命令、响应格式、字段映射	references/resources.md
完整工作流步骤，含参数表和 JSON 示例（快速路径 + 标准路径）	references/workflows.md
Magic Video——可选的视频模板步骤（目录、参数、语言规则）	references/magic-video.md
轮询模式、任务类型、文件操作、用户账户、错误代码	references/operations.md

流程概览

                    ┌─── Fast Path (原创文案, cheaper) ───┐
                    │   fast-writing → fast-clip-data     │
  Source material ──┤              ↓                      ├──→ video-composing ──→ (magic-video)
  (material list /  │   [video-composing keys off         │   final MP4 URL       optional visual
   search-movie /   │    fast-clip-data.task_order_num]   │                        template pass
   file upload)     └─────────────────────────────────────┘
                    ┌─── Standard Path (二创文案) ────────┐
                    │   popular-learning → generate-      │
                    │   writing → clip-data               │
                    │              ↓                      │
                    │   [video-composing keys off         │
                    │    generate-writing.task_order_num] │
                    └─────────────────────────────────────┘

Agent 规则（强制——适用于所有步骤）

始终遵守：

• 操作前先确认。 每项资源（源文件、BGM、配音、模板）以及每次 magic-video 提交，都必须获得用户明确批准。切勿自动选择或自动提交。
• 使用源数据，绝不编造。 从 material list 字段或 task search-movie 输出构建 confirmed_movie_json。如果两者都无法提供该数据，请询问用户，切勿伪造。
• 遵循语言链。 配音声音的语言决定写作任务的 language 参数以及每个 magic-video 文本参数。三者必须一致。→ references/magic-video.md § 语言适配
• 将 material list 分页获取至全部加载完成，并以编程方式搜索。 获取所有页面，直到 total 条数据全部取完，再对 JSON 使用 grep -i 或 python3 -c。切勿依赖被截断的终端显示。
• 使用标准 while 循环，每隔 5 秒轮询。 切勿使用固定迭代次数的 for 循环。→ references/operations.md § 任务轮询

绝不允许：

• 未展示完整请求正文（模板及每个 template_params 值）并获得用户确认，就提交 magic-video。 费用为每分钟 30 pts，且不可撤销。
• 旁白语言非中文时，向 magic-video 文本参数提交中文默认值。 默认值是硬编码的中文，在非中文视频中会显示为中文文本。
• 将 .task_id（32 位十六进制字符串）作为 order_num 提交。 下游任务需要的是 .task_order_num（带前缀的字符串，如 generate_writing_xxxxx），而不是 .task_id。提交十六进制字符串会返回 10001 任务关联记录数据异常。另一个看起来相似的值——.results.order_info.order_num（script_xxxxx）也不正确；参见 references/operations.md § 任务查询响应结构。
• 失败后自动切换路径。 如果某个步骤失败，应向用户说明错误，并明确询问：重试相同路径、切换到另一条路径，还是中止。切勿由 Agent 自行推断并切换路径。

先决条件

此技能要求已安装 narrator-ai-cli 二进制文件，并配置有效的 NARRATOR_APP_KEY。安装和设置说明请参见 README.md。Agent 可使用 narrator-ai-cli user balance 验证配置。

核心概念

概念	描述
file_id	已上传文件的 32 位十六进制字符串。通过 file upload 或任务结果获取
task_id	创建任务时返回的 32 位十六进制字符串。使用 task query 轮询
task_order_num	创建任务后分配。作为下游任务的 order_num 使用
files[]	已完成任务响应中的输出文件（顶层的扁平数组）。每个条目包含 file_id、file_path、suffix。读取 .files[0].file_id 作为下一步的输入
learning_model_id	旁白风格模型——来自预构建模板（90+ 个）或 popular-learning 结果
learning_srt	参考 SRT 文件的 file_id。与 learning_model_id 互斥

对话开始

⚠️ Agent 行为——会话中的第一条消息：在询问用户电影片名或工作流路径之前，主动介绍这项技能能提供什么。大多数用户会以为需要上传自己的视频和 SRT，却不知道这项技能附带了预先准备好的素材库。跳过这一步往往会导致用户不必要地上传文件或中止会话。

开场必须包含以下内容（根据对话语言调整）：

1. 先介绍预先准备好的素材库。 开头就说明有约 100 部现成电影，视频和 SRT 字幕都已就绪——大多数情况下无需上传。
2. 提供三个明确的开始方式（让用户选择一个）：
   • “我心里有一部特定的电影” → 获取片名，先搜索素材；找不到时才使用 task search-movie
   • “给我看看有哪些素材” → 运行 material list --json，展示 5–8 部不同类型的电影；并表示用户可以按类型筛选
   • “我要上传自己的视频和 SRT” → 引导用户完成 file upload
3. 等确认素材来源后，再询问快速路线还是标准路线。 同时询问会让用户在还不了解情况时就被迫做决定。
4. 可选：分享可视化资源预览链接（可直观浏览 BGM / 配音 / 模板）：https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc — 但仅在用户想浏览时分享，不要一开始就丢出一堆链接。

开场示例（中文对话）：

你好，欢迎使用 AI 解说大师。这个技能可以帮你生成电影/短剧解说视频。我这边内置了约 100 部电影素材（视频 + 字幕都是现成的），所以大多数情况你不需要自己上传任何文件。

你想怎么开始？

1. 直接告诉我片名 — 我先查内置素材库，没有再去外部搜
2. 让我列一些内置素材 — 你可以按类型挑（喜剧 / 动作 / 悬疑 / 科幻…）
3. 自己上传视频 + 字幕 — 我引导你完成上传流程

确认素材来源后，按以下决策顺序引导用户——每轮只问一个问题，按顺序进行。不要把多个决定合并到一条消息中；用户在选定路线之前无法判断 target_mode。

决策顺序（每一步都要等待用户明确确认）：

1. 素材来源——见上文。
2. 工作流路径——快速（原创文案）或标准（二创文案）。参见下文的“Two Workflow Paths”。
3. target_mode——仅在路径为快速时询问。选择模式 1 / 2 / 3（参见下文的“Fast Path internal: target_mode”）。如果路径为标准，完全跳过此问题——标准路径没有 target_mode。
4. BGM → 配音音色 → 解说模板——参见“资源选择协议”。

⚠️ 反面示例（切勿这样做）： 在同一条消息中询问“① 解说模式（纯解说/原声混剪）② 制作路线（快速/标准）”。 纯解说 和 原声混剪 是快速路线的内部模式（target_mode 1 与 2）。标准路线中不存在这两种模式。把它们与路线选择一起询问，会迫使用户以错误的顺序做决定，并混淆决策树的两个层级。

两种工作流路径

两种端到端路径都能制作出完整的解说视频。开始前，请与用户确认选择哪种路径。

	快速路径（原创文案，推荐）	标准路径（二创文案）
流程	material → fast-writing → fast-clip-data → video-composing → magic-video*	material → popular-learning** → generate-writing → clip-data → video-composing → magic-video*
成本 / 速度	更快、更省钱	解说质量更高
适用场景	默认选择，除非用户想要改编风格的解说	用户想要借鉴参考风格创作解说时

* magic-video 为可选项；仅在用户明确要求时使用。 ** 使用预构建模板时，可跳过 popular-learning（推荐）。

⚠️ 路径是独立的决策——请单独发送一条消息，询问用户“快速还是标准？”。不要自动选择，也不要将此问题与 target_mode 或任何其他后续问题合并。

⚠️ 每部影片都要重新选择路径。 如果用户在同一会话中为之前的影片切换过路径（例如因故障从快速路径改为标准路径），该选择与当前影片无关。每部新影片都必须重新询问路径，不要沿用或推断之前会话中的选择。

快速路径内部选项：target_mode（仅在确认选择快速路径后询问）

如果用户选择了标准路径，请完全跳过本节——target_mode 仅适用于 fast-writing。

模式	适用场景	必需输入
"1" 热门影视 (纯解说)	已知影片，仅根据剧情撰写解说	confirmed_movie_json；不需要 episodes_data
"2" 原声混剪 (Original Mix)	已知影片，且有其 SRT	confirmed_movie_json + episodes_data[{srt_oss_key, num}]
"3" 冷门/新剧 (New Drama)	冷门或新内容	episodes_data[{srt_oss_key, num}]；confirmed_movie_json 可选

资源选择流程

开始任何任务前，都要按以下顺序收集资源，并在每一步明确征求用户确认：

1. 源文件（视频 + SRT）——通过 material list 或 file upload 获取
2. 背景音乐——通过 bgm list 获取
3. 配音——通过 dubbing list 获取
4. 解说风格模板——通过 task narration-styles 获取

详细的列表命令、响应格式和字段映射请参阅 references/resources.md。

⚠️ 通用规则——适用于每个资源步骤：

1. 根据上下文预先筛选。 在支持时使用各资源对应的筛选标志：bgm list --search、dubbing list --lang、task narration-styles --genre。material list 不支持这些标志——请对 JSON 分页，并使用 grep -i / python3 -c 进行程序化搜索。
2. 默认展示 5–8 个选项，包括资源 ID 和关键描述字段。
3. 如果用户没有偏好：提供 3 个推荐选项，每项附上一句理由。仍需等待用户确认。
4. 一次确认一个资源。 当前资源确认前，不要进入下一步。

⚠️ 配音与写作 language 不匹配检查：如果用户预先指定的 language 值与所选语音不兼容，请指出不匹配之处并在继续前询问。（通用语言链规则见上文 Agent Rules。）

快速路径 — 高层流程

详细的参数表、所有 target_mode 情况和完整 JSON 示例见 references/workflows.md。

步骤 0 — 查找素材并确定 target_mode：

1. 列出素材：narrator-ai-cli material list --json --page 1 --size 100。在 JSON 输出上使用 grep -i 或 python3 -c 进行程序化搜索——不要依赖终端显示内容（可能会被截断）。如果 total > 100，继续翻页（--page 2 等），直至查完。
2. 素材中已找到 → 询问用户：纯解说（target_mode=1）还是原片混剪（target_mode=2）？根据素材字段构造 confirmed_movie_json（映射关系见 references/resources.md）。
3. 未找到，但片名已知 → task search-movie "<name>" --json → target_mode=1（若用户上传 SRT，则为 target_mode=2）。可能需要 60 秒以上（Gradio 后端，结果缓存 24 小时）。
4. 冷门 / 新内容 → 使用用户上传的 SRT，设置 target_mode=3。confirmed_movie_json 为可选项。

步骤 1 — 快速写作：传入 learning_model_id、target_mode、playlet_name、confirmed_movie_json 和/或 episodes_data、model（定价：纯解说文案使用 flash，每千字符 5 积分；或 pro，每千字符 15 积分；原片混剪解说文案使用 flash，每千字符 12 积分；或 pro，每千字符 40 积分）。从创建响应中保存 task_id，然后轮询，直至顶层 .status=2，并从已完成的任务中保存 .files[0].file_id。

步骤 2 — 快速剪辑数据：传入步骤 1 中的 task_id 和 file_id，以及 bgm、dubbing、dubbing_type 和包含 video_oss_key / srt_oss_key / negative_oss_key 的 episodes_data。轮询，直至顶层 .status=2；从响应中读取顶层 .task_order_num。

步骤 3 — 视频合成：仅传入 order_num: <步骤 2 中的 .task_order_num>。轮询 → .results.tasks[0].video_url 即为完成的 MP4。

步骤 4（可选）— magic-video：仅在用户明确要求时使用。见 references/magic-video.md。

标准路径 — 高层流程

详细的参数表和 JSON 示例见 references/workflows.md。

步骤 0 — 素材：素材/上传流程与快速路径相同。在 episodes_data 中，将 video_file_id 用作 video_oss_key 和 negative_oss_key，将 srt_file_id 用作 srt_oss_key。

步骤 1 — popular-learning（使用预构建模板时跳过）：传入 video_srt_path、narrator_type、model_version。轮询，直到顶层 .status=2，然后解析 .results.tasks[0].task_result JSON → agent_unique_code 即为 learning_model_id。或者直接使用 task narration-styles --json 返回的预构建模板 id。

步骤 2 — generate-writing：传入 learning_model_id、playlet_name、playlet_num、episodes_data，以及另外三个必填字段 — target_platform（例如 "douyin"）、vendor_requirements（没有时填 ""）和 target_character_name（不适用时填 ""）。省略其中任一字段都会返回 10001 ... Field required。完整参数表见 references/workflows.md。保存创建响应中的 task_id。

步骤 3 — clip-data：传入 order_num（即步骤 2 轮询得到的任务记录中的顶层 .task_order_num，例如 generate_writing_xxxxx），以及 bgm、dubbing、dubbing_type。⚠️ 这与快速路径的 fast-clip-data 不同，后者接收 task_id — clip-data 接收的是 order_num。轮询，直到顶层 .status=2（这是步骤 4 的必要前提）— 但不要将 clip-data 自身的 task_order_num 用于 video-composing；步骤 4 使用的是 generate-writing 的 task_order_num。

步骤 4 — video-composing：传入 order_num + bgm + dubbing + dubbing_type（这四项都必填 — 重新传入步骤 3 中的 BGM/语音值；API 不会继承这些值，只提交 order_num 会返回 10001 查询解说工程任务结果失败）。⚠️ 标准路径使用 generate-writing 的 task_order_num（generate_writing_xxxxx），而不是 clip-data 的。clip-data 必须先达到顶层 .status=2，作为必要前提，但提交它自身的 task_order_num（generate_clip_data_xxxxx）会返回 10001 任务关联记录信息缺失。这与快速路径相反（快速路径应使用 fast-clip-data）— 参见重要说明 #4。轮询 → .results.tasks[0].video_url 是生成完成的 MP4。

步骤 5（可选）— magic-video：仅在用户明确要求时使用。参见 references/magic-video.md。

独立任务

# Voice clone — input audio_file_id, returns voice_id
narrator-ai-cli task create voice-clone --json -d '{"audio_file_id": "<file_id>"}'

# Text to speech — input voice_id + audio_text
narrator-ai-cli task create tts --json -d '{"voice_id": "<voice_id>", "audio_text": "Text to speak"}'

两者都接受可选的 clone_model（默认值：pro）。

重要说明

1. 对于 target_mode=1 和 2，必须提供 confirmed_movie_json；对于 3，此字段可选。如果在预构建素材中找到素材字段，请据此构造；否则使用 search-movie。
2. **file_id 始终来自 file list 或 material list。**切勿猜测。
3. search-movie 可能需要 60 秒以上（Gradio 后端，结果缓存 24 小时）。
4. video-composing.order_num 的路径不对称 — 应使用哪个上游任务的 task_order_num，因路径而异（字段名规则 — 使用 task_order_num，而不是十六进制的 order_num — 见上文 Agent Rules）：
   • 快速路径 → 使用 fast-clip-data 的 task_order_num（格式：fast_writing_clip_data_xxxxx）。
   • 标准路径 → 使用 generate-writing 的 task_order_num（格式：generate_writing_xxxxx）。clip-data 步骤自身的 task_order_num（generate_clip_data_xxxxx）会返回 10001 任务关联记录信息缺失。clip-data 仍必须先完成，作为必要前提 — 但 video-composing 使用的不是它的顺序号。
5. 优先使用预构建模板，而非 popular-learning。使用 task narration-styles --json 列出；在上文的资源 URL 中预览。
6. 对于较大的请求体，使用 -d @file.json，以避免 shell 引号问题。
7. 在耗时任务前使用 task verify，以便及早发现缺失/无效素材；使用 task budget 估算点数成本。

数据与隐私

• API 端点：所有请求均发送至 https://openapi.jieshuo.cn。不使用第三方服务。
• 文件上传：预签名 URL → OSS PUT → 回调。文件与你的账号绑定，不会公开。
• 凭据：NARRATOR_APP_KEY 存储在 ~/.narrator-ai/config.yaml 中。请妥善保管；不要提交。
• 范围：此技能仅负责协调 CLI；不会访问你明确作为输入传入的内容以外的文件。