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

Windows users: For a full PowerShell pipeline example (T2I → I2V → sound → upscale → download), see skills/examples/windows/powershell-text-to-video.ps1.

---

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

---

Capabilities Overview#

I want to...Use skillCreate a video from text or imagepixverse:create-videoEnhance a video prompt for better resultspixverse:prompt-enhanceModify an existing video with a promptpixverse:modify-videoCreate or edit an imagepixverse:create-and-edit-imageExtend, upscale, or add audio to a videopixverse:post-process-videoCreate transition animation between framespixverse:transitionCheck generation progresspixverse:task-managementBrowse, download, or delete assetspixverse:asset-managementSet up auth or check accountpixverse:auth-and-accountBrowse and create from effect templatespixverse:templateManage workspaces (list, switch, status)pixverse:workspaceGenerate Mondo-style posters and coverspixverse:mondo-poster-design

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 valueMax QualityDurationPixVerse V6 (default)v6``1080p``1– 15 sPixVerse v5.6v5.6``1080p``1– 10 sSora 2sora-2``720p``4 8 12 sSora 2 Prosora-2-pro``1080p``4 8 12 sVeo 3.1 Standardveo-3.1-standard``1080p``4 6 8 sVeo 3.1 Fastveo-3.1-fast``1080p``4 6 8 sGrok Imaginegrok-imagine``720p``1– 15 s

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

Model--model valueMax QualityQwen Image (default)qwen-image``1080pSeedream 5.0 Liteseedream-5.0-lite``1800pSeedream 4.5seedream-4.5``2160pSeedream 4.0seedream-4.0``2160pGemini 2.5 Flash (Nanobanana)gemini-2.5-flash``1080pGemini 3.0 (Nano Banana Pro)gemini-3.0``2160pGemini 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 skillGenerate video from text end-to-endpixverse:text-to-video-pipelineAnimate an image into videopixverse:image-to-video-pipelineGenerate image then animate itpixverse:text-to-image-to-videoIteratively edit an imagepixverse:image-editing-pipelineModify a video and enhance itpixverse:modify-video-pipelineFull video production (create + extend + audio + upscale)pixverse:video-productionCreate multiple items in parallelpixverse:batch-creationGenerate a Mondo-style poster end-to-endpixverse:mondo-poster-pipelineGenerate poster then animate into videopixverse:mondo-poster-to-video-pipeline

---

Reference Materials#

Located in skills/references/. These are read-only knowledge bases that capabilities and workflows draw from — no CLI commands, just curated design knowledge.

ReferencePathContentMondo Artist Stylesreferences/mondo-poster/artist-styles.md37 artist styles with prompt keywords across 7 categoriesMondo Composition Patternsreferences/mondo-poster/composition-patterns.md8 composition techniques (negative space, silhouette, geometric framing, etc.)Mondo Genre Templatesreferences/mondo-poster/genre-templates.mdGenre-specific prompt templates for film, book covers, and album covers

---

All Commands#

CommandDescriptionauth loginLogin via browser (OAuth device flow)auth statusCheck authentication statusauth logoutRemove stored tokencreate videoText-to-video or image-to-videocreate imageText-to-image or image-to-imagecreate transitionCreate transitions between keyframescreate speechAdd lip-sync speech to videocreate soundAdd AI sound effects to videocreate modifyModify video content with a prompt at a keyframecreate extendExtend video durationcreate upscaleUpscale video resolutioncreate referenceGenerate video with character referencescreate templateCreate video or image from an effect templatetemplate categoriesList template categoriestemplate listBrowse templates (with optional category filter)template searchSearch templates by keywordtemplate infoGet template detailstask statusCheck task statustask waitWait for task completionasset listList generated assetsasset infoGet asset detailsasset downloadDownload a generated assetasset deleteDelete an assetaccount infoView account info and creditsaccount usageView credit usage recordsworkspace listList all workspacesworkspace statusShow currently active workspaceworkspace switchSwitch to a different workspaceworkspace manageOpen workspace management in browsersubscribeOpen subscription page in browserconfig listList all config valuesconfig getGet a config valueconfig setSet a config valueconfig resetReset config to defaultsconfig pathShow config file pathconfig defaultsManage per-mode creation defaults

---

Global Flags#

FlagDescription--json or -pPure JSON output to stdout (required for agent use)--workspace-id <id>Per-command workspace override (0 = personal). Not persisted — only affects the single invocation.-V, --versionShow CLI version-h, --helpShow 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#

CodeNameMeaningRecovery0SUCCESSCompleted—1GENERAL_ERRORUnexpected errorCheck stderr for details2TIMEOUTPolling timed outIncrease --timeout or use --no-wait then pixverse task wait3AUTH_EXPIREDToken invalid/expiredRe-run pixverse auth login --json4CREDIT_INSUFFICIENTNot enough creditsCheck pixverse account info --json, wait for daily reset or upgrade5GENERATION_FAILEDGeneration failed/rejectedCheck prompt, try different parameters6VALIDATION_ERRORInvalid parametersCheck flag values against enums in each skill

Workspace error auto-recovery#

When a request fails because the active workspace is no longer accessible (e.g. user was removed from a team), the CLI automatically resets to personal workspace (ID=0) and asks you to retry. This does not trigger when --workspace-id override is active or the failing request is a workspace management command.

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