> 以下是 Azimo 开发者文档「命令行与 MCP」的 Markdown 版本，供 AI 助手参考。
> - Azimo（https://azimo.ai）是 AI 商业视频制作服务：一段文字加几份资料，交付一条通过质检的商用视频；提供异步 REST API、Python / TypeScript SDK、命令行 azimo 和 MCP 服务。
> - Base URL：https://azimo.ai
> - 鉴权：每个 /v1 请求带 `Authorization: Bearer <API key>`（在 https://azimo.ai/console#account 创建 Key）；用 `X-Project-ID` 选择项目，省略时使用默认项目。
> - 本页地址：https://azimo.ai/developers/cli-mcp
> - 价格不公开：请联系 sales@azimo.ai。

# 命令行与 MCP

用 `azimo` 命令行在终端里做视频，或者通过 MCP 让 Claude、Cursor 等 AI 助手替你完成“上传 → 方案 → 制作 → 下载”。

## 安装

命令行、MCP 服务器和 Python SDK 都在同一个 Python 包 `vidgen-sdk` 里，需要 Python 3.9 及以上，只依赖 `requests`。

这个包还没有发布到 PyPI。公测期间请向 sales@azimo.ai 索取，然后用 pip 或 pipx 安装它所在的目录：

```bash
pipx install ./vidgen-sdk      # 或：pip install ./vidgen-sdk
azimo version
```

## 登录

