pixverse-ai-image-and-video-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PixVerse CLI — Master Skill

PixVerse CLI — 核心使用指南

What is PixVerse CLI

什么是PixVerse CLI

PixVerse CLI is the official command-line interface for PixVerse — an AI-powered creative platform for generating videos and images. It is essentially a UI-free version of the PixVerse website: all features, models, and parameters are aligned with the web experience at app.pixverse.ai.

It is designed for:

AI agents (primary) — structured JSON output, deterministic exit codes, and pipeable commands for autonomous workflows (Claude Code, Cursor, Codex, custom agents)
Developers & power users — scriptable video/image generation without leaving the terminal
Automation — batch processing, CI/CD pipelines, content production workflows

Key facts:

Generating content consumes credits from the user's PixVerse account (same pricing as the website)
Only subscribed users can use the CLI — see subscription plans
All output can be returned as structured JSON via
```
--json
```
flag
English only

PixVerse CLI是PixVerse的官方命令行界面——一个基于AI的创意平台，用于生成视频和图片。它本质上是PixVerse网站的无UI版本：所有功能、模型和参数都与app.pixverse.ai的网页体验保持一致。

它专为以下用户设计：

AI Agent（主要用户）——结构化JSON输出、确定的退出码和可管道化的命令，适用于自主工作流（Claude Code、Cursor、Codex、自定义Agent）
开发者与高级用户——无需离开终端即可通过脚本生成视频/图片
自动化场景——批量处理、CI/CD流水线、内容生产工作流

关键说明：

生成内容会消耗用户PixVerse账户中的点数（定价与网站一致）
仅订阅用户可使用该CLI——查看订阅方案
所有输出可通过
```
--json
```
标志返回为结构化JSON
仅支持英文

Installation

安装

bash

npm install -g pixverse

Or run without installing:

bash

npx pixverse

Verify:

bash

pixverse --version

Requires Node.js >= 20.

bash

npm install -g pixverse

或者无需安装直接运行：

bash

npx pixverse

验证安装：

bash

pixverse --version

要求Node.js版本 >= 20。

Quick Start

快速开始

bash

undefined

bash

undefined

1. Install

1. 安装

npm install -g pixverse

2. Authenticate (OAuth device flow — opens browser)

2. 认证（OAuth设备流 — 会打开浏览器）

pixverse auth login --json

3. Create a video (waits for completion by default)

3. 创建视频（默认等待生成完成）

RESULT=$(pixverse create video --prompt "A cat astronaut floating in space" --json) VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')

4. Download the result

4. 下载生成结果

pixverse asset download $VIDEO_ID --json


To skip waiting and poll later:
```bash
RESULT=$(pixverse create video --prompt "A cat astronaut floating in space" --no-wait --json)
VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')
pixverse task wait $VIDEO_ID --json
pixverse asset download $VIDEO_ID --json

pixverse asset download $VIDEO_ID --json


若要跳过等待，后续再轮询状态：
```bash
RESULT=$(pixverse create video --prompt "A cat astronaut floating in space" --no-wait --json)
VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')
pixverse task wait $VIDEO_ID --json
pixverse asset download $VIDEO_ID --json

Authentication

认证

PixVerse CLI uses OAuth device flow — no need to manually copy tokens:

Run
```
pixverse auth login --json
```
The CLI prints an authorization URL
Open the URL in your browser and authorize
The token is stored automatically in
```
~/.pixverse/
```

Details:

Token is valid for 30 days
CLI sessions are independent from your web/app sessions
If token expires (exit code 3), re-run
```
pixverse auth login --json
```
Set
```
PIXVERSE_TOKEN
```
environment variable to override the stored token
Run
```
pixverse auth status --json
```
to check login state and credits

PixVerse CLI采用OAuth设备流——无需手动复制令牌：

运行
```
pixverse auth login --json
```
CLI会打印一个授权URL
在浏览器中打开该URL并完成授权
令牌会自动存储在
```
~/.pixverse/
```
目录中

详细说明：

令牌有效期为30天
CLI会话与网页/应用会话相互独立
若令牌过期（退出码3），重新运行
```
pixverse auth login --json
```
设置环境变量
```
PIXVERSE_TOKEN
```
可覆盖存储的令牌
运行
```
pixverse auth status --json
```
可查看登录状态和剩余点数

Capabilities Overview

功能概览

