🇺🇸English
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
npm install -g pixverse
Or run without installing:
npx pixverse
Verify:
pixverse --version
Requires Node.js >= 20.
Quick Start
# 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:
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 |
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–10s |
| Sora 2 | sora-2 | 720p | 4 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 |
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 | |
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 |
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 |
Error handling pattern
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
Weekly Installs
63
Repository
pixverseai/skills
GitHub Stars
6
First Seen
12 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
gemini-cli60
github-copilot60
amp60
codex60
kimi-cli60
cursor60
