ViewMax CLI

可用性

viewmax-cli 尚未发布到 npm，因此 npm install -g viewmax-cli 会失败。在发布之前，请在脚本和 CI 中使用 REST API，或在 Agent 中使用 MCP 创建任务。本页记录该包提供的命令。

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

配置 API key

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

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

export VIEWMAX_API_KEY=sk-your-api-key

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

命令

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`

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：创建任务会消耗模型配置的积分。

ViewMax CLI

On this page