I want to...	Use skill
Create a video from text or image	`pixverse:create-video`
Create or edit an image	`pixverse:create-and-edit-image`
Extend, upscale, or add audio to a video	`pixverse:post-process-video`
Create transition animation between frames	`pixverse:transition`
Check generation progress	`pixverse:task-management`
Browse, download, or delete assets	`pixverse:asset-management`
Set up auth or check account	`pixverse:auth-and-account`
Browse and create from effect templates	`pixverse:template`

Looking up models or parameters? Don't wait until you're generating — read the relevant capabilities file directly:
Video models & constraints →
skills/capabilities/create-video.md
(Model Reference section)
Image models & constraints →
skills/capabilities/create-and-edit-image.md
(Model Reference section)

我想要...	使用对应技能
从文本或图片创建视频	`pixverse:create-video`
创建或编辑图片	`pixverse:create-and-edit-image`
扩展视频时长、提升分辨率或为视频添加音频	`pixverse:post-process-video`
在帧之间创建转场动画	`pixverse:transition`
查看生成进度	`pixverse:task-management`
浏览、下载或删除资产	`pixverse:asset-management`
设置认证或查看账户信息	`pixverse:auth-and-account`
浏览并从特效模板创建内容	`pixverse:template`

想要查看模型或参数？ 不用等到生成时才了解——直接阅读相关的功能文档：
视频模型与限制 →
skills/capabilities/create-video.md
（模型参考章节）
图像模型与限制 →
skills/capabilities/create-and-edit-image.md
（模型参考章节）

Model Quick Reference

模型快速参考

Use this to pick a model before diving into a sub-skill.

在深入学习子技能之前，用这个来选择合适的模型。

Video Models (

pixverse create video --model <value>

)

视频模型（

pixverse create video --model <value>

）

Model	`--model` value	Max Quality	Duration
PixVerse v5.6 (default)	`v5.6`	`1080p`	`1` – `10` s
Sora 2	`sora-2`	`720p`	`4` `8` `12` s
Sora 2 Pro	`sora-2-pro`	`1080p`	`4` `8` `12` s
Veo 3.1 Standard	`veo-3.1-standard`	`1080p`	`4` `6` `8` s
Veo 3.1 Fast	`veo-3.1-fast`	`1080p`	`4` `6` `8` s
Grok Imagine	`grok-imagine`	`720p`	`1` – `15` s

模型	`--model` 参数值	最高画质	时长
PixVerse v5.6（默认）	`v5.6`	`1080p`	`1` – `10` s
Sora 2	`sora-2`	`720p`	`4` `8` `12` s
Sora 2 Pro	`sora-2-pro`	`1080p`	`4` `8` `12` s
Veo 3.1 Standard	`veo-3.1-standard`	`1080p`	`4` `6` `8` s
Veo 3.1 Fast	`veo-3.1-fast`	`1080p`	`4` `6` `8` s
Grok Imagine	`grok-imagine`	`720p`	`1` – `15` s

Image Models (

pixverse create image --model <value>

)

图像模型（

pixverse create image --model <value>

）

Model	`--model` value	Max Quality
Qwen Image (default)	`qwen-image`	`1080p`
Seedream 5.0 Lite	`seedream-5.0-lite`	`1800p`
Seedream 4.5	`seedream-4.5`	`2160p`
Seedream 4.0	`seedream-4.0`	`2160p`
Gemini 2.5 Flash (Nanobanana)	`gemini-2.5-flash`	`1080p`
Gemini 3.0 (Nano Banana Pro)	`gemini-3.0`	`2160p`
Gemini 3.1 Flash (Nano Banana 2)	`gemini-3.1-flash`	`2160p`

For full parameter constraints (aspect ratios, quality per model, mode support), read the capabilities files listed above.

模型	`--model` 参数值	最高画质
Qwen Image（默认）	`qwen-image`	`1080p`
Seedream 5.0 Lite	`seedream-5.0-lite`	`1800p`
Seedream 4.5	`seedream-4.5`	`2160p`
Seedream 4.0	`seedream-4.0`	`2160p`
Gemini 2.5 Flash (Nanobanana)	`gemini-2.5-flash`	`1080p`
Gemini 3.0 (Nano Banana Pro)	`gemini-3.0`	`2160p`
Gemini 3.1 Flash (Nano Banana 2)	`gemini-3.1-flash`	`2160p`

如需完整的参数限制（宽高比、各模型支持的画质、模式支持），请阅读上面列出的功能文档。