先在 [https://azimo.ai/console](https://azimo.ai/console) 的 **个人中心 → API Key** 创建一把 Key，然后：

```bash
azimo login                           # 隐藏输入 Key；验证通过才保存
echo "$AZIMO_API_KEY" | azimo login   # 或者从管道读入
azimo whoami                          # 查看角色、组织和项目
```

Key 保存在 `~/.config/azimo/config.json`，只有你自己能读。也可以不登录，直接设环境变量 `AZIMO_API_KEY`。要切换项目，用 `--project` 或 `AZIMO_PROJECT`。

## 常用命令

一条视频的完整流程：

```bash
azimo playground                        # 看有哪些现成的工作流
azimo assets upload brief.pdf logo.png  # 上传资料，得到素材 ID
azimo plan --prompt "用 30 秒向食品企业采购讲清冷链配送的优势" \
  --duration 30 --ratio 9:16 --subtitles --asset 3f2a9c1b7d6e4a58
azimo create --plan 53f755f4a1b24c0e     # 确认方案后开始制作（使用余额）
azimo wait 188f86a5c3d94e21              # 等到结束
azimo download 188f86a5c3d94e21 --name all --dir ./out
```

结构化片型用 `--type` 加 `--field`，字段名用 `azimo types` 查看：

```bash
azimo plan --type product --duration 30 \
  --field product_name="普利瓦折叠旅行水壶" --field audience_role="出差的商务旅客" \
  --field usage_scenario="深夜酒店房间" --field main_benefits="可折叠；一次两杯；不漏水" \
  --field demonstration="展开、烧水、倒水、折叠" --field evidence="客户提供的规格书" \
  --field purchase_action="到官方商店搜索"
```

| 命令 | 作用 |
| --- | --- |
| `azimo playground` / `azimo types` | 现成工作流；结构化片型和字段 |
| `azimo assets upload FILE...` | 上传资料，打印素材 ID |
| `azimo plan ...` | 创建方案，不开始制作 |
| `azimo create --plan ID` | 基于方案开始制作 |
| `azimo run ...` | 创建方案，在终端里问你确认后开始制作（`--yes` 跳过询问；在脚本里不会询问） |
| `azimo status ID` / `azimo wait ID` / `azimo list` | 查看、等待、列出视频 |
| `azimo download ID --name all` | 下载成片、字幕和封面 |
| `azimo resume ID --message "..."` / `--approve-budget` | 回答 `needs_input`，或批准继续 |
| `azimo cancel ID` / `azimo balance` | 取消视频；查看余额 |

`azimo plan` 常用参数：`--prompt` 或 `--prompt-file`、`--workflow`、`--type`、`--field`、`--duration`（秒）、`--ratio`（`16:9`、`9:16`、`1:1`）、`--asset`（可重复）、`--subtitles`、`--no-music`。

每个命令都支持 `--json`，输出机器可读结果。退出码：`0` 成功，`1` 出错，`2` 用法错误，`3` `wait` 结束但视频没有完成，`4` Key 缺失或无效。

注意：`azimo create` 每次运行都会开始一次新的制作，对同一个方案运行两次会做两条视频。

## 接入 AI 助手（MCP）

有两种接法，工具完全一样：

- **本地（推荐）：** `azimo mcp` 在你的电脑上运行，可以直接上传本机文件。需要先安装上面的包。
- **远程：** `https://azimo.ai/mcp`，不用安装任何东西，用请求头 `Authorization: Bearer <API Key>` 认证。它读不到你的本机文件，上传时由助手把文件内容发过去，单个文件最多 20 MB。

### Claude Code

```bash
# 本地；如果已经 azimo login，可以省略 --env
claude mcp add --env AZIMO_API_KEY="$AZIMO_API_KEY" azimo -- azimo mcp

# 远程
claude mcp add --transport http azimo https://azimo.ai/mcp --header "Authorization: Bearer $AZIMO_API_KEY"
```

### Claude Desktop

编辑 `claude_desktop_config.json`，用本地版。如果找不到 `azimo`，把 `command` 换成 `which azimo` 输出的完整路径。

```json
{
  "mcpServers": {
    "azimo": {
      "command": "azimo",
      "args": ["mcp"],
      "env": {"AZIMO_API_KEY": "你的 API Key"}
    }
  }
}
```

### Cursor

编辑 `~/.cursor/mcp.json`。本地版写法和 Claude Desktop 相同；远程版：

```json
{
  "mcpServers": {
    "azimo": {
      "url": "https://azimo.ai/mcp",
      "headers": {"Authorization": "Bearer ${env:AZIMO_API_KEY}"}
    }
  }
}
```

接好之后直接说：“帮我给普利瓦折叠旅行水壶做一条 30 秒的产品视频。”

## 助手能做什么、不能做什么

**能做：** 列出工作流和片型字段，上传你指定的文件，创建方案，在你同意后开始制作，等待进度，给你下载链接；遇到 `needs_input` 时转达问题，在你同意后批准继续；查看余额，取消视频。

**必须先给你看方案。** 开始制作只能基于一个方案，工具要求助手先展示方案（工作流、时长、画幅）并得到你的明确同意。开始制作、批准继续和取消都标记为需要确认的操作，大多数客户端会在执行前询问你。对同一个方案重复调用，只会返回同一条视频。

**不能做：** 不能查看或报价格（价格请联系 sales@azimo.ai）；不能绕过余额和限额；本地版拒绝读取隐藏文件和目录（例如 `~/.ssh`）；远程版读不到你电脑上的文件。

## 安全建议

- 给每个客户端单独建一把 Key，泄露时只撤销这一把。
- 只想让助手查进度，就用 `viewer` 角色的 Key，它不能创建方案或开始制作。
- 不要把 Key 贴进聊天，放在环境变量或配置文件里。

## 排错

- 退出码 `4` 或 `401`：Key 缺失、错误或已撤销，重新 `azimo login`。
- `403 read-only key`：当前是 `viewer` Key，换 `editor` 或 `owner`。
- `402`：余额或额度不足。
- 方案是 `needs_input`：按 `requirements` 修改，例如 `unsupported_duration` 表示时长超出范围。
- MCP 客户端说服务器启动失败：在终端运行 `azimo mcp`，错误信息会打印在 stderr。

更多内容见 [进阶用法](https://azimo.ai/developers/advanced) 和 [API 参考](https://azimo.ai/developers/api)。