Pixverse Ai Image And Video Generator

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, images, and audio (speech & music). 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

> Windows users: For a full PowerShell pipeline example (T2I → I2V → 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
• 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 | | Review a prompt and get suggestions to improve it (advice only, any model — never auto-edits the prompt) | pixverse:prompting-guide | | Enhance a video prompt for better results (V6 / generic) | pixverse:prompt-enhance | | Optimize a prompt for Seedance 2.0 (auto-triggers when prompt has clear optimization headroom; skipped when prompt is already clean) | pixverse:seedance-prompt-optimize | | Distill an emotional / atmospheric / loosely-expressed idea into an experience-first Seedance 2.0 prompt (Vibe Creating) | pixverse:seedance-vibe-creating | | Edit video content with AI (replace subjects, swap outfits, change backgrounds) | pixverse:modify-video | | Animate a character with motion from a reference video | pixverse:motion-control | | Create or edit an image | pixverse:create-and-edit-image | | Generate speech / voiceover from text (TTS) | pixverse:create-voice | | Generate music or a soundtrack from a prompt | pixverse:create-music | | Extend or upscale a video | pixverse:post-process-video | | Create transition animation between frames | pixverse:transition | | Check generation progress | pixverse:task-management | | Browse, download, upload, or delete assets | pixverse:asset-management | | Organize assets into named folders | pixverse:saved-folders | | Set up auth or check account | pixverse:auth-and-account | | Browse and create from effect templates | pixverse:template | | Manage workspaces (list, switch, status) | pixverse:workspace | | Generate Mondo-style posters and covers | pixverse:mondo-poster-design | | Design and reuse persistent characters across a story | pixverse:character-design | | Design and reuse persistent key items / props / objects | pixverse:item-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 )

| Model | --model value | Max Quality | Duration | |:---|:---|:---|:---| | PixVerse V6 (default) | v6 | 1080p | 1–15s | | PixVerse C1 | pixverse-c1 | 1080p | 1–15s | | PixVerse v5.6 | v5.6 | 1080p | 1–10s | | Sora 2 | sora-2 | 720p | 4 8 12s | | Sora 2 Pro | sora-2-pro | 1080p | 4 8 12s | | Veo 3.1 Standard | veo-3.1-standard | 1080p | 4 6 8s | | Veo 3.1 Fast | veo-3.1-fast | 1080p | 4 6 8s | | Veo 3.1 Lite | veo-3.1-lite | 1080p | 4–6s | | Grok Imagine | grok-imagine | 720p | 1–15s | | Grok Imagine 1.5 (image-to-video only) | grok-imagine-1.5 | 720p | 1–15s | | Happy Horse 1.0 | happyhorse-1.0 | 1080p | 3–15s | | Seedance 2.0 Standard | seedance-2.0-standard | 2160p | 4–15s | | Seedance 2.0 Fast | seedance-2.0-fast | 720p | 4–15s | | Seedance 2.0 Mini | seedance-2.0-mini | 720p | 4–15s | | Kling O3 Pro | kling-o3-pro | 720p | 3–15s | | Kling O3 Standard | kling-o3-standard | 720p | 3–15s | | Kling 3.0 Pro | kling-3.0-pro | 720p | 3–15s | | Kling 3.0 Standard | kling-3.0-standard | 720p | 3–15s |

Image Models (pixverse create image --model )

| Model | --model value | Max Quality | |:---|:---|:---| | GPT Image 2 (default) | gpt-image-2.0 | 2160p | | Qwen Image | qwen-image | 1080p | | Seedream 5.0 Lite | seedream-5.0-lite | 2160p | | 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 | | Kling Image O3 | kling-image-o3 | 2160p | | Kling Image V3 | kling-image-v3 | 1440p |

Voice / TTS Models (pixverse create voice --model )

| Model | --model value | Provider | Max characters | |:---|:---|:---|---:| | MiniMax Speech 2.8 HD (default) | speech-2.8-hd | MiniMax | 10,000 | | MiniMax Speech 2.8 Turbo | speech-2.8-turbo | MiniMax | 10,000 | | Eleven Multilingual v2 | eleven-multilingual-v2 | ElevenLabs | 10,000 | | Eleven v3 | eleven-v3 | ElevenLabs | 5,000 | | Eleven Turbo v2.5 | eleven-turbo-v2.5 | ElevenLabs | 40,000 |

Music Models (pixverse create music --model )

| Model | --model value | Provider | Lyrics | Image ref | |:---|:---|:---|:---|:---| | MiniMax Music 2.6 (default) | music-2.6 | MiniMax | Yes | No | | ElevenLabs Music | music-v1 | ElevenLabs | Yes | No | | Google Lyria 3 Pro | lyria-3-pro-preview | Google | No (use prompt) | Up to 10 |