Workflow Skills

工作流技能

I want to...	Use skill
Generate video from text end-to-end	`pixverse:text-to-video-pipeline`
Animate an image into video	`pixverse:image-to-video-pipeline`
Generate image then animate it	`pixverse:text-to-image-to-video`
Iteratively edit an image	`pixverse:image-editing-pipeline`
Full video production (create + extend + audio + upscale)	`pixverse:video-production`
Create multiple items in parallel	`pixverse:batch-creation`

我想要...	使用对应技能
从文本端到端生成视频	`pixverse:text-to-video-pipeline`
将图片动作为视频	`pixverse:image-to-video-pipeline`
先生成图片再将其动作为视频	`pixverse:text-to-image-to-video`
迭代编辑图片	`pixverse:image-editing-pipeline`
完整视频制作（创建+扩展+音频+提升分辨率）	`pixverse:video-production`
并行生成多个内容	`pixverse:batch-creation`

All Commands

所有命令

Command	Description
`auth login`	Login via browser (OAuth device flow)
`auth status`	Check authentication status
`auth logout`	Remove stored token
`create video`	Text-to-video or image-to-video
`create image`	Text-to-image or image-to-image
`create transition`	Create transitions between keyframes
`create speech`	Add lip-sync speech to video
`create sound`	Add AI sound effects to video
`create extend`	Extend video duration
`create upscale`	Upscale video resolution
`create reference`	Generate video with character references
`create template`	Create video or image from an effect template
`template categories`	List template categories
`template list`	Browse templates (with optional category filter)
`template search`	Search templates by keyword
`template info`	Get template details
`task status`	Check task status
`task wait`	Wait for task completion
`asset list`	List generated assets
`asset info`	Get asset details
`asset download`	Download a generated asset
`asset delete`	Delete an asset
`account info`	View account info and credits
`account usage`	View credit usage records
`subscribe`	Open subscription page in browser
`config list`	List all config values
`config get`	Get a config value
`config set`	Set a config value
`config reset`	Reset config to defaults
`config path`	Show config file path
`config defaults`	Manage per-mode creation defaults

命令	描述
`auth login`	通过浏览器登录（OAuth设备流）
`auth status`	查看认证状态
`auth logout`	删除存储的令牌
`create video`	文本转视频或图片转视频
`create image`	文本转图片或图片转图片
`create transition`	在关键帧之间创建转场效果
`create speech`	为视频添加唇形同步的语音
`create sound`	为视频添加AI音效
`create extend`	扩展视频时长
`create upscale`	提升视频分辨率
`create reference`	基于角色参考生成视频
`create template`	从特效模板创建视频或图片
`template categories`	列出模板分类
`template list`	浏览模板（可按分类筛选）
`template search`	按关键词搜索模板
`template info`	获取模板详情
`task status`	查看任务状态
`task wait`	等待任务完成
`asset list`	列出已生成的资产
`asset info`	获取资产详情
`asset download`	下载已生成的资产
`asset delete`	删除资产
`account info`	查看账户信息和剩余点数
`account usage`	查看点数使用记录
`subscribe`	在浏览器中打开订阅页面
`config list`	列出所有配置值
`config get`	获取某个配置值
`config set`	设置某个配置值
`config reset`	将配置重置为默认值
`config path`	显示配置文件路径
`config defaults`	管理各创建模式的默认设置

Global Flags

全局标志

Flag	Description
`--json` or `-p`	Pure JSON output to stdout (required for agent use)
`-V, --version`	Show CLI version
`-h, --help`	Show help for any command

Every command supports

--json

. All examples in skills use

--json

for machine-readable output.

Interactive mode: Run any creation command without arguments (and without

--json

) to enter the interactive wizard.

标志	描述
`--json` 或 `-p`	向标准输出输出纯JSON（Agent使用时必填）
`-V, --version`	显示CLI版本
`-h, --help`	查看任意命令的帮助信息

所有命令都支持

--json

标志。技能中的所有示例都使用

--json

以获得机器可读的输出。

交互模式：运行任意创建命令时不带参数（且不带

--json

）即可进入交互式向导。

Output Contract

输出约定

JSON mode (

--json

)

JSON模式（

--json

）

stdout: Pure JSON only. No spinners, no progress text, no decorative output.
stderr: All errors, warnings, and diagnostic messages.
Parse stdout with
```
jq
```
or any JSON parser.

