PixVerseAI/cli
GitHub: PixVerseAI/cli
PixVerse CLI 是 PixVerse AI 创意平台的官方命令行界面，支持在终端中通过文本或图像生成视频、图像、语音和音乐等多模态内容。
Stars: 53 | Forks: 3
# PixVerse CLI
[PixVerse](https://pixverse.ai) 的官方命令行界面 (CLI) —— 直接从您的终端创建 AI 驱动的视频、图像和音频。
## 什么是 PixVerse？
PixVerse 是一个 AI 驱动的创意平台，可以根据文本 prompt 或参考图像生成高质量的视频、图像和音频。它支持广泛的创意工作流，包括 text-to-video、image-to-video、text-to-image、视频转场、text-to-speech（语音合成）、音乐生成、模板/特效等。
## 什么是 PixVerse CLI？
PixVerse CLI 本质上是 **PixVerse 网站的无 UI 版本**。所有功能和特性与网页版体验保持一致 —— 如果您能在 [pixverse.ai](https://pixverse.ai) 上完成操作，就可以在命令行中使用相同的模型、参数和质量来完成。
它专为以下场景设计：
- **AI agent** —— 结构化的 JSON 输出、确定性的退出码以及可通过管道处理的命令，使其成为自治工作流（例如 Claude Code、Cursor、Codex、LangChain、自定义 agent）的理想工具。
- **开发者与高级用户** —— 无需离开终端即可进行可脚本化的视频/图像/音频生成。
- **自动化** —— 将 AI 内容生成集成到 CI/CD pipeline、批处理脚本或内容生产工作流中。
## 需要订阅
PixVerse CLI 使用与网站相同的 credit 系统 —— 生成视频、图像和音频会消耗您 PixVerse 账户余额中的 credit，定价保持一致。为防止滥用，**PixVerse CLI 目前仅对订阅用户开放**。有关订阅计划和会员权益的详细信息，请参阅 [PixVerse 订阅](https://app.pixverse.ai/subscribe)页面。
## 安装
```
npm install -g pixverse
```
或者无需安装直接运行：
```
npx pixverse
```
**要求：** Node.js >= 20
## 身份验证
PixVerse CLI 使用 OAuth device flow —— 无需手动复制 token：
```
pixverse auth login
```
这会打开一个浏览器供您确认授权。您也可以复制 URL 并从**任何设备上的任何浏览器**进行授权 —— 这对于 SSH 或无头环境非常有用。CLI 会自动接收 token 并将其存储在本地。
- Token 有效期为 30 天
- CLI 会话与您的网页/APP 会话相互独立
- 运行 `pixverse auth status` 检查您的登录状态和 credit
- 运行 `pixverse auth logout` 删除已存储的 token
## 支持的模型
### 视频模型 (`--model `)
| 模型 | `--model` 值 | 质量 | 时长 | 宽高比 |
|:---|:---|:---|:---|:---|
| PixVerse V6 *(默认)* | `v6` | `360p` `540p` `720p` `1080p` | `1`–`15`s | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` `21:9` |
| PixVerse C1 | `pixverse-c1` | `360p` `540p` `720p` `1080p` | `1`–`15`s | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` |
| Seedance 2.0 Standard | `seedance-2.0-standard` | `480p` `720p` `1080p` | `4`–`15`s | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9` |
| Seedance 2.0 Fast | `seedance-2.0-fast` | `480p` `720p` | `4`–`15`s | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9` |
| Happy Horse 1.0 | `happyhorse-1.0` | `720p` `1080p` | `3`–`15`s | `16:9` `9:16` `1:1` `4:3` `3:4` |
| Kling O3 Pro | `kling-o3-pro` | `720p` | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling O3 Standard | `kling-o3-standard` | `720p` | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling 3.0 Pro | `kling-3.0-pro` | `720p` | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling 3.0 Standard | `kling-3.0-standard` | `720p` | `3`–`15`s | `16:9` `9:16` `1:1` |
| Grok Imagine 1.5 | `grok-imagine-1.5` | `480p` `720p` | `1`–`15`s | *来自图像* |
| Grok Imagine | `grok-imagine` | `480p` `720p` | `1`–`15`s | `16:9` `4:3` `1:1` `9:16` `3:4` `3:2` `2:3` |
| Veo 3.1 Lite | `veo-3.1-lite` | `720p` `1080p` | `4` `6` `8`s | `16:9` `9:16` |
| Veo 3.1 Standard | `veo-3.1-standard` | `720p` `1080p` `2160p` | `4` `6` `8`s | `16:9` `9:16` |
| Veo 3.1 Fast | `veo-3.1-fast` | `720p` `1080p` `2160p` | `4` `6` `8`s | `16:9` `9:16` |
| Sora 2 Pro | `sora-2-pro` | `720p` `1080p` | `4` `8` `12`s | `16:9` `9:16` |
| Sora 2 | `sora-2` | `720p` | `4` `8` `12`s | `16:9` `9:16` |
| PixVerse v5.6 | `v5.6` | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` |
| PixVerse v5.5 | `v5.5` | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` |
| PixVerse v5 | `v5` | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` |
#### 各模式模型支持
| 创建模式 | 支持的 `--model` 值 |
|:---|:---|
| `create video` (text-to-video / image-to-video) | `v6` `pixverse-c1` `seedance-2.0-standard` `seedance-2.0-fast` `happyhorse-1.0` `kling-o3-pro` `kling-o3-standard` `kling-3.0-pro` `kling-3.0-standard` `grok-imagine-1.5` `grok-imagine` `veo-3.1-lite` `veo-3.1-standard` `veo-3.1-fast` `sora-2-pro` `sora-2` `v5.6` |
| `create extend` | `v6` `grok-imagine` |
| `create reference` (多主体融合) | `v6` `pixverse-c1` `seedance-2.0-standard` `seedance-2.0-fast` `kling-o3-pro` `kling-o3-standard` `grok-imagine` `v5.6` |
| `create transition` (2 帧) | `v6` `pixverse-c1` `seedance-2.0-standard` `seedance-2.0-fast` `kling-o3-pro` `kling-o3-standard` `kling-3.0-pro` `kling-3.0-standard` `veo-3.1-lite` `veo-3.1-standard` `veo-3.1-fast` `v5.6` |
| `create transition` (3 帧及以上) | `v5` |
| `create modify` | `v5.5` |
| `create motion-control` | `v5.6` |
### 图像模型 (`--model `)
| 模型 | `--model` 值 | 质量 | 宽高比 |
|:---|:---|:---|:---|
| GPT Image 2 *(默认)* | `gpt-image-2.0` | `1080p` `1440p` `2160p` | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` `2:1` `1:2` `21:9` |
| Nano Banana 2 | `gemini-3.1-flash` | `512p` `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` + 更多 |
| Qwen-image | `qwen-image` | `720p` `1080p` | `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` |
| Nano Banana Pro | `gemini-3.0` | `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` + 更多 |
| Nano Banana | `gemini-2.5-flash` | `1080p` | `auto` `1:1` `16:9` `9:16` + 更多 |
| Seedream 5.0 Lite | `seedream-5.0-lite` | `1440p` `1800p` `2160p` | `auto` `1:1` `16:9` `9:16` + 更多 |
| Seedream 4.5 | `seedream-4.5` | `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` + 更多 |
| Seedream 4.0 | `seedream-4.0` | `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` + 更多 |
| Kling Image O3 | `kling-image-o3` | `1080p` `1440p` `2160p` | `16:9` `9:16` `1:1` + 更多 |
| Kling Image V3 | `kling-image-v3` | `1080p` `1440p` | `16:9` `9:16` `1:1` + 更多 |
### 语音 / TTS 模型 (`create voice --model `)
| 模型 | `--model` 值 | 提供商 | 最大字符数 |
|:---|:---|:---|:---|
| MiniMax Speech 2.8 HD *(默认)* | `speech-2.8-hd` | MiniMax | 10,000 |
| MiniMax Speech 2.8 Turbo | `speech-2.8-turbo` | MiniMax | 10,000 |
| Eleven Multilingual v2 | `eleven-multilingual-v2` | ElevenLabs | 10,000 |
| Eleven v3 | `eleven-v3` | ElevenLabs | 5,000 |
| Eleven Turbo v2.5 | `eleven-turbo-v2.5` | ElevenLabs | 40,000 |
### 音乐模型 (`create --model `)
| 模型 | `--model` 值 | 提供商 | 时长 | 备注 |
|:---|:---|:---|:---|:---|
| MiniMax Music 2.6 *(默认)* | `music-2.6` | MiniMax | `10`-`240`s | 歌词、自动歌词、纯音乐 |
| ElevenLabs Music | `music_v1` | ElevenLabs | `10`-`240`s | 歌词、自动歌词、纯音乐 |
| Google Lyria 3 Pro | `lyria-3-pro-preview` | Google | `10`-`240`s | 图像参考，无需单独指定 `--lyrics` |
## 用法
### 交互模式
运行任何创建命令而不带参数即可进入交互式向导：
```
pixverse create video
pixverse create image
```
向导将逐步引导您设置 prompt、模型、质量、宽高比及其他选项。
大于 `1920x1920` 或 `5MB` 的本地图像输入会在上传前自动调整大小/压缩。远程图像 URL 由后端按原样进行验证。
### 文本生成视频
```
pixverse create video --prompt "A cat walking on Mars" --model v6 --quality 720p --aspect-ratio 16:9
```
### 文本输入：字面量、文件或 stdin
文本输入 flag —— `--prompt`（所有 create 命令）、`--text`（`create voice`）和 `--lyrics`（`create music`）—— 像对待 `--image` / `--video` 一样，接受三种形式：
- **字面量**字符串：`--prompt "A neon city skyline"`
- **本地文件路径**：`--prompt ./scene.txt`（使用文件内容）
- `-` 表示从 **stdin** 读取：`... | pixverse create video --prompt -`
```
pixverse create video --prompt ./scene.txt
cat scene.txt | pixverse create image --prompt - --json
echo "Hello from the command line" | pixverse create voice --text -
pixverse create music --prompt "Bright synth-pop" --lyrics ./lyrics.txt
```
### 图像生成视频
```
pixverse create video --prompt "Slow zoom in" --image ./photo.png
```
### 文本生成图像
```
pixverse create image --prompt "Cyberpunk cityscape at night" --aspect-ratio 16:9
```
### 图像生成图像
```
pixverse create image --prompt "Turn this into a watercolor painting" --image ./photo.png
```
### 其他创建模式
```
# 创建 keyframes 之间的过渡（需要 2+ 张图像）
pixverse create transition --images ./frame1.png ./frame2.png ./frame3.png
# 从文本生成语音音频（text-to-speech）
pixverse create voice --text "Hello world" --voice-id --output ./out.mp3
# 浏览可用的模型 / 预设声音：
pixverse voice models
pixverse voice presets --model speech-2.8-hd
# 从 prompt 生成音乐音频
pixverse create music --prompt "A cinematic pop song with bright synths" --auto-lyrics
pixverse create music --prompt "Uplifting piano theme" --instrumental --duration-seconds 60
# 支持歌词的模型需要歌词，除非使用 --auto-lyrics 或 --instrumental：
# （--lyrics 接受文字字符串、本地文件路径或 - 代表 stdin）
pixverse create music --prompt "Bright synth-pop, uplifting mood" --lyrics ./lyrics.txt
# Google Lyria 支持图像引用，并期望在 --prompt 中提供类似歌词的指令：
pixverse create music -m lyria-3-pro-preview --prompt "Instrumental orchestral cue inspired by these images" --image ./moodboard.png
# 浏览可用的音乐模型：
pixverse music models
# 延长视频时长
pixverse create extend --video
# 修改现有视频
pixverse create modify --video --prompt "Change the background to a beach"
# Upscale 视频分辨率
pixverse create upscale --video --quality 1080p
# 使用角色引用生成视频（1–7 张图像）
pixverse create reference --images ./char1.png ./char2.png --prompt "Two friends walking in a park"
# Seedance 2.0 引用 — 混合图像和视频（最多 3 个视频，总计 ≤ 15s）
pixverse create reference -m seedance-2.0-standard --images ./char.png --videos ./motion.mp4 --prompt "@image1 follows the motion in @video1"
# Motion control — 角色图像 + motion reference 视频
pixverse create motion-control --image ./character.png --video ./dance.mp4
# 从模板/效果创建
pixverse create template --template-id 12345 --image ./photo.png
```
语音速度使用特定于提供商的验证：
| 提供商 | 默认值 | 有效范围 | 无效范围错误 | 提供商请求字段 |
|:---|:---|:---|:---|:---|
| ElevenLabs | `1.0` | `0.7..1.2` | `--speed must be between 0.7 and 1.2` | `voice_settings.speed` |
| MiniMax | `1.0` | `0.5..2.0` | `--speed must be between 0.5 and 2` | `voice_setting.speed` |
### 常用创建 Flag
这些 flag 在大多数 `create` 子命令中可用：
| Flag | 描述 |
|:---|:---|
| `--count ` | 生成多个变体（1–4，默认为 1） |
| `--seed ` | 设置随机 seed 以获得可复现的结果 |
| `--off-peak` | 使用非高峰定价（消耗更少的 credit） |
| `--audio` / `--no-audio` | 启用或禁用音频生成 |
| `--multi-shot` / `--no-multi-shot` | 启用或禁用多镜头模式（仅限视频） |
| `--no-wait` | 立即返回，不等待完成 |
| `--timeout ` | 轮询超时时间（以秒为单位，默认 300） |
### 任务管理
```
# 检查任务状态
pixverse task status
# 轮询语音/音乐音频任务（音频不会自动检测 — 需传入 --type audio）
pixverse task status --type audio
# 批量状态查询（并行；每个 ID 的失败记录在响应 map 中）
pixverse task status --ids 123,456,789 --type video --json
# 等待任务完成
pixverse task wait
```
### 资产管理
```
# 列出已生成的 assets（默认：已创建的视频）
pixverse asset list
pixverse asset list --type image
pixverse asset list --type audio # voice and music audio history
pixverse asset list --type audio --source upload
pixverse asset list --source upload
pixverse asset list --source create --off-peak
# 将本地文件或 URL 上传到 asset library
pixverse asset upload ./photo.png
pixverse asset upload ./voice-over.mp3
pixverse asset upload https://example.com/image.jpg
# 获取 asset 详情（类型自动检测：video → image → audio）
pixverse asset info
# 传入 --type 以跳过自动检测
pixverse asset info --type audio
pixverse asset info --type audio --source upload
# 下载已创建的视频、图像或音频（上传的内容不可下载）
pixverse asset download
pixverse asset download --type audio --dest ./out/
# 删除已创建的 asset — 传入其 id（自动检测）
pixverse asset delete
pixverse asset delete --type audio
# 删除已上传的 asset — 传入从 `asset list --source upload` 获取的 id
pixverse asset delete --source upload --type image
```
### 保存文件夹
```
# 列出所有已保存的文件夹
pixverse saved list
# 列出文件夹中的项目（如省略则为默认文件夹）
pixverse saved items
pixverse saved items --type image --source upload
# 创建新文件夹
pixverse saved new "My Collection"
# 重命名文件夹
pixverse saved rename "New Name"
# 将 assets 添加到文件夹
pixverse saved add --folder --type video
# 从文件夹中移除 assets
pixverse saved remove --folder --type video
# 删除文件夹
pixverse saved delete
```
### 模板
```
# 列出模板分类
pixverse template categories
# 列出模板（带有可选的分类筛选器和分页功能）
pixverse template list
pixverse template list --category 5 --page 2 --limit 10
# 按关键词搜索模板
pixverse template search "dance"
# 获取模板详情
pixverse template info
```
### 工作区
```
# 列出所有 workspaces
pixverse workspace list
# 显示当前 workspace
pixverse workspace status
# 切换 workspace（交互式或通过 ID）
pixverse workspace switch
pixverse workspace switch
# 在浏览器中打开 workspace 管理
pixverse workspace manage
```
### 账户与订阅
```
# 查看账户信息和 credits
pixverse account info
pixverse account usage
# 查看当前并发生成槽位（image / video）
pixverse account slots
pixverse account slots --json
# 在浏览器中打开订阅页面
pixverse subscribe
```
### 保持 CLI 最新
```
# 更新到最新发布版本
pixverse update
```
在交互式运行时，CLI 每天最多检查一次 npm registry，并向 **stderr**（绝不向 stdout 输出，因此 `--json` 输出保持纯净）打印一行“有可用更新”通知。在 `--json`/`-p` 模式、CI 环境以及当 stdout/stderr 被管道重定向时，将跳过此检查。
### 配置
```
# 设置输出目录
pixverse config set output-dir ~/Downloads
# 查看当前配置
pixverse config list
# 显示配置文件路径
pixverse config path
# 设置各模式的创建默认值（model、quality、duration 等）
pixverse config defaults set video model v6
pixverse config defaults set video quality 1080p
pixverse config defaults show
```
## 用于脚本和 Agent 的 JSON 输出
所有命令均支持 `--json`（或 `-p`）以输出结构化 JSON，这使得 CLI 非常易于集成到自动化工作流中：
```
pixverse create video --prompt "A sunset over the ocean" --json
pixverse task wait --json
pixverse account info --json
```
### Pipeline 示例
```
# 创建视频 → 等待完成 → 下载
VID=$(pixverse create video --prompt "A cat on the moon" --json | jq -r '.video_id')
pixverse task wait "$VID" --json
pixverse asset download "$VID" --dest ./output/
```
### 退出码
| 代码 | 含义 |
|:---|:---|
| `0` | 成功 |
| `1` | 常规错误 |
| `2` | 超时 |
| `3` | 身份验证错误 |
| `4` | Credit / 订阅限制 |
| `5` | 生成失败 |
| `6` | 验证错误 |
## 所有命令
| 命令 | 描述 |
|:---|:---|
| `auth login` | 通过浏览器登录（OAuth device flow） |
| `auth status` | 检查身份验证状态 |
| `auth logout` | 移除已存储的 token |
| `create video` | text-to-video 或 image-to-video |
| `create image` | text-to-image 或 image-to-image |
| `create transition` | 在关键帧之间创建转场 |
| `create voice` | 从文本生成语音音频（text-to-speech） |
| `create music` | 从 prompt 生成音乐音频 |
| `create extend` | 延长视频时长 |
| `create modify` | 修改现有视频 |
| `create upscale` | 提升视频分辨率 |
| `create reference` | 使用角色参考生成视频 |
| `create motion-control` | 使用角色图像 + 参考视频进行运动控制 |
| `create template` | 从模板/特效创建 |
| `template categories` | 列出模板分类 |
| `template list` | 列出模板（带有分类过滤） |
| `template search` | 按关键字搜索模板 |
| `template info` | 获取模板详情 |
| `voice models` | 列出语音/TTS 提供商、模型和支持的语言 |
| `voice presets` | 列出预设语音（可按模型 / 语言 / 提供商过滤） |
| `music models` | 列出音乐提供商、模型和功能 |
| `task status` | 检查任务状态（单个 `` 或使用 `--ids id1,id2,...` 进行批量操作） |
| `task wait` | 等待任务完成 |
| `asset list` | 列出资产（`--source create\|upload`, `--type video\|image\|audio`, `--off-peak`） |
| `asset upload` | 将本地文件或 HTTPS URL 上传到资产库 |
| `asset info` | 获取资产详情 |
| `asset download` | 下载已生成的资产 |
| `asset delete` | 删除资产 |
| `saved list` | 列出已保存的文件夹 |
| `saved items` | 列出已保存文件夹中的项目 |
| `saved new` | 创建新的已保存文件夹 |
| `saved rename` | 重命名已保存的文件夹 |
| `saved add` | 将资产添加到已保存的文件夹 |
| `saved remove` | 从已保存的文件夹中移除资产 |
| `saved delete` | 删除已保存的文件夹 |
| `workspace list` | 列出所有工作区 |
| `workspace status` | 显示当前工作区 |
| `workspace switch` | 切换工作区（交互式或按 ID） |
| `workspace manage` | 在浏览器中打开工作区管理 |
| `account info` | 查看账户信息和工作区 credit |
| `account usage` | 查看 credit 使用情况 |
| `account slots` | 查看当前并发生成槽位（图像 / 视频） |
| `subscribe` | 打开订阅页面 |
| `update` | 更新 CLI 到最新版本（`npm i -g pixverse@latest`） |
| `config set` | 设置配置值 |
| `config get` | 获取配置值 |
| `config list` | 列出所有配置值 |
| `config reset` | 将配置重置为默认值 |
| `config path` | 显示配置文件路径 |
| `config defaults` | 管理各模式的创建默认值 |
## 全局 Flag
| Flag | 描述 |
|:---|:---|
| `--json` | 输出为 JSON |
| `-p` | 打印模式（`--json` 的别名） |
| `--workspace-id ` | 为此命令覆盖当前活动工作区（0 = 个人） |
| `-V, --version` | 显示 CLI 版本 |
| `-h, --help` | 显示任何命令的帮助 |
## 对于 AI Agent —— 高级用法
对于 AI agent（Claude Code、Cursor、Codex 等），我们**强烈推荐**安装 [PixVerse Skills](https://github.com/PixVerseAI/skills) —— 这是一个全面的技能库，可教导 agent 如何在完整的模型约束、多步骤 pipeline 和错误处理下正确使用 PixVerse CLI。
为了进行轻量级的发现，公开仓库还在 `capabilities.json` 中包含了一个紧凑的机器可读命令清单；npm 包在 `dist/capabilities.json` 中包含相同的文件。
**通过 Skills CLI 安装：**
```
npx skills add https://github.com/pixverseai/skills --skill pixverse-ai-image-and-video-generator
```
**或在 ClawHub 上浏览：**
[https://clawhub.ai/pixverse-official/pixverse-ai-image-and-video-generator](https://clawhub.ai/pixverse-official/pixverse-ai-image-and-video-generator)
Skills 包括：
- 各模型的参数约束（哪些模型支持哪些模式、质量级别、时长、宽高比）
- 端到端工作流 pipeline（text-to-video、故事板生成视频、视频制作、运动控制等）
- 提升生成质量的 Prompt 优化技术
- 批量创建模式和错误处理策略
## 链接
- [PixVerse 官网](https://pixverse.ai)
- [PixVerse Skills](https://github.com/PixVerseAI/skills) —— Agent 技能库
- [npm 包](https://www.npmjs.com/package/pixverse)
- [更新日志](https://github.com/PixVerseAI/cli/blob/main/CHANGELOG.md)
- [报告问题](https://github.com/PixVerseAI/cli/issues)
## 许可证
[MIT](LICENSE)
标签：AIGC, GNU通用公共许可证, MITM代理, Node.js, 人工智能, 图像生成, 文档结构分析, 暗色界面, 用户模式Hook绕过, 视频生成