Narrator AI CLI Agent Skill

>- Create AI-narrated film/drama commentary videos via CLI. Two workflow paths (Original & Adapted narration), 93 movies, 146 BGM tracks, 63 dubbing voices in 11 languages, 90+ narration templates. Use when creating narration videos, film commentary, short drama dubbing, or video production.

5k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

102

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/NarratorAI-Studio/narrator-ai-cli --skill narrator-ai-cli

What comes with it

4 752 bytes besides the instruction

imgs/contact.png

The instruction itself

26 sections, as written by the author

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:

narrator-ai-cli config show

If not configured, set up with:

narrator-ai-cli config set app_key <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: [email protected]
💬 WeChat:

!联系客服

Core Rules

ALWAYS use --json for all commands. Parse the JSON output to extract values for next steps.
NEVER fabricate data — never guess file IDs, movie info, or voice IDs. Always query from CLI commands.
ASK user to choose when there are multiple options (pre-built vs custom, which template, which movie, etc.).
Poll task status — tasks are async. After creation, poll with narrator-ai-cli task query <task_id> --json until status is 2 (success) or 3 (failed).
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
dubbing list returns id and type — pass id as dubbing, pass type as dubbing_type. They are two separate fields.
negative_oss_key = video_oss_key — always set negative_oss_key to the same value as video_oss_key in episodes_data.
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)

  narrator-ai-cli task narration-styles --json
  # or filter: narrator-ai-cli task narration-styles --genre <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)

  narrator-ai-cli material list --json
  # or search: narrator-ai-cli material list --search "<movie_name>" --json
  # or filter: narrator-ai-cli material list --genre <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

  narrator-ai-cli file list --json
  # or search: narrator-ai-cli file list --search "<keyword>" --json
  # or transfer by link: narrator-ai-cli file transfer --link "<url>" --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)

  narrator-ai-cli bgm list --json
  # or search: narrator-ai-cli bgm list --search "<keyword>" --json

Show results to user. The id field is the bgm parameter value.

Option B: User's uploaded audio

  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: "配音角色：请选择配音语言和角色"

# First show available languages
narrator-ai-cli dubbing languages --json

# Then list voices for chosen language
narrator-ai-cli dubbing list --lang <language> --json

# Or filter by genre recommendation
narrator-ai-cli dubbing list --tag <genre_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

  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:

# 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": "<srt_file_id from material or file list>",
  "video_path": "<video_file_id from material or file list>"
}'
# Poll until done -> extract learning_model_id from results

Step 2: Generate Writing

# 2a. Search movie info (for confirmed_movie_json / story_info)
narrator-ai-cli task search-movie "<movie_name>" --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 "<movie_name>" --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": "<from step 1>",
  "learning_srt": "",
  "native_video": "",
  "native_srt": "",
  "playlet_name": "<movie_name>",
  "playlet_num": "1",
  "target_platform": "抖音",
  "vendor_requirements": "",
  "task_count": 1,
  "target_character_name": "<ASK user for main character name>",
  "story_info": "",
  "episodes_data": [{"video_oss_key": "<video_id>", "srt_oss_key": "<srt_id>", "negative_oss_key": "<video_id>", "num": 1}]
}'
# Poll -> extract task_order_num and results.file_ids[0]

Step 3: Generate Clip Data

# 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 <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": "<task_order_num from step 2>",
  "bgm": "<from Decision 4>",
  "dubbing": "<id from Decision 5>",
  "dubbing_type": "<type from Decision 5>"
}'
# Poll -> extract results.file_ids[0]

Step 4: Video Composing

IMPORTANT: order_num is from step 2 (generate-writing), NOT step 3 (clip-data).

narrator-ai-cli task create video-composing --json -d '{
  "order_num": "<task_order_num from step 2 (generate-writing)>",
  "bgm": "<same bgm as step 3>",
  "dubbing": "<same dubbing as step 3>",
  "dubbing_type": "<same dubbing_type as step 3>"
}'
# Poll -> extract video URLs from results

Step 5 (Optional): Magic Video

Based on Decision 6:

