PixVerse CLI — Master Skill

What is 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

Installation

bash

npm install -g pixverse

Or run without installing:

bash

npx pixverse

Verify:

bash

pixverse --version

Requires Node.js >= 20.

Quick Start

bash

# 1. Install
npm install -g pixverse

# 2. Authenticate (OAuth device flow — opens browser)
pixverse auth login --json

# 3. Create a video (waits for completion by default)
RESULT=$(pixverse create video --prompt "A cat astronaut floating in space" --json)
VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')

# 4. Download the result
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

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

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)

Model Quick Reference

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

Video Models (

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

Image Models (

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.

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`

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

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.

Output Contract

JSON mode (

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

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

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

pixverse-ai-image-and-video-generator

NPX Install

Tags

SKILL.md Content

PixVerse CLI — Master Skill

What is PixVerse CLI

Installation

Quick Start

Authentication

Capabilities Overview

Model Quick Reference

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

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

Workflow Skills

All Commands

Global Flags

Output Contract

JSON mode (
`--json`
)

Exit Codes

Error handling pattern

pixverse-ai-image-and-video-generator

NPX Install

Tags

SKILL.md Content

PixVerse CLI — Master Skill

What is PixVerse CLI

Installation

Quick Start

Authentication

Capabilities Overview

Model Quick Reference

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

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

Workflow Skills

All Commands

Global Flags

Output Contract

JSON mode (--json)

Exit Codes

Error handling pattern

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

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

JSON mode (
`--json`
)