Back to Details

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
npm install -g pixverse

2. Authenticate (OAuth device flow — opens browser)

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

pixverse auth login --json
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')
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:
  1. Run 
    pixverse auth login --json
  2. The CLI prints an authorization URL
  3. Open the URL in your browser and authorize
  4. 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设备流——无需手动复制令牌：
  1. 运行
    pixverse auth login --json
  2. CLI会打印一个授权URL
  3. 在浏览器中打开该URL并完成授权
  4. 令牌会自动存储在
    ~/.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 QualityDuration
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

所有命令

CommandDescription
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

全局标志

FlagDescription
--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

退出码

CodeNameMeaningRecovery
0SUCCESSCompleted—
1GENERAL_ERRORUnexpected errorCheck stderr for details
2TIMEOUTPolling timed outIncrease 
--timeout
or use 
--no-wait
then 
pixverse task wait
3AUTH_EXPIREDToken invalid/expiredRe-run 
pixverse auth login --json
4CREDIT_INSUFFICIENTNot enough creditsCheck 
pixverse account info --json
, wait for daily reset or upgrade
5GENERATION_FAILEDGeneration failed/rejectedCheck prompt, try different parameters
6VALIDATION_ERRORInvalid parametersCheck flag values against enums in each skill
代码名称含义恢复方法
0SUCCESS任务完成—
1GENERAL_ERROR意外错误查看标准错误输出获取详情
2TIMEOUT轮询超时增加
--timeout
参数，或使用
--no-wait
后再运行
pixverse task wait
3AUTH_EXPIRED令牌无效/过期重新运行
pixverse auth login --json
4CREDIT_INSUFFICIENT点数不足查看
pixverse account info --json
，等待每日重置或升级订阅
5GENERATION_FAILED生成失败/被拒绝检查提示词，尝试不同参数
6VALIDATION_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