# ViewMax CLI

viewmax 视频生成命令行客户端参考。该包尚未发布到 npm。

## 可用性

`viewmax-cli` 尚未发布到 npm，因此 `npm install -g viewmax-cli` 会失败。在发布之前，请在脚本和 CI 中使用 [REST API](https://viewmax.studio/zh/docs/api)，或在 Agent 中使用 [MCP](https://viewmax.studio/zh/docs/mcp) 创建任务。本页记录该包提供的命令。

CLI 需要 Node.js 20 或更高版本，且没有运行时依赖。它只支持视频；图片、音乐和音频请使用 REST API 或 MCP。

## 配置 API key

```bash
viewmax config set-key sk-your-api-key
```

命令会以 600 文件权限把 key 保存到 `~/.config/viewmax/config.json`。key 必须以 `sk-` 开头。单个 shell 或 CI 中可改用环境变量：

```bash
export VIEWMAX_API_KEY=sk-your-api-key
```

对需要认证的命令，CLI 按 `--api-key`、`VIEWMAX_API_KEY`、保存的配置的顺序查找凭证。`viewmax models` 是公开命令，不会发送 key。

## 命令

```bash
viewmax config set-key <sk-...> [--json]
viewmax models [--json]
viewmax credits [--json]
viewmax generate -m <model> -p <prompt> [options]
viewmax task <task_id> [--wait] [--output file] [--json]
viewmax help
```

### `models`

列出公开视频模型目录（`GET /api/v1/models`），每个模型一行：`id  label — vendor (credits)`。加上 `--json` 可获得完整目录，包括各模式的时长、分辨率、宽高比、`defaults` 和积分价格。

### `credits`

输出已认证账户的剩余积分。

### `generate`

```bash
viewmax generate -m viewmax-c1 -p "A paper kite crossing a bright summer sky" \
  --duration 5s --resolution 768P --aspect-ratio 16:9 \
  --idempotency-key kite-demo-001 --wait --output kite.mp4
```

该任务消耗 10 积分（ViewMax C1 按每秒 2 积分计费）。

| 选项                        | 含义                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `-m`, `--model`             | 必填模型 ID                                                                                                         |
| `-p`, `--prompt`            | 必填提示词                                                                                                          |
| `--mode`                    | 视频模式，例如 `text-to-video` 或 `image-to-video`。CLI 无法发送 `video_urls`                                       |
| `--image <url>`             | 公开的源图片 URL；可重复传入多张。省略 `--mode` 时设为 `image-to-video`                                             |
| `--duration <duration>`     | 模型列出的时长，例如 `5s`；省略时使用该模式的默认值                                                                 |
| `--resolution <resolution>` | 模型列出的分辨率，例如 `768P`                                                                                       |
| `--aspect-ratio <ratio>`    | 模型列出的宽高比，例如 `16:9`                                                                                       |
| `--audio`                   | 请求音频；仅适用于 `audio_toggle` 为 `true` 的模式                                                                  |
| `--idempotency-key <key>`   | 作为 `Idempotency-Key` 请求头发送（1–200 个可见 ASCII 字符，不含空格）。用同一个 key 重跑会返回原任务，不会再次扣费 |
| `--wait`                    | 每 5 秒轮询，最长 10 分钟                                                                                           |
| `--output <file>`           | 等待任务完成后，把第一个 `taskUrls` 结果下载到文件（隐含 `--wait`）                                                 |

不带 `--wait` 或 `--output` 时，`generate` 输出 `Created task <id>: <status> (<credits> credits)`。人类可读输出不打印结果 URL；请使用 `--json` 读取 `taskUrls`，或使用 `--output`。

### `task`

按 ID 查询任务。使用 `--wait` 轮询，使用 `--output` 下载第一个结果。任务以 `failed` 或 `canceled` 结束时，CLI 会打印 `taskInfo.errorMessage` 中的原因并以 `1` 退出；积分会自动退回。

## 通用选项、输出与退出码

`--base-url <url>` 覆盖默认的 `https://viewmax.studio`，可用于测试环境。`--api-key <key>` 覆盖环境变量和保存的 key。`--json` 向 stdout 输出裸 JSON：成功时为 `data`，失败时为 API 错误信封 `{ code, message, error }`。

| 退出码 | 含义                                                            |
| ------ | --------------------------------------------------------------- |
| `0`    | 成功                                                            |
| `1`    | API 错误、任务 `failed` 或 `canceled`、下载失败或 `--wait` 超时 |
| `2`    | 用法无效，包括未知选项、缺少 `-m`/`-p` 或没有 API key           |

`--wait` 超时后任务仍在运行；可用 `viewmax task <task_id> --wait` 继续等待。生成前请先查看 `viewmax models --json`：创建任务会消耗模型配置的积分。