AI 电影/短剧解说视频自动生成（AI 解说大师 CLI Skill）。当用户需要创建电影解说视频、短剧解说、影视二创、AI 配音旁白视频、film commentary、video narration、drama dubbing、movie narration 时触发。内置电影素材库、BGM、多语种配音、解说模板。通过 narrator-ai-cli 命令行实现：搜片→选模板→选 BGM→选配音→生成文案→合成视频的全流程自动化。CLI client for Narrator AI video narration API.

narrator ai cli — AI Video Narration CLI Skill CLI client for [Narrator AI](https://openapi.jieshuo.cn) video narration API. Designed for AI agents and developers. CLI repo : https://github.com/NarratorAI Studio/narrator ai cli Resources preview (BGM / dubbing / templates): https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc Reference Index This file covers decision flow, the common workflow, and pointers. Detailed lookups live in references/ : Topic File Resource selection (material / BGM / dubbing / templates) — list commands, response formats, field mapping references/resources.md Full workflow steps with parameter tables and JSON examples (Fast Path + Standard Path) references/workflows.md Magic Video — optional visual template step (catalog, params, language rules) references/magic video.md Polling pattern, task types, file ops, user account, error codes references/operations.md Pipeline at a Glance Agent Rules (mandatory — apply across all steps) Always: Confirm before acting. Every resource (source, BGM, dubbing, template) and every magic video submission requires explicit user approval. Never auto select, never auto submit. Source data, never invent. Construct confirmed movie json from material list fields or task search movie output. If neither yields it, ask the user — do not fabricate. Honor the language chain. The dubbing voice's language defines the writing task language param AND every magic video text param. All three must match. → references/magic video.md § Language Awareness Paginate material list to exhaustion, search programmatically. Fetch all pages until total is consumed, then grep i or python3 c on the JSON. Never trust truncated terminal display. Poll with the canonical while loop at 5 second intervals. Never use a fixed iteration for loop. → references/operations.md § Task Polling Never: Submit magic video without showing the full request body (templates + every template params value) and getting user confirmation. The cost is 30 pts/minute and irreversible. Submit Chinese default values for magic video text params when narration language is non Chinese. The defaults are hardcoded Chinese and will appear as Chinese text in a non Chinese video. Submit .task id (32 char hex) as order num . Downstream tasks want .task order num (the prefixed string like generate writing xxxxx ), not .task id . Submitting the hex returns 10001 任务关联记录数据异常 . The other look alike — .results.order info.order num ( script xxxxx ) — is also wrong; see references/operations.md § Task Query Response Shape. Auto switch paths after a failure. If a step fails, surface the error to the user and ask explicitly: retry the same path, switch to the other path, or abort. Never infer a path switch on the agent's own initiative. Prerequisites This skill assumes the narrator ai cli binary is installed and configured with a valid NARRATOR APP KEY . See [README.md](README.md) for install / setup. Agents can verify with narrator ai cli user balance . Core Concepts Concept Description file id 32 char hex string for uploaded files. Via file upload or task results task id 32 char hex string returned on task creation. Poll with task query task order num Assigned after task creation. Used as order num for downstream tasks files[] Output files in the completed task response (flat, top level array). Each entry has file id , file path , suffix . Read .files[0].file id for the next step's input learning model id Narration style model — from a pre built template (90+) or popular learning result learning srt Reference SRT file id. Mutually exclusive with learning model id Conversation Initiation ⚠️ Agent behavior — first message of a session : Before asking the user for a movie title or workflow path, proactively orient them about what the skill offers. Most users assume they need to upload their own video + SRT and don't realize a pre built material library ships with the skill. Skipping this step often results in unnecessary uploads or aborted sessions. Required opening (adapt to the conversation language): 1. Lead with the pre built material library. Mention upfront that ~100 ready to use movies are available with video + SRT already loaded — no upload needed in most cases. 2. Offer three concrete entry points (let the user pick one): "I have a specific movie in mind" → take the title, search materials first, fall back to task search movie only if not found "Show me what's available" → run material list json and present 5–8 titles spanning varied genres; offer to filter by genre on request "I'll upload my own video + SRT" → guide through file upload 3. Defer the Fast vs Standard path question until source material is confirmed. Asking both at once forces a decision the user has no context for yet. 4. Optionally share the visual resources preview link (BGM / dubbing / templates browsable visually): https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc — but only if the user wants to browse, not as a wall of links upfront. Example opening (Chinese conversation): 你好，欢迎使用 AI 解说大师。这个技能可以帮你生成电影/短剧解说视频。我这边内置了约 100 部电影素材（视频 + 字幕都是现成的），所以大多数情况你不需要自己上传任何文件。你想怎么开始？ 1. 直接告诉我片名 — 我先查内置素材库，没有再去外部搜 2. 让我列一些内置素材 — 你可以按类型挑（喜剧 / 动作 / 悬疑 / 科幻…） 3. 自己上传视频 + 字幕 — 我引导你完成上传流程 After source material is confirmed, walk the user through the decision sequence below — one question per turn, in order . Do NOT collapse multiple decisions into one message; users cannot reason about target mode before they've picked a path. Decision sequence (each step waits for explicit user confirmation): 1. Source material — covered above. 2. Workflow path — Fast (原创文案) or Standard (二创文案). See "Two Workflow Paths" below. 3. target mode — only ask if path = Fast . Choose mode 1 / 2 / 3 (see "Fast Path internal: target mode " below). If path = Standard, skip this question entirely — Standard Path has no target mode . 4. BGM → Dubbing voice → Narration template — see "Resource Selection Protocol". ⚠️ Anti pattern (do NOT do this) : Asking "① 解说模式 (纯解说/原声混剪) ② 制作路线 (快速/标准)" in the same message. 纯解说 and 原声混剪 are Fast Path internal modes (target mode 1 vs 2). They do not exist in Standard Path. Asking them alongside the path choice forces the user to make decisions in the wrong order and conflates two layers of the decision tree. Two Workflow Paths Two end to end paths produce a finished narrated video. Choose with the user before starting. Fast Path (原创文案, recommended) Standard Path (二创文案) Pipeline material → fast writing → fast clip data → video composing → magic video material → popular learning → generate writing → clip data → video composing → magic video Cost / speed Faster, cheaper Higher quality narration When to use Default unless user wants adapted style narration When user wants narration learned from a reference style \ magic video is optional; only on explicit user request. \ \ popular learning is skippable when using a pre built template (recommended). ⚠️ Path is a standalone decision — ask the user "Fast or Standard?" by itself, in its own message. Do not auto select. Do not bundle it with target mode or any other follow up question. ⚠️ Path choice is per movie, evaluated fresh each time. If the user switched paths for a previous movie in the same session (e.g. from Fast to Standard due to a failure), that choice has no bearing on the current movie. Always ask the path question anew for each new movie — do not carry over or infer the prior session's path. Fast Path internal: target mode (ask only after path=Fast is confirmed) Skip this section entirely if the user picked Standard Path — target mode only exists inside fast writing. Mode Use when Required input "1" 热门影视 (纯解说) Known movie, narration from plot only confirmed movie json ; no episodes data "2" 原声混剪 (Original Mix) Known movie + you have its SRT confirmed movie json + episodes data[{srt oss key, num}] "3" 冷门/新剧 (New Drama) Obscure/new content episodes data[{srt oss key, num}] ; confirmed movie json optional Resource Selection Protocol Before any task, gather these resources in this order, with explicit user confirmation at each step : 1. Source files (video + SRT) — from material list or via file upload 2. BGM — from bgm list 3. Dubbing voice — from dubbing list 4. Narration style template — from task narration styles Detailed list commands, response shapes, and field mappings live in references/resources.md . ⚠️ Universal rules — apply at every resource step: 1. Pre filter by context. Use the per resource filter flag where supported: bgm list search , dubbing list lang , task narration styles genre . material list does NOT accept these flags — paginate the JSON and search programmatically with grep i / python3 c . 2. Default presentation: 5–8 options with the resource ID and key descriptive fields. 3. If the user has no preference : present 3 recommendations with a one line reason for each. Still wait for confirmation. 4. Confirm one resource at a time. Do not advance until the current one is confirmed. ⚠️ Dubbing → writing language mismatch check : if the user pre specified a language value that conflicts with the chosen voice, surface the mismatch and ask before proceeding. (The general language chain rule lives in Agent Rules above.) Fast Path — High Level Flow Detailed parameter tables, all target mode cases, and full JSON examples live in references/workflows.md . Step 0 — Find source material & determine target mode : 1. List materials: narrator ai cli material list json page 1 size 100 . Search programmatically with grep i or python3 c on the JSON output — do NOT rely on the terminal display (may be truncated). Paginate ( page 2 , etc.) until exhausted if total 100 . 2. Found in materials → ask user: pure narration ( target mode=1 ) or original mix ( target mode=2 )? Construct confirmed movie json from material fields (mapping in references/resources.md ). 3. Not found, known title → task search movie "<name " json → target mode=1 (or target mode=2 if user uploads SRT). May take 60+ seconds (Gradio backend, results cached 24h). 4. Obscure / new content → target mode=3 with user's uploaded SRT. confirmed movie json optional. Step 1 — fast writing : pass learning model id , target mode , playlet name , confirmed movie json and/or episodes data , model (pricing: 纯解说文案 flash 5pts/1k chars or pro 15pts/1k chars; 原片混剪解说文案 flash 12pts/1k chars or pro 40pts/1k chars). Save task id from the creation response , then poll until top level .status=2 and save .files[0].file id from the completed task. Step 2 — fast clip data : pass task id + file id from Step 1, plus bgm , dubbing , dubbing type , and episodes data with video oss key / srt oss key / negative oss key . Poll until top level .status=2 ; read top level .task order num from the response. Step 3 — video composing : pass order num: <.task order num from Step 2 only. Poll → .results.tasks[0].video url is the finished MP4. Step 4 (optional) — magic video : only on explicit user request. See references/magic video.md . Standard Path — High Level Flow Detailed parameter tables and JSON examples live in references/workflows.md . Step 0 — Source material : same material/upload flow as Fast Path. Use video file id as video oss key and negative oss key , and srt file id as srt oss key in episodes data . Step 1 — popular learning (ski