For full parameter constraints (aspect ratios, quality per model, mode support, voice/music flags), 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 | | Modify a video and enhance it | pixverse:modify-video-pipeline | | Full video production (create + extend + audio + upscale) | pixverse:video-production | | Animate a character with a motion reference | pixverse:motion-control-pipeline | | Create multiple items in parallel | pixverse:batch-creation | | Generate a Mondo-style poster end-to-end | pixverse:mondo-poster-pipeline | | Generate poster then animate into video | pixverse:mondo-poster-to-video-pipeline | | Storyboard → 4-shot video from a single prompt | pixverse:storyboard-to-video |

---

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.

| Reference | Path | Content | |:---|:---|:---| | Mondo Artist Styles | references/mondo-poster/artist-styles.md | 37 artist styles with prompt keywords across 7 categories | | Mondo Composition Patterns | references/mondo-poster/composition-patterns.md | 8 composition techniques (negative space, silhouette, geometric framing, etc.) | | Mondo Genre Templates | references/mondo-poster/genre-templates.md | Genre-specific prompt templates for film, book covers, and album covers |

---

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 voice | Generate speech audio from text (TTS) | | create music | Generate music audio from a prompt | | create modify | Modify video content with a prompt at a keyframe | | create extend | Extend video duration | | create upscale | Upscale video resolution | | create reference | Generate video with character references | | create motion-control | Generate video with character image + motion reference video | | 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 | | voice models | List voice/TTS providers, models, and languages | | voice presets | List preset voices | | music models | List music providers and models | | task status | Check task status | | task wait | Wait for task completion | | asset list | List generated assets (with --source and --off-peak filters) | | asset info | Get asset details | | asset download | Download a generated asset | | asset upload | Upload a local file or HTTPS URL to asset library | | asset delete | Delete an asset | | saved list | List saved folders | | saved items | List items in a saved folder | | saved new | Create a new saved folder | | saved rename | Rename a saved folder | | saved add | Add assets to a saved folder | | saved remove | Remove assets from a saved folder | | saved delete | Delete a saved folder | | account info | View account info and credits | | account usage | View credit usage records | | account slots | Show current concurrent generation slots (image / video) | | workspace list | List all workspaces | | workspace status | Show currently active workspace | | workspace switch | Switch to a different workspace | | workspace manage | Open workspace management in browser | | 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 show | Show creation defaults (all modes or a specific mode) | | config defaults set | Set a per-mode creation default value | | config defaults reset | Reset creation defaults to built-in values | | update | Update the CLI to the latest version (npm i -g pixverse@latest) |

---

Global Flags

| Flag | Description | |:---|:---| | --json or -p | Pure JSON output to stdout (required for agent use) | | --workspace-id | Per-command workspace override (0 = personal). Not persisted — only affects the single invocation. | | --trace-id | Attach a caller-supplied UUIDv4 to all API requests in this invocation (for end-to-end tracing). Must be a valid UUIDv4. | | -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.

Common creation conventions (apply across create … commands):

• - for stdin — text inputs (--prompt, --text, --lyrics) accept a literal string, a local file path, or - to read from stdin. Pipe long or multi-line prompts: cat prompt.txt | pixverse create video --prompt - --json.
• --idempotency-key — supply a stable key for safe retries; the backend dedupes by key, so a repeated submission returns the original task without re-charging credits.

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 — including error payloads in --json mode (as of CLI v1.1.4: pixverse task … and pixverse template … errors are also routed to stderr, preserving the stdout-is-success contract).
• Parse stdout with jq or any JSON parser.

Universal JSON fields

All --json object payloads (both success on stdout and errors on stderr) automatically include:

| Field | When present | Meaning | |:---|:---|:---| | trace_id | Whenever the command made an HTTP request and the API returned an Ai-Trace-Id header | Upstream request id — include this when reporting bugs. Array / primitive payloads are not augmented. | | code | Error payloads from API failures | Backend error code (from ApiError). Pair with trace_id for support. | | error | Error payloads | Human-readable error message. | | cost_credits | create … success payloads, only when backend returns a positive integer | Credits charged for this creation request. Absent when the API returns 0, null, or omits the field. |

In interactive (non-JSON) text mode, cost_credits surfaces as Cost: N credits after Submitted!.

Exit Codes

| Code | Name | Meaning | Recovery | |:---|:---|:---|:---| | 0 | SUCCESS | Completed | — | | 1 | GENERALERROR | Unexpected error | Check stderr for details | | 2 | TIMEOUT | Polling timed out | Increase --timeout or use --no-wait then pixverse task wait | | 3 | AUTHEXPIRED | Token invalid/expired | Re-run pixverse auth login --json | | 4 | CREDITINSUFFICIENT | Not enough credits | Check pixverse account info --json, wait for daily reset or upgrade | | 5 | GENERATIONFAILED | Generation failed/rejected | Check prompt, try different parameters | | 6 | VALIDATION_ERROR | Invalid parameters | Check 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

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"
  pi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PixVerseAI](https://github.com/PixVerseAI)
- **Source:** [PixVerseAI/skills](https://github.com/PixVerseAI/skills)
- **License:** MIT
- **Homepage:** https://app.pixverse.ai

Install and usage instructions live in the source repository linked above.