# List visual templates
narrator-ai-cli task templates --json
# -> user picks template name

# Apply template
narrator-ai-cli task create magic-video --json -d '{
  "task_id": "<task_id from step 4>",
  "template_name": ["<selected template name>"]
}'

Workflow Path 2: 原创文案 (faster & cheaper)

search-movie -> fast-writing -> fast-clip-data -> video-composing -> magic-video(optional)

Step 0: Prepare

# Get narration style template (Decision 2)
narrator-ai-cli task narration-styles --json
# -> user picks one -> learning_model_id

# Search movie info (required for target_mode=1)
narrator-ai-cli task search-movie "<movie_name>" --json
# -> show 3 results, user picks one -> confirmed_movie_json

Step 1: Fast Writing (原创文案)

ASK user to choose a mode:

Mode 1 - 热门影视 (Hot Drama): generates original narration from movie info. Requires confirmed_movie_json from search-movie.
Mode 2 - 原声混剪 (Original Mix): mixes original audio with narration. Requires episodes_data[{srt_oss_key, num}].
Mode 3 - 冷门/新剧 (New/Niche Drama): for lesser-known content. Requires episodes_data[{srt_oss_key, num}].

# Mode 1 example (most common):
narrator-ai-cli task create fast-writing --json -d '{
  "learning_model_id": "<from Decision 2>",
  "target_mode": "1",
  "playlet_name": "<movie_name>",
  "model": "flash",
  "language": "Chinese (中文)",
  "perspective": "third_person",
  "confirmed_movie_json": <user-selected search result>
}'

# Mode 2/3 example:
narrator-ai-cli task create fast-writing --json -d '{
  "learning_model_id": "<from Decision 2>",
  "target_mode": "2",
  "playlet_name": "<movie_name>",
  "episodes_data": [{"srt_oss_key": "<srt_file_id>", "num": 1}]
}'
# Poll -> extract task_id and results.file_ids[0]

Step 2: Fast Clip Data

# 2a. Get BGM (Decision 4)
# Option A: narrator-ai-cli bgm list --json -> user picks
# Option B: narrator-ai-cli file list --json -> user picks audio

# 2b. Get dubbing voice (Decision 5)
# narrator-ai-cli dubbing list --lang <lang> --json -> user picks

# 2c. Get source files (Decision 3)
# Option A: narrator-ai-cli material list --search "<movie_name>" --json
# Option B: narrator-ai-cli file list --json

# 2d. Create task
narrator-ai-cli task create fast-clip-data --json -d '{
  "task_id": "<task_id from step 1>",
  "file_id": "<results.file_ids[0] from step 1>",
  "bgm": "<from Decision 4>",
  "dubbing": "<id from Decision 5>",
  "dubbing_type": "<type from Decision 5>",
  "episodes_data": [{"video_oss_key": "<video_id>", "srt_oss_key": "<srt_id>", "negative_oss_key": "<video_id>", "num": 1}]
}'
# Poll -> extract task_order_num

Step 3: Video Composing

IMPORTANT: In 原创文案 path, order_num comes from fast-clip-data's task_order_num.

narrator-ai-cli task create video-composing --json -d '{
  "order_num": "<task_order_num from step 2 (fast-clip-data)>",
  "bgm": "<same bgm as step 2>",
  "dubbing": "<same dubbing as step 2>",
  "dubbing_type": "<same dubbing_type as step 2>"
}'
# Poll -> extract video URLs from results

Step 4 (Optional): Magic Video

Based on Decision 6:

narrator-ai-cli task templates --json
# -> user picks template

narrator-ai-cli task create magic-video --json -d '{
  "task_id": "<task_id from step 3>",
  "template_name": ["<selected template name>"]
}'

Standalone Tasks

# Voice Clone — clone a voice from audio sample
narrator-ai-cli task create voice-clone --json -d '{"audio_file_id": "<file_id from file list>"}'

# Text to Speech — convert text using cloned voice
narrator-ai-cli task create tts --json -d '{"voice_id": "<id>", "audio_text": "text"}'

Utility Commands

# Account
narrator-ai-cli user balance --json

