# narrator-ai-cli Skill You have access to `narrator-ai-cli`, a CLI tool for the Narrator AI video narration API. Always use `--json` flag for all commands to get structured output you can parse. ## Prerequisites The CLI must be configured before use. Check with: ```bash narrator-ai-cli config show ``` If not configured, set up with: ```bash narrator-ai-cli config set app_key ``` Server defaults to `https://openapi.jieshuo.cn` — no need to configure. **Need an app_key or help with setup?** Contact us to get started: - 📧 Email: merlinyang@gridltd.com - 💬 WeChat: ![联系客服](imgs/contact.png) ## Core Rules 1. **ALWAYS use `--json`** for all commands. Parse the JSON output to extract values for next steps. 2. **NEVER fabricate data** — never guess file IDs, movie info, or voice IDs. Always query from CLI commands. 3. **ASK user to choose** when there are multiple options (pre-built vs custom, which template, which movie, etc.). 4. **Poll task status** — tasks are async. After creation, poll with `narrator-ai-cli task query --json` until `status` is `2` (success) or `3` (failed). 5. **video-composing order_num source differs by path**: - Standard Path: use `generate-writing`'s `task_order_num` (NOT clip-data's) - Fast Path: use `fast-clip-data`'s `task_order_num` 6. **dubbing list returns `id` and `type`** — pass `id` as `dubbing`, pass `type` as `dubbing_type`. They are two separate fields. 7. **negative_oss_key = video_oss_key** — always set `negative_oss_key` to the same value as `video_oss_key` in episodes_data. 8. **search-movie may take 60+ seconds** — this is normal (Gradio backend). ## Decision Points (ASK USER) Before starting any workflow, you need to help the user make the following choices. **Present the options and let the user decide. Do NOT pick for them.** ### Decision 1: Which workflow path? ASK: "请选择工作流路径：" - **二创文案**: 爆款学习 → 生成解说文案 → 生成剪辑数据 → 合成视频 → 视觉模板(可选) - Based on existing reference video style, generates adapted narration - Suitable when: user wants to recreate content based on reference material - **原创文案** (faster & cheaper): 快速文案 → 快速剪辑数据 → 合成视频 → 视觉模板(可选) - Generates original narration from movie info + narration template - Three sub-modes: 热门影视(hot drama), 原声混剪(original mix), 冷门/新剧(new drama) - Suitable when: user wants original narration, faster speed, lower cost ### Decision 2: Narration style — pre-built template or custom learning? ASK: "解说风格：使用预置模板还是自定义学习？" - **Option A: Pre-built template** (recommended, 90+ templates across 12 genres) ```bash narrator-ai-cli task narration-styles --json # or filter: narrator-ai-cli task narration-styles --genre --json ``` Show the list to user, let them pick one. The `id` field is the `learning_model_id`. - **Option B: Custom learning** (popular-learning task, Standard Path only) Requires user to provide a reference video + SRT. The output `learning_model_id` is used in generate-writing. ### Decision 3: Movie source files — pre-built material or user upload? ASK: "电影素材：使用预置素材还是自己上传的文件？" - **Option A: Pre-built materials** (93 movies ready to use) ```bash narrator-ai-cli material list --json # or search: narrator-ai-cli material list --search "" --json # or filter: narrator-ai-cli material list --genre --json ``` Show results to user. Each entry has `video_id` and `srt_id`. - Use `video_id` as `video_oss_key` AND `negative_oss_key` - Use `srt_id` as `srt_oss_key` - **Option B: User's uploaded files** ```bash narrator-ai-cli file list --json # or search: narrator-ai-cli file list --search "" --json # or transfer by link: narrator-ai-cli file transfer --link "" --json ``` User picks video and SRT files from their cloud storage. ### Decision 4: BGM — pre-built track or user upload? ASK: "背景音乐：使用预置BGM还是自己上传的音频？" - **Option A: Pre-built BGM** (146 tracks) ```bash narrator-ai-cli bgm list --json # or search: narrator-ai-cli bgm list --search "" --json ``` Show results to user. The `id` field is the `bgm` parameter value. - **Option B: User's uploaded audio** ```bash narrator-ai-cli file list --json ``` User picks an audio file. Use its `file_id` as the `bgm` parameter. ### Decision 5: Dubbing voice — which voice and language? ASK: "配音角色：请选择配音语言和角色" ```bash # First show available languages narrator-ai-cli dubbing languages --json # Then list voices for chosen language narrator-ai-cli dubbing list --lang --json # Or filter by genre recommendation narrator-ai-cli dubbing list --tag --json ``` Show results to user. From the selected voice: - `id` field → pass as `dubbing` parameter - `type` field → pass as `dubbing_type` parameter **There is no "custom upload" option for dubbing — always pick from the pre-built list.** (Users can create custom voices via `voice-clone` task separately.) ### Decision 6: Visual template (optional)? ASK: "是否需要应用视觉模板？（可选步骤）" - **Yes**: Pick a template ```bash narrator-ai-cli task templates --json ``` Show results to user, let them pick. The `name` field goes into `template_name` list. - **No**: Skip magic-video step. ## Workflow Path 1: 二创文案 ``` popular-learning(optional) -> generate-writing -> clip-data -> video-composing -> magic-video(optional) ``` ### Step 1: Get learning_model_id Based on Decision 2: ```bash # Option A: Pre-built template (recommended) narrator-ai-cli task narration-styles --json # -> user picks one -> learning_model_id = selected item's "id" # Option B: Custom learning narrator-ai-cli task create popular-learning --json -d '{ "video_srt_path": "", "video_path": "" }' # Poll until done -> extract learning_model_id from results ``` ### Step 2: Generate Writing ```bash # 2a. Search movie info (for confirmed_movie_json / story_info) narrator-ai-cli task search-movie "" --json # Show 3 results to user, let them pick one # 2b. Get source files (based on Decision 3) # Option A: narrator-ai-cli material list --search "" --json # Option B: narrator-ai-cli file list --json # -> user picks video and SRT files # 2c. Create task narrator-ai-cli task create generate-writing --json -d '{ "learning_model_id": "", "learning_srt": "", "native_video": "", "native_srt": "", "playlet_name": "", "playlet_num": "1", "target_platform": "抖音", "vendor_requirements": "", "task_count": 1, "target_character_name": "", "story_info": "", "episodes_data": [{"video_oss_key": "", "srt_oss_key": "", "negative_oss_key": "", "num": 1}] }' # Poll -> extract task_order_num and results.file_ids[0] ``` ### Step 3: Generate Clip Data ```bash # 3a. Get BGM (based on Decision 4) # Option A: narrator-ai-cli bgm list --json -> user picks -> bgm = selected "id" # Option B: narrator-ai-cli file list --json -> user picks audio -> bgm = selected "file_id" # 3b. Get dubbing voice (Decision 5) # narrator-ai-cli dubbing list --lang --json -> user picks # -> dubbing = selected "id", dubbing_type = selected "type" # 3c. Create task narrator-ai-cli task create clip-data --json -d '{ "order_num": "", "bgm": "", "dubbing": "", "dubbing_type": "" }' # Poll -> extract results.file_ids[0] ``` ### Step 4: Video Composing **IMPORTANT**: `order_num` is from step 2 (generate-writing), NOT step 3 (clip-data). ```bash narrator-ai-cli task create video-composing --json -d '{ "order_num": "", "bgm": "", "dubbing": "", "dubbing_type": "" }' # Poll -> extract video URLs from results ``` ### Step 5 (Optional): Magic Video Based on Decision 6: ```bash # Li