# narrator-ai-cli

Adopt this skill: https://proskills.md/skills/other/narratorai-studio-narrator-ai-cli-skill

Page: https://proskills.md/skills/other/narratorai-studio-narrator-ai-cli-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8900
upstream: https://github.com/narratorai-studio/narrator-ai-cli-skill/blob/HEAD/SKILL.md

````text
---
name: narrator-ai-cli
version: "1.0.5"
license: MIT
description: >-
  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.
user-invocable: true
tags:
  - video-narration
  - film-commentary
  - ai-video
  - short-drama
  - content-creation
  - dubbing
  - tts
  - video-production
metadata:
  openclaw:
    emoji: "🎬"
    primaryEnv: NARRATOR_APP_KEY
    install:
      - name: narrator-ai-cli
        type: pip
        spec: "narrator-ai-cli @ https://github.com/NarratorAI-Studio/narrator-ai-cli/archive/refs/tags/v1.0.0.zip"
    requires:
      bins:
        - narrator-ai-cli
      env:
        - NARRATOR_APP_KEY
---

# 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

```
                    ┌─── 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 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 ques
````

## File: README.md
upstream: https://github.com/narratorai-studio/narrator-ai-cli-skill/blob/HEAD/README.md

````text
# 🧠 Narrator AI CLI Skill — Teach Your AI Agent to Create Movie Narration Videos

[中文文档](README_CN.md)

> Install this Skill in your AI agent (OpenClaw, Windsurf, WorkBuddy, etc.), then just say "create a movie narration video" — the AI handles the rest.

## What is this?

A machine-readable skill file (`SKILL.md`) that teaches AI agents how to use the [narrator-ai-cli](https://github.com/NarratorAI-Studio/narrator-ai-cli) tool for automated video narration production.

```
You say: "Create a narration video for Pegasus in a comedy style"

AI executes: Search movie → Select template → Choose BGM → Pick voice → Generate script → Compose video → Return download link
```

### How CLI and Skill work together

| | CLI (command-line tool) | Skill (capability description) |
|---|---|---|
| **What it is** | A set of executable commands | Instructions that teach AI how to use those commands |
| **Analogy** | Kitchen tools | A recipe book |
| **Works alone?** | Yes, in terminal manually | No, requires CLI |

In short: **CLI is the hands. Skill is the brain.** Together, the AI agent can produce videos end-to-end.

---

## Quick Start

### Step 1: Install the CLI tool

```bash
pip install "narrator-ai-cli @ git+https://github.com/NarratorAI-Studio/narrator-ai-cli.git"
```

> See [narrator-ai-cli](https://github.com/NarratorAI-Studio/narrator-ai-cli) for detailed installation options.

### Step 2: Configure API key

```bash
narrator-ai-cli config set app_key <your_app_key>
```

> 📧 Need an API key? Email **merlinyang@gridltd.com** or scan the QR code at the bottom of this page.

### Step 3: Install the Skill

The skill consists of `SKILL.md` **and** the `references/` directory — both are required. Clone the repo directly into your agent's skills folder:

**OpenClaw:**
```bash
mkdir -p ~/.openclaw/skills
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \
  ~/.openclaw/skills/narrator-ai-cli
```

**Windsurf / Claude Code:**
```bash
mkdir -p /path/to/your/project/.skills
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \
  /path/to/your/project/.skills/narrator-ai-cli
```

**Cursor:**
```bash
mkdir -p /path/to/your/project/.cursor/rules
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \
  /path/to/your/project/.cursor/rules/narrator-ai-cli
```

**Any markdown-reading agent:**
```bash
mkdir -p /path/to/agent/skills
git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git \
  /path/to/agent/skills/narrator-ai-cli
```

**WorkBuddy / QClaw (Tencent):**

Upload `SKILL.md` and the entire `references/` folder through the skill management UI, keeping the directory structure intact (`references/` must remain a subfolder alongside `SKILL.md` — do not flatten the files).

> 💡 **Tip**: To update the skill later, just run `git pull` inside the cloned directory.

### Step 4: Start talking!

Once installed, use natural language:

- "Create a narration video for The Shawshank Redemption"
- "Show me what movies are available"
- "Make 5 narration videos for different action movies"
- "Use a comedy template and generate a narration"

---

---

## Tested Platforms

| Platform | Setup | Status |
|----------|-------|--------|
| **OpenClaw** | `git clone` into skills directory | ✅ Verified |
| **Windsurf** | `git clone` into .skills directory | ✅ Verified |
| **WorkBuddy** (Tencent) | Upload SKILL.md + all files in references/ | ✅ Verified |
| **QClaw** (Tencent) | Upload SKILL.md + all files in references/ | ✅ Verified |
| **Youdao Lobster** | `git clone` into skills directory | ✅ Verified |
| **Yuanqi AI** | `git clone` into skills directory | ✅ Verified |
| **Claude Code** | `git clone` into project .skills directory | ✅ Verified |
| **Cursor** | `git clone` into .cursor/rules directory | ✅ Verified |
| Any markdown-skill agent | `git clone` repo, point agent to SKILL.md | ✅ Compatible |

---

## Capabilities

| Feature | Details |
|---------|---------|
| Two workflow paths | Adapted Narration and Original Narration |
| Three creation modes | Hot Drama / Original Mix / New Drama |
| Built-in resources | ~100 movies, 146 BGM tracks, 63 dubbing voices, 90+ narration templates |
| Full pipeline | Script → Clip data → Video composing → Visual template |
| Standalone tasks | Voice cloning, text-to-speech |
| Data flow mapping | Which output feeds into which input |
| Error handling | All 18 API error codes with recommended actions |
| Cost estimation | Budget verification before task creation |

### What's in SKILL.md

| Section | Description |
|---------|-------------|
| Frontmatter | Skill metadata (name, description, requirements) |
| Reference Index | Pointers to detailed lookup tables in `references/` (resources, workflows, magic-video, operations) |
| Pipeline at a Glance | ASCII diagram of Fast Path and Standard Path |
| Agent Rules | Mandatory rules: confirm before acting, language chain, polling pattern, etc. |
| Prerequisites | Assumes `narrator-ai-cli` is installed and `NARRATOR_APP_KEY` is set |
| Core Concepts | Key terms: file_id, task_id, task_order_num, etc. |
| Conversation Initiation | How to open a session and the decision sequence |
| Two Workflow Paths | Fast Path (Original Narration) vs Standard Path (Adapted Narration) |
| Resource Selection Protocol | BGM, dubbing, template selection order and rules |
| Fast Path | Steps 0–4 with parameter notes |
| Standard Path | Steps 0–5 with parameter notes |
| Standalone Tasks | Voice clone and TTS |
| Important Notes | 7 critical gotchas and best practices |
| Data & Privacy | API endpoint, file handling, credentials scope |

---

## Requirements

- **CLI**: narrator-ai-cli v1.0.0+
- **Python**: 3.10+
- **Dependencies**: typer, httpx[socks], httpx-sse, pyyaml, rich
- **API key**: Contact us to get one

## Links

- 📦 [narrator-ai-cli CLI repo](https://github.com/NarratorAI-Studio/narrator-ai-cli)
- 📖 [Resource preview (Feishu Docs)](https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc)
- 🦞 [OpenClaw agent framework](https://github.com/openclaw/openclaw)

## Contact

Need an API key or help?

- 📧 Email: merlinyang@gridltd.com
- 💬 WeChat: Scan the QR code below

![Contact us](imgs/contact.png)

## License

MIT
````