标准输出：仅输出纯JSON。无加载动画、无进度文本、无装饰性输出。
标准错误输出：所有错误、警告和诊断信息。
可使用
```
jq
```
或任意JSON解析器解析标准输出。

Exit Codes

退出码

Code	Name	Meaning	Recovery
0	SUCCESS	Completed	—
1	GENERAL_ERROR	Unexpected error	Check stderr for details
2	TIMEOUT	Polling timed out	Increase `--timeout` or use `--no-wait` then `pixverse task wait`
3	AUTH_EXPIRED	Token invalid/expired	Re-run `pixverse auth login --json`
4	CREDIT_INSUFFICIENT	Not enough credits	Check `pixverse account info --json` , wait for daily reset or upgrade
5	GENERATION_FAILED	Generation failed/rejected	Check prompt, try different parameters
6	VALIDATION_ERROR	Invalid parameters	Check flag values against enums in each skill

代码	名称	含义	恢复方法
0	SUCCESS	任务完成	—
1	GENERAL_ERROR	意外错误	查看标准错误输出获取详情
2	TIMEOUT	轮询超时	增加 `--timeout` 参数，或使用 `--no-wait` 后再运行 `pixverse task wait`
3	AUTH_EXPIRED	令牌无效/过期	重新运行 `pixverse auth login --json`
4	CREDIT_INSUFFICIENT	点数不足	查看 `pixverse account info --json` ，等待每日重置或升级订阅
5	GENERATION_FAILED	生成失败/被拒绝	检查提示词，尝试不同参数
6	VALIDATION_ERROR	参数无效	检查标志值是否符合各技能中的枚举值

Error handling pattern

错误处理示例

bash

RESULT=$(pixverse create video --prompt "A sunset over mountains" --json 2>/tmp/pv_err)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')
  echo "Success: $VIDEO_ID"
  pixverse asset download $VIDEO_ID --json
elif [ $EXIT_CODE -eq 3 ]; then
  echo "Token expired, re-authenticating..."
  pixverse auth login --json
elif [ $EXIT_CODE -eq 4 ]; then
  echo "Not enough credits"
  pixverse account info --json | jq '.credits'
elif [ $EXIT_CODE -eq 5 ]; then
  echo "Generation failed — check prompt or parameters"
  cat /tmp/pv_err
else
  echo "Error (code $EXIT_CODE)"
  cat /tmp/pv_err
fi

bash

RESULT=$(pixverse create video --prompt "A sunset over mountains" --json 2>/tmp/pv_err)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')
  echo "Success: $VIDEO_ID"
  pixverse asset download $VIDEO_ID --json
elif [ $EXIT_CODE -eq 3 ]; then
  echo "令牌过期，重新认证中..."
  pixverse auth login --json
elif [ $EXIT_CODE -eq 4 ]; then
  echo "点数不足"
  pixverse account info --json | jq '.credits'
elif [ $EXIT_CODE -eq 5 ]; then
  echo "生成失败 — 检查提示词或参数"
  cat /tmp/pv_err
else
  echo "错误（代码 $EXIT_CODE)"
  cat /tmp/pv_err
fi

pixverse-ai-image-and-video-generator

Original

Translation

PixVerse CLI — Master Skill

PixVerse CLI — 核心使用指南

What is PixVerse CLI

什么是PixVerse CLI

Installation

安装

Quick Start

快速开始

1. Install

1. 安装

2. Authenticate (OAuth device flow — opens browser)

2. 认证（OAuth设备流 — 会打开浏览器）

3. Create a video (waits for completion by default)

3. 创建视频（默认等待生成完成）

4. Download the result

4. 下载生成结果

Authentication

认证

Capabilities Overview

功能概览

Model Quick Reference

模型快速参考

Video Models (pixverse create video --model <value>)

视频模型（pixverse create video --model <value>）

Image Models (pixverse create image --model <value>)

图像模型（pixverse create image --model <value>）

Workflow Skills

工作流技能

All Commands

所有命令

Global Flags

全局标志

Output Contract

输出约定

JSON mode (--json)

JSON模式（--json）

Exit Codes

退出码

Error handling pattern

错误处理示例

Video Models (
`pixverse create video --model <value>`
)

视频模型（
`pixverse create video --model <value>`
）

Image Models (
`pixverse create image --model <value>`
)

图像模型（
`pixverse create image --model <value>`
）

JSON mode (
`--json`
)

JSON模式（
`--json`
）