# Tasks
narrator-ai-cli task list --json
narrator-ai-cli task list --status 2 --type 9 --json   # filter: status 0-4, type 1-10
narrator-ai-cli task query <task_id> --json
narrator-ai-cli task budget --json -d '{...}'           # estimate points
narrator-ai-cli task verify --json -d '{...}'           # verify materials

# Writing management
narrator-ai-cli task get-writing --task-id <id> --file-id <id> --json
narrator-ai-cli task save-writing --json -d '{"task_id":"...", "file_id":"...", "content":[{"type":"解说","text":"..."}]}'

# Files (user's uploaded files)
narrator-ai-cli file list --json
narrator-ai-cli file list --search "<keyword>" --json
narrator-ai-cli file upload ./file.mp4 --json
narrator-ai-cli file transfer --link "<url>" --json          # transfer by HTTP/Baidu/PikPak link
narrator-ai-cli file info <file_id> --json
narrator-ai-cli file download <file_id> --json
narrator-ai-cli file storage --json
narrator-ai-cli file delete <file_id> --json

# Pre-built Resources
narrator-ai-cli task narration-styles --json            # 90+ narration style templates
narrator-ai-cli task narration-styles --genre <g> --json
narrator-ai-cli material list --json                     # 93 pre-built movies (video + SRT)
narrator-ai-cli material list --genre <g> --json
narrator-ai-cli material list --search "<name>" --json
narrator-ai-cli material genres --json
narrator-ai-cli bgm list --json                          # 146 pre-built BGM tracks
narrator-ai-cli bgm list --search "<name>" --json
narrator-ai-cli dubbing list --json                      # 63 pre-built dubbing voices
narrator-ai-cli dubbing list --lang <lang> --json
narrator-ai-cli dubbing list --tag <tag> --json
narrator-ai-cli dubbing languages --json
narrator-ai-cli dubbing tags --json
narrator-ai-cli task templates --json                    # visual templates (magic-video)
narrator-ai-cli task search-movie "<name>" --json        # movie info search

# All pre-built resources can be previewed at:
# https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc

Task Status Codes

0 = init
1 = in_progress
2 = success (done, extract results)
3 = failed (check error_message_slug)
4 = cancelled

Error Codes

10001 = failed (generic)
10004 = invalid app key
10009 = insufficient balance — notify the user:

  ⚠️ 账户余额不足，请联系客服充值或获取 App Key：
  📧 Email: [email protected]

Then display: !联系客服

10010 = task not found
60000 = retryable error (retry the operation)

Other skills for the same job

different authors, same section of the catalogue

Canvas Design

by anthropics

vendor ×13

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.

Improves the quality of images, especially screenshots, by enhancing resolution, sharpness, and clarity. Perfect for preparing images for presentations, documentation, or social media posts.

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

Lightweight WSI tile extraction and preprocessing. Use for basic slide processing tissue detection, tile extraction, stain normalization for H&E images. Best for simple pipelines, dataset preparation, quick tile-based analysis. For advanced spatial proteomics, multiplexed imaging, or deep learning pipelines use pathml.

Microscopy data management platform. Access images via Python, retrieve datasets, analyze pixels, manage ROIs/annotations, batch processing, for high-content screening and microscopy workflows.

Python library for working with DICOM (Digital Imaging and Communications in Medicine) files. Use this skill when reading, writing, or modifying medical imaging data in DICOM format, extracting pixel data from medical images (CT, MRI, X-ray, ultrasound), anonymizing DICOM files, working with DICOM metadata and tags, converting DICOM images to other formats, handling compressed DICOM data, or processing medical imaging datasets. Applies to tasks involving medical image analysis, PACS systems, radiology workflows, and healthcare imaging applications.

This skill should be used when working with pre-trained transformer models for natural language processing, computer vision, audio, or multimodal tasks. Use for text generation, classification, question answering, translation, summarization, image classification, object detection, speech recognition, and fine-tuning models on custom datasets.

13k tokens

How to use it

Copy the folder

Take narratorai-studio/narrator-ai-cli-narrator-ai-cli from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.