narrator-ai-cli — AI Video Narration CLI Skill

CLI client for Narrator AI video narration API. Designed for AI Agents and developers.

CLI Repo: https://github.com/GridLtd-ProductDev/narrator-ai-cli Resources Preview: https://ceex7z9m67.feishu.cn/wiki/WLPnwBysairenFkZDbicZOfKnbc

Installation

# From GitHub release (recommended — pinned to a specific version)
pip install "narrator-ai-cli @ https://github.com/GridLtd-ProductDev/narrator-ai-cli/archive/refs/tags/v1.0.0.zip"

# Or from GitHub latest (tracks main branch)
pip install "narrator-ai-cli @ git+https://github.com/GridLtd-ProductDev/narrator-ai-cli.git"

# Or clone + editable install
git clone https://github.com/GridLtd-ProductDev/narrator-ai-cli.git
cd narrator-ai-cli && pip install -e .

Requires Python 3.10+. Dependencies: typer, httpx[socks], httpx-sse, pyyaml, rich.

Setup

# Interactive setup (server URL + API key)
narrator-ai-cli config init

# Or set directly
narrator-ai-cli config set app_key <your_app_key>
# No API key yet? Contact support: WeChat `gezimufeng` or email [email protected]

# Verify
narrator-ai-cli config show
narrator-ai-cli user balance

Config stored at ~/.narrator-ai/config.yaml (permissions 0600). Server defaults to https://openapi.jieshuo.cn.

Environment variable overrides (take precedence over config file):

Architecture

src/narrator_ai/
├── cli.py              # Typer main entry point, 7 sub-command groups
├── client.py           # httpx client: GET/POST/DELETE/SSE/upload, auto auth via app-key header
├── config.py           # YAML config (~/.narrator-ai/config.yaml), env var override
├── output.py           # Rich table + JSON dual output (--json flag)
├── commands/
│   ├── config_cmd.py   # config init/show/set
│   ├── user.py         # balance/login/keys/create-key
│   ├── task.py         # 9 task types, create/query/list/budget/verify/search-movie/narration-styles/templates/get-writing/save-writing/save-clip
│   ├── file.py         # 3-step upload (presigned URL → OSS PUT → callback), download/list/info/storage/delete
│   ├── materials.py    # 100+ pre-built movies (--page/--size pagination; no --genre/--search, filter locally)
│   ├── bgm.py          # 146 BGM tracks (--search filter)
│   └── dubbing.py      # 63 voices, 11 languages (--lang, --tag, --search filters)
└── models/
    └── responses.py    # API response codes (SUCCESS=10000, FAILED=10001, etc.) + task status constants

Key design choices:

• All commands support --json for machine-readable output (always use when parsing programmatically)
• Request body via `-d '{"key": "val...