🎬 Narrator AI CLI — Create Movie Narration Videos with Natural Language

One command to install, one sentence to create videos. 93 built-in movies, 146 BGM tracks, 63 dubbing voices, 90+ narration templates — ready out of the box.

What is this?

Narrator AI CLI is the command-line tool for Narrator AI, an AI-powered video narration platform. Once installed in your AI agent (OpenClaw, Windsurf, WorkBuddy, etc.), just say:

"Create a movie narration video for Pegasus in a comedy style"

The AI handles everything automatically:

Select movie → Match narration style → Generate script → Compose video → Output download link

No manual steps required. The AI completes the entire pipeline for you.

What it can do

✅ Movie narration videos: Input a movie name, get a complete narration video (script + voiceover + footage + BGM)
✅ Multiple narration styles: Action, Comedy, Thriller and more — 12 genres, 90+ templates
✅ Multi-language voiceover: 11 languages including English, Mandarin, Japanese, and 63 voice characters
✅ Batch production: Tell the AI "make 10 narration videos" and it will process them one by one
✅ Run unattended: Let the agent work while you sleep

Quick Start

Step 1: Install the CLI

Prerequisites: Python 3.10+ (check "Add to PATH"), Git

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/jieshuo-ai/narrator-ai-cli/main/install.py | python3

Windows (CMD / PowerShell)

python -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/jieshuo-ai/narrator-ai-cli/main/install.py').read())"

Verify:

narrator-ai-cli --version

Step 2: Get an API Key

📧 Email [email protected] or scan the QR code below to get your API key.

Step 3: Configure

narrator-ai-cli config set app_key your_api_key

Step 4: Start creating videos!

If using with an AI agent (OpenClaw, etc.), just use natural language:

"Create a narration video for The Shawshank Redemption with an inspirational style"

For terminal usage, see Command Reference below.

Using with AI Agents (Recommended)

This tool works best with AI agents. Install the Skill so the agent knows how to use these commands.

👉 Install the Skill: narrator-ai-cli-skill

Tested Platforms

Platform	Setup	Experience
Windsurf	CLI repo only	⭐⭐⭐⭐⭐ Auto-understands
WorkBuddy (Tencent)	CLI + Skill repos	⭐⭐⭐⭐⭐ Smooth
Youdao Lobster	CLI + Skill repos	⭐⭐⭐⭐ Reliable
QClaw (Tencent)	CLI + Skill repos	⭐⭐⭐⭐ Reliable
Yuanqi AI	CLI + Skill repos	⭐⭐⭐ Functional

💡 Note: Most domestic Chinese AI agents require both CLI and Skill repo URLs. Windsurf can work with just the CLI repo.

Built-in Resources

No uploads needed — all of these are ready to use:

Resource	Count	Command
🎬 Movie materials	93 movies	`narrator-ai-cli material list`
🎵 Background music	146 tracks	`narrator-ai-cli bgm list`
🎙️ Dubbing voices	63 voices (11 languages)	`narrator-ai-cli dubbing list`
📝 Narration templates	90+ (12 genres)	`narrator-ai-cli task narration-styles`

🔗 Preview all resources: Feishu Docs

Two Workflow Paths

Original Narration (Recommended — faster & cheaper)

Search movie → Fast writing → Fast clip data → Video composing → Magic video (optional)

3 modes:

Hot Drama: Well-known movies with full info available
Original Mix: Mix original audio with narration
New Drama: Short dramas or movies without full info

Adapted Narration

Popular learning → Generate writing → Clip data → Video composing → Magic video (optional)

Command Reference

Config

Command	Description
`config init`	Interactive setup (server URL + API key)
`config show`	Show current config (key masked)
`config set <key> <value>`	Set a config value

User

Command	Description
`user balance`	Query account balance
`user login`	Login with username/password
`user keys`	List sub API keys
`user create-key`	Create a sub API key

Task

Command	Description
`task types`	List task types (`-V` for details)
`task create <type> -d '{...}'`	Create a task
`task query <task_id>`	Query task status and results
`task list`	List tasks with filters
`task budget -d '{...}'`	Estimate credits consumption
`task verify -d '{...}'`	Verify materials before creation
`task search-movie "<name>"`	Search movie info
`task narration-styles`	List narration templates (90+)
`task templates`	List visual templates for magic-video
`task get-writing`	Retrieve generated script
`task save-writing -d '{...}'`	Save modified script
`task save-clip -d '{...}'`	Save modified clip data

Task Types:

Type	Workflow Position
`popular-learning`	Adapted Narration Step 1
`generate-writing`	Adapted Narration Step 2
`fast-writing`	Original Narration Step 1
`clip-data`	Adapted Narration Step 3
`fast-clip-data`	Original Narration Step 2
`video-composing`	Video composing (both paths)
`magic-video`	Optional final step (visual template)
`voice-clone`	Standalone
`tts`	Standalone

File

Command	Description
`file upload <path>`	Upload file (returns file_id)
`file transfer --link <url>`	Transfer remote file by link (HTTP / Baidu Netdisk / PikPak)
`file list`	List uploaded files
`file info <file_id>`	Get file details
`file download <file_id>`	Get presigned download URL
`file storage`	Show storage usage (3GB limit)
`file delete <file_id>`	Delete a file

Materials / BGM / Dubbing

Command	Description
`material list`	List 93 pre-built movies (`--genre`, `--search`)
`material genres`	List movie genres with counts
`bgm list`	List 146 BGM tracks (`--search`)
`dubbing list`	List 63 voices (`--lang`, `--tag`, `--search`)
`dubbing languages`	List supported languages
`dubbing tags`	List genre recommendation tags

Data Flow

                     file upload / file list / material list
                     -> video_file_id, srt_file_id
                     bgm list -> bgm_id
                     dubbing list -> dubbing, dubbing_type

    Adapted Narration                    Original Narration (faster)
    ─────────────────                    ────────────────────────────
    popular-learning (optional)          search-movie
    OUT: learning_model_id               OUT: confirmed_movie_json
      OR use pre-built template                  │
              │                          fast-writing (3 modes)
              ▼                          IN:  learning_model_id + movie_json
    generate-writing                     OUT: task_id, file_ids[0]
    IN:  learning_model_id, episodes              │
    OUT: task_order_num, file_ids[0]     fast-clip-data
              │                          IN:  task_id, file_id, episodes
              ▼                          OUT: task_order_num
    clip-data                                     │
    IN:  order_num, bgm, dubbing                  │
    OUT: file_ids[0]                              │
              │                                   │
              ▼                                   ▼
         video-composing
         IN:  order_num (from writing step), bgm, dubbing
         OUT: task_id, video URLs
                    │
                    ▼
         magic-video (optional)
         IN:  task_id or file_id + template_name
         OUT: rendered video URLs

JSON Output

All commands support --json for structured output (recommended for AI agents):

narrator-ai-cli task list --json
narrator-ai-cli task query <task_id> --json

Environment Variables

Variable	Description
`NARRATOR_SERVER`	API server URL
`NARRATOR_APP_KEY`	API key
`NARRATOR_TIMEOUT`	Timeout in seconds (default: 30)

AI Agent Integration

See narrator-ai-cli-skill for the complete SKILL.md that teaches AI agents how to use this tool automatically.

Contact

Need an API key or help? Reach out:

📧 Email: [email protected]
💬 WeChat: Scan the QR code below