# PixVerse CLI

The official command-line interface (CLI) for [PixVerse](https://pixverse.ai) — create AI-powered videos, images, and audio directly from your terminal.

## What is PixVerse?

PixVerse is an AI-powered creative platform that generates high-quality videos, images, and audio from text prompts or reference images. It supports a wide range of creative workflows including text-to-video, image-to-video, text-to-image, video transitions, text-to-speech (voice synthesis), music generation, templates/effects, and more.

## What is PixVerse CLI?

PixVerse CLI is essentially **a UI-free version of the PixVerse website**. All features and capabilities are aligned with the web experience — if you can do it on [pixverse.ai](https://pixverse.ai), you can do it from the command line with the same models, parameters, and quality.

It is designed for:

- **AI agents** — structured JSON output, deterministic exit codes, and pipeable commands make it a perfect tool for autonomous workflows (e.g. Claude Code, Cursor, Codex, LangChain, custom agents).
- **Developers & power users** — scriptable video/image/audio generation without leaving the terminal.
- **Automation** — integrate AI content generation into CI/CD pipelines, batch processing scripts, or content production workflows.

## Subscription Required

PixVerse CLI uses the same credit system as the website — generating videos, images, and audio consumes credits from your PixVerse account balance with the same pricing. To prevent abuse, **PixVerse CLI is currently available to subscribed users only**. For details on subscription plans and member benefits, see the [PixVerse Subscribe](https://app.pixverse.ai/subscribe) page.

## Installation

```bash
npm install -g pixverse
```

Or run without installing:

```bash
npx pixverse
```

**Requirements:** Node.js >= 22.12

## Authentication

PixVerse CLI uses OAuth device flow — no need to manually copy tokens:

```bash
pixverse auth login
```

This opens a browser where you confirm the authorization. You can also copy the URL and authorize from **any browser on any device** — useful for SSH or headless environments. The CLI receives a token automatically and stores it locally.

- Token is valid for 30 days
- CLI sessions are independent from your web/app sessions
- Run `pixverse auth status` to check your login state and credits
- Run `pixverse auth logout` to remove the stored token

> You need a PixVerse account to use the CLI. Sign up at [pixverse.ai](https://pixverse.ai) if you don't have one.

## Supported Models

### Video Models (`--model <value>`)

| Model                   | `--model` value         | Quality                             | Duration      | Aspect Ratio                                       |
| :---------------------- | :---------------------- | :---------------------------------- | :------------ | :------------------------------------------------- |
| PixVerse V6 _(default)_ | `v6`                    | `360p` `540p` `720p` `1080p`        | `1`–`15`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` `21:9` |
| PixVerse C1             | `pixverse-c1`           | `360p` `540p` `720p` `1080p`        | `1`–`15`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3`        |
| Seedance 2.5            | `seedance-2.5`          | `480p` `720p`                       | `4`–`30`s     | `auto` `21:9` `16:9` `4:3` `1:1` `3:4` `9:16`      |
| Seedance 2.0 Standard   | `seedance-2.0-standard` | `480p` `720p` `1080p` `2160p`       | `4`–`15`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9`             |
| Seedance 2.0 Fast       | `seedance-2.0-fast`     | `480p` `720p`                       | `4`–`15`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9`             |
| Seedance 2.0 Mini       | `seedance-2.0-mini`     | `480p` `720p`                       | `4`–`15`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9`             |
| MiniMax H3              | `minimax-h3`            | `768p` `1440p`                      | `5`–`15`s     | `auto` `21:9` `16:9` `4:3` `1:1` `3:4` `9:16`      |
| Google Gemini Omni      | `gemini-omni-flash`     | `720p`                              | `3`–`10`s     | `16:9` `9:16`                                      |
| Happy Horse 1.0         | `happyhorse-1.0`        | `720p` `1080p`                      | `3`–`15`s     | `16:9` `9:16` `1:1` `4:3` `3:4`                    |
| Kling O3 Pro            | `kling-o3-pro`          | _not applicable_                    | `3`–`15`s     | `16:9` `9:16` `1:1`                                |
| Kling O3 Standard       | `kling-o3-standard`     | _not applicable_                    | `3`–`15`s     | `16:9` `9:16` `1:1`                                |
| Kling O3 4K             | `kling-o3-4k`           | _not applicable_                    | `3`–`15`s     | `16:9` `9:16` `1:1`                                |
| Kling 3.0 Pro           | `kling-3.0-pro`         | _not applicable_                    | `3`–`15`s     | `16:9` `9:16` `1:1`                                |
| Kling 3.0 Standard      | `kling-3.0-standard`    | _not applicable_                    | `3`–`15`s     | `16:9` `9:16` `1:1`                                |
| Kling 3.0 4K            | `kling-3.0-4k`          | _not applicable_                    | `3`–`15`s     | `16:9` `9:16` `1:1`                                |
| Grok Imagine 1.5        | `grok-imagine-1.5`      | `480p` `720p` `1080p`               | `1`–`15`s     | _from image_                                       |
| Grok Imagine            | `grok-imagine`          | `480p` `720p`                       | `1`–`15`s     | `16:9` `4:3` `1:1` `9:16` `3:4` `3:2` `2:3`        |
| Veo 3.1 Lite            | `veo-3.1-lite`          | `720p` `1080p`                      | `4` `6` `8`s  | `16:9` `9:16`                                      |
| Veo 3.1 Standard        | `veo-3.1-standard`      | `720p` `1080p` `2160p`              | `4` `6` `8`s  | `16:9` `9:16`                                      |
| Veo 3.1 Fast            | `veo-3.1-fast`          | `720p` `1080p` `2160p`              | `4` `6` `8`s  | `16:9` `9:16`                                      |
| Sora 2 Pro              | `sora-2-pro`            | `720p` `1080p`                      | `4` `8` `12`s | `16:9` `9:16`                                      |
| Sora 2                  | `sora-2`                | `720p`                              | `4` `8` `12`s | `16:9` `9:16`                                      |
| PixVerse v5.6           | `v5.6`                  | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3`        |
| PixVerse v5.5           | `v5.5`                  | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3`        |
| PixVerse v5             | `v5`                    | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s     | `16:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3`        |

> Seedance 2.5 defaults to `720p`, 5 seconds, and `16:9` for generation without a reference video. Text-to-video and reference mode accept `--aspect-ratio auto` in addition to the fixed ratios. Reference requests containing a video default to automatic duration and lock the aspect ratio to `auto`; selecting an integer from 4 through 30 unlocks both automatic and fixed aspect ratios. Reference mode also accepts the optional `--task-type <type>` flag (`auto` by default, `reference`, `edit`, or `extend`) to guide the task intent; this flag is rejected for other models. Image-to-video retains its existing fixed-ratio behavior, while transition does not send a user-selected aspect ratio. Generated audio, multi-shot, and off-peak generation are unsupported.

> MiniMax H3 text-to-video defaults to `16:9`. Image-to-video forces `auto`; reference mode with images supports both `auto` and fixed aspect ratios and defaults to `auto`.

> Kling resolution is selected entirely by the model ID. Kling requests do not send `quality`; an explicit `--quality` value is ignored with a warning. Both 4K models support text/image-to-video and two-frame transitions, while only Kling O3 4K supports `create reference`.

> Reference video editing: V6 accepts up to 10 images and 2 videos (15s total after per-clip rounding); requests with a video lock duration to `auto` and reject fixed values. Seedance 2.5 accepts up to 10 videos (30s total); requests with a video default to `auto` but may select a fixed 4–30 seconds. Gemini Omni accepts up to 5 images and 1 video up to 10s; requests with a video lock duration to `auto` and reject fixed values. Kling O3 accepts up to 7 images without video or 4 images with 1 video up to 15s (200MB, 2048px per side). Grok Imagine accepts either 1–7 images with normal fixed duration or exactly 1 MP4 video up to 8.7s; video mode locks duration to `auto` and derives aspect ratio from the source video.

> Grok Imagine 1.5 is image-to-video only — it requires `--image`, supports `480p`, `720p`, and `1080p`, and derives its aspect ratio from the input image (the `--aspect-ratio` flag is ignored).

> Not all models support all creation modes. See the per-mode support matrix below.

#### Per-mode Model Support

| Creation mode                                   | Supported `--model` values                                                                                                                                                                                                                                                                                                                                               |
| :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create video` (text-to-video / image-to-video) | `v6` `pixverse-c1` `seedance-2.5` `seedance-2.0-standard` `seedance-2.0-fast` `seedance-2.0-mini` `minimax-h3` `gemini-omni-flash` `happyhorse-1.0` `kling-o3-pro` `kling-o3-standard` `kling-o3-4k` `kling-3.0-pro` `kling-3.0-standard` `kling-3.0-4k` `grok-imagine-1.5` `grok-imagine` `veo-3.1-lite` `veo-3.1-standard` `veo-3.1-fast` `sora-2-pro` `sora-2` `v5.6` |
| `create extend`                                 | `v6` `grok-imagine`                                                                                                                                                                                                                                                                                                                                                      |
| `create reference` (reference / video editing)  | `v6` `pixverse-c1` `seedance-2.5` `seedance-2.0-standard` `seedance-2.0-fast` `seedance-2.0-mini` `minimax-h3` `gemini-omni-flash` `kling-o3-pro` `kling-o3-standard` `kling-o3-4k` `grok-imagine` `v5.6`                                                                                                                                                                |
| `create transition` (2 frames)                  | `v6` `pixverse-c1` `seedance-2.5` `seedance-2.0-standard` `seedance-2.0-fast` `seedance-2.0-mini` `minimax-h3` `kling-o3-pro` `kling-o3-standard` `kling-o3-4k` `kling-3.0-pro` `kling-3.0-standard` `kling-3.0-4k` `veo-3.1-lite` `veo-3.1-standard` `veo-3.1-fast` `v5.6`                                                                                              |
| `create transition` (3+ frames)                 | `v5`                                                                                                                                                                                                                                                                                                                                                                     |
| `create modify`                                 | `v5.5`                                                                                                                                                                                                                                                                                                                                                                   |
| `create motion-control`                         | `v5.6`                                                                                                                                                                                                                                                                                                                                                                   |

> Audio creation uses separate model families: `create voice` for text-to-speech and `create music` for prompt-to-music.

### Image Models (`--model <value>`)

| Model                   | `--model` value         | Quality                        | Aspect Ratio                                                   |
| :---------------------- | :---------------------- | :----------------------------- | :------------------------------------------------------------- |
| GPT Image 2 _(default)_ | `gpt-image-2.0`         | `1080p` `1440p` `2160p`        | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` `2:1` `1:2` `21:9` |
| Nano Banana 2           | `gemini-3.1-flash`      | `512p` `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` + more                              |
| Nano Banana 2 Lite      | `gemini-3.1-flash-lite` | `1080p`                        | `auto` `1:1` `16:9` `9:16` + more                              |
| Qwen-image              | `qwen-image`            | `720p` `1080p`                 | `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` |
| Nano Banana Pro         | `gemini-3.0`            | `1080p` `1440p` `2160p`        | `auto` `1:1` `16:9` `9:16` + more                              |
| Nano Banana             | `gemini-2.5-flash`      | `1080p`                        | `auto` `1:1` `16:9` `9:16` + more                              |
| Seedream 5.0 Pro        | `seedream-5.0-pro`      | `1080p` `1440p`                | `auto` `1:1` `16:9` `9:16` + more                              |
| Seedream 5.0 Lite       | `seedream-5.0-lite`     | `1440p` `1800p` `2160p`        | `auto` `1:1` `16:9` `9:16` + more                              |
| Seedream 4.5            | `seedream-4.5`          | `1440p` `2160p`                | `auto` `1:1` `16:9` `9:16` + more                              |
| Seedream 4.0            | `seedream-4.0`          | `1080p` `1440p` `2160p`        | `auto` `1:1` `16:9` `9:16` + more                              |
| Kling Image O3          | `kling-image-o3`        | `1080p` `1440p` `2160p`        | `16:9` `9:16` `1:1` + more                                     |
| Kling Image V3          | `kling-image-v3`        | `1080p` `1440p`                | `16:9` `9:16` `1:1` + more                                     |

### Voice / TTS Models (`create voice --model <value>`)

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

> Browse available preset voices with `pixverse voice presets --model <id>` and the full live model catalog with `pixverse voice models`.

### Music Models (`create music --model <value>`)

| Model                         | `--model` value       | Provider   | Duration    | Notes                                                               |
| :---------------------------- | :-------------------- | :--------- | :---------- | :------------------------------------------------------------------ |
| MiniMax Music 3.0             | `music-3.0`           | MiniMax    | `10`-`240`s | Lyrics, auto lyrics, instrumental                                   |
| MiniMax Music 2.6 _(default)_ | `music-2.6`           | MiniMax    | `10`-`240`s | Lyrics, auto lyrics, instrumental                                   |
| ElevenLabs Music V2           | `music-v2`            | ElevenLabs | `10`-`240`s | Lyrics, auto lyrics, instrumental                                   |
| ElevenLabs Music              | `music-v1`            | ElevenLabs | `10`-`240`s | Lyrics, auto lyrics, instrumental                                   |
| Google Lyria 3 Pro            | `lyria-3-pro-preview` | Google     | `10`-`240`s | Auto lyrics, instrumental, image references, no separate `--lyrics` |

> Browse the live music model catalog with `pixverse music models`.

---

## Usage

### Interactive Mode

Run any creation command without arguments to enter the interactive wizard:

```bash
pixverse create video
pixverse create image
```

The wizard guides you through prompt, model, quality, aspect ratio, and other options step by step.

Local image inputs larger than `1920x1920` or `5MB` are automatically resized/compressed before upload. Remote image URLs are validated by the backend as-is.

### Text to Video

```bash
pixverse create video --prompt "A cat walking on Mars" --model v6 --quality 720p --aspect-ratio 16:9

# Seedance 2.5 supports integer durations from 4 through 30 seconds
pixverse create video --prompt "A slow aerial orbit around an alpine lake" --model seedance-2.5 --quality 720p --duration 12 --aspect-ratio 21:9

# Seedance 2.5 can let the model determine the text-to-video aspect ratio
pixverse create video --prompt "A cinematic landscape revealed through fog" --model seedance-2.5 --aspect-ratio auto
```

### Text inputs: literal, a file, or stdin

Text-input flags — `--prompt` (all create commands), `--text` (`create voice`), and `--lyrics` (`create music`) — accept three forms, just like `--image` / `--video`:

- a **literal** string: `--prompt "A neon city skyline"`
- a **local file path**: `--prompt ./scene.txt` (the file's contents are used)
- `-` to read from **stdin**: `... | pixverse create video --prompt -`

```bash
pixverse create video --prompt ./scene.txt
cat scene.txt | pixverse create image --prompt - --json
echo "Hello from the command line" | pixverse create voice --text -
pixverse create music --prompt "Bright synth-pop" --lyrics ./lyrics.txt
```

> A value is treated as a file only when a matching file actually exists on disk; otherwise it's used as literal text (the same rule as `--image` / `--video`).

### Image to Video

```bash
pixverse create video --prompt "Slow zoom in" --image ./photo.png

# Seedance 2.5 image-to-video preserves an explicitly selected fixed ratio
pixverse create video --prompt "The subject turns toward the camera" --image ./portrait.png --model seedance-2.5 --aspect-ratio 4:3
```

### Text to Image

```bash
pixverse create image --prompt "Cyberpunk cityscape at night" --aspect-ratio 16:9
```

### Image to Image

```bash
pixverse create image --prompt "Turn this into a watercolor painting" --image ./photo.png
```

### Other Creation Modes

```bash
# Create a transition between keyframes (requires 2+ images)
pixverse create transition --images ./frame1.png ./frame2.png ./frame3.png

# Seedance 2.5 transition requires exactly 2 frames; do not pass --aspect-ratio
pixverse create transition -m seedance-2.5 --images ./first.png ./last.png --prompt "A seamless transformation"

# Generate speech audio from text (text-to-speech)
pixverse create voice --text "Hello world" --voice-id <preset_voice_id> --output ./out.mp3
# Browse available models / preset voices:
pixverse voice models
pixverse voice presets --model speech-2.8-hd

# Generate music audio from a prompt
pixverse create music --prompt "A cinematic pop song with bright synths" --auto-lyrics
pixverse create music --prompt "Uplifting piano theme" --instrumental --duration-seconds 60
# Lyrics-capable models require lyrics unless --auto-lyrics or --instrumental is used:
# (--lyrics takes a literal string, a local file path, or - for stdin)
pixverse create music --prompt "Bright synth-pop, uplifting mood" --lyrics ./lyrics.txt
# Google Lyria supports image references and expects lyric-like instructions in --prompt:
pixverse create music -m lyria-3-pro-preview --prompt "Instrumental orchestral cue inspired by these images" --image ./moodboard.png
# Browse available music models:
pixverse music models

# Extend video duration
pixverse create extend --video <video_id>

# Modify an existing video
pixverse create modify --video <video_id> --prompt "Change the background to a beach"

# Upscale video resolution
pixverse create upscale --video <video_id> --quality 2160p

# Generate video from image references (V6 accepts up to 10 images)
pixverse create reference -m v6 --images ./char1.png ./char2.png --prompt "Two friends walking in a park"

# Edit video with V6 reference media (up to 2 videos, rounded total ≤ 15s)
pixverse create reference -m v6 --videos ./shot1.mp4 ./shot2.mov --duration auto --prompt "Turn the scene into a rainy night"

# Gemini Omni defaults to automatic duration with its single source video (up to 10s)
pixverse create reference -m gemini-omni-flash --images ./style.png --videos ./source.mp4 --prompt "Keep @video1's motion and apply @image1's style"

# Kling O3 4K accepts up to 4 images when a video is present (video ≤ 15s, 200MB, 2048px per side)
pixverse create reference -m kling-o3-4k --images ./character.png --videos ./motion.mov --prompt "Use @image1 as the subject in @video1"

# Grok Imagine accepts images or one MP4 video, but not both (video ≤ 8.7s)
pixverse create reference -m grok-imagine --videos ./source.mp4 --prompt "Replace the background with a desert"

# Seedance 2.5 reference — up to 50 total inputs: 30 images, 10 videos, and 10 audios;
# video and audio totals are each limited to 30s, audio needs an image or video,
# and --task-type defaults to auto (or explicitly accepts reference, edit, or extend)
pixverse create reference -m seedance-2.5 --images ./char.png --videos ./motion.mp4 --audios ./voice.mp3 --duration auto --aspect-ratio auto --prompt "@image1 follows @video1 and @audio1"

# Seedance 2.0 reference — mix images and videos (max 3 videos, total ≤ 15s)
pixverse create reference -m seedance-2.0-standard --images ./char.png --videos ./motion.mp4 --prompt "@image1 follows the motion in @video1"

# Seedance 2.0 reference — add audio references (max 3, each 2–15s, total ≤ 15s; needs a visual reference)
pixverse create reference -m seedance-2.0-standard --images ./char.png --audios ./voice.mp3 --prompt "@image1 speaks the line in @audio1"

# MiniMax H3 reference — mix up to 9 images, 3 videos, and 3 audios
pixverse create reference -m minimax-h3 --images ./char.png --videos ./motion.mp4 --audios ./voice.mp3 --prompt "@image1 follows @video1 and @audio1"

# Motion control — character image + motion reference video
pixverse create motion-control --image ./character.png --video ./dance.mp4

# Create from a template/effect
pixverse create template --template-id 12345 --image ./photo.png
```

Voice speed uses provider-specific validation:

| Provider   | Default | Valid range | Invalid range error                   | Provider request field |
| :--------- | :------ | :---------- | :------------------------------------ | :--------------------- |
| ElevenLabs | `1.0`   | `0.7..1.2`  | `--speed must be between 0.7 and 1.2` | `voice_settings.speed` |
| MiniMax    | `1.0`   | `0.5..2.0`  | `--speed must be between 0.5 and 2`   | `voice_setting.speed`  |

### Common Creation Flags

These flags are available across most `create` subcommands:

| Flag                               | Description                                       |
| :--------------------------------- | :------------------------------------------------ |
| `--count <n>`                      | Generate multiple variations (1–4, default 1)     |
| `--seed <number>`                  | Set random seed for reproducible results          |
| `--off-peak`                       | Use off-peak pricing (lower credit cost)          |
| `--audio` / `--no-audio`           | Enable or disable audio generation                |
| `--multi-shot` / `--no-multi-shot` | Enable or disable multi-shot mode (video only)    |
| `--no-wait`                        | Return immediately without waiting for completion |
| `--timeout <sec>`                  | Polling timeout in seconds (default 300)          |

> Model-specific support still applies. Seedance 2.5 does not support `--audio`, `--multi-shot`, or `--off-peak`. Its `--audios` values in `create reference` are input references, not a generated-audio toggle.

### MiniApps

MiniApps are preset, single-purpose generators from the PixVerse web app (Magic
Extend, Image Region Editor, …). The CLI is a thin pass-through: it does not
bundle each app's parameter schema. Instead, `miniapps info <id>` returns the
app's **parameter schema** (required fields, types, enum values, and a
copy-pasteable example) — read it, then submit the app id plus its `args` as JSON
with `miniapps create`.

```bash
# List available MiniApps
pixverse miniapps list

# Show a MiniApp's details + its parameter schema (what to put in --params)
pixverse miniapps info magic_extend          # add --json for the machine-readable params_schema

# Create a MiniApp project — --id and --params are required; --params takes JSON (a literal, a file path, or - for stdin)
pixverse miniapps create --id magic_extend --params '{"image":"<media-path>","ratio":"16:9","quality":"720p"}'
pixverse miniapps create --id image_region_editor --params ./args.json

# create returns a project_id — query / download / delete it with --type miniapps
pixverse task status <project_id> --type miniapps
pixverse task wait <project_id> --type miniapps
pixverse asset info <project_id> --type miniapps
pixverse asset download <project_id> --type miniapps --dest ./out/
pixverse asset delete <project_id> --type miniapps
```

Media fields inside `--params` must be **media paths** — the `path` returned by
`asset upload` (not a URL, not a local file). The CLI passes `--params` straight
through without uploading, so upload first with `pixverse asset upload <file>` and
use the returned `path`.

### Task Management

```bash
# Check task status
pixverse task status <id>

# Poll a voice/music audio task (audio is not auto-detected — pass --type audio)
pixverse task status <id> --type audio

# Poll a MiniApp project (pass --type miniapps; project_id comes from `miniapps create`)
pixverse task status <project_id> --type miniapps

# Batch status query with space-separated IDs (parallel; per-ID failures captured)
pixverse task status 123 456 789 --type video --json

# Comma-separated batch syntax remains supported
pixverse task status --ids 123,456,789 --type video --json

# Wait for a task to complete
pixverse task wait <id>
```

### Asset Management

```bash
# List your generated assets (default: created videos)
pixverse asset list
pixverse asset list --type image
pixverse asset list --type audio              # voice and music audio history
pixverse asset list --type audio --source upload
pixverse asset list --type miniapps           # MiniApp projects
pixverse asset list --source upload
pixverse asset list --source create --off-peak

# Upload a local file or URL to asset library
pixverse asset upload ./photo.png
pixverse asset upload ./voice-over.mp3
pixverse asset upload https://example.com/image.jpg

# Get asset details (type auto-detected: video → image → audio)
pixverse asset info <id>
# Pass --type to skip auto-detection
pixverse asset info <id> --type audio
pixverse asset info <id> --type audio --source upload

# Download a created video, image, or audio (uploads are not downloadable)
pixverse asset download <id>
pixverse asset download <id> --type audio --dest ./out/

# Delete a created asset — pass its id (auto-detected)
pixverse asset delete <id>
pixverse asset delete <id> --type audio

# Delete an uploaded asset — pass the id from `asset list --source upload`
pixverse asset delete <id> --source upload --type image
```

### Saved Folders

```bash
# List all saved folders
pixverse saved list

# List items in a folder (default folder if omitted)
pixverse saved items
pixverse saved items <folder_id> --type image --source upload

# Create a new folder
pixverse saved new "My Collection"

# Rename a folder
pixverse saved rename <folder_id> "New Name"

# Add assets to a folder
pixverse saved add <asset_id...> --folder <folder_id> --type video

# Remove assets from a folder
pixverse saved remove <asset_id...> --folder <folder_id> --type video

# Delete a folder
pixverse saved delete <folder_id>
```

### Templates

```bash
# List template categories
pixverse template categories

# List templates (with optional category filter and pagination)
pixverse template list
pixverse template list --category 5 --page 2 --limit 10

# Search templates by keyword
pixverse template search "dance"

# Get template details
pixverse template info <template_id>
```

### Workspaces

```bash
# List all workspaces
pixverse workspace list

# Show current workspace
pixverse workspace status

# Switch workspace (interactive or by ID)
pixverse workspace switch
pixverse workspace switch <workspace_id>

# Open workspace management in browser
pixverse workspace manage
```

### Account & Subscription

```bash
# View account info and credits
pixverse account info
pixverse account usage

# View current concurrent generation slots (image / video)
pixverse account slots
pixverse account slots --json

# Open subscription page in browser
pixverse subscribe
```

### Keeping the CLI up to date

```bash
# Update to the latest published version
pixverse update
```

When run interactively, the CLI checks the npm registry at most once per day and prints a one-line "update available" notice to **stderr** (never to stdout, so `--json` output stays clean). The check is skipped in `--json`/`-p` mode, in CI, and when stdout/stderr is piped.

### Configuration

```bash
# Set output directory
pixverse config set output-dir ~/Downloads

# View current configuration
pixverse config list

# Show config file path
pixverse config path

# Set per-mode creation defaults (model, quality, duration, etc.)
pixverse config defaults set video model v6
pixverse config defaults set video quality 1080p
pixverse config defaults show
```

## JSON Output for Scripts & Agents

All commands support `--json` (or `-p`) for structured JSON output, making the CLI easy to integrate into automated workflows:

```bash
pixverse create video --prompt "A sunset over the ocean" --json
pixverse task wait <id> --json
pixverse account info --json
```

### Pipeline Example

```bash
# Create a video → wait for completion → download
VID=$(pixverse create video --prompt "A cat on the moon" --json | jq -r '.video_id')
pixverse task wait "$VID" --json
pixverse asset download "$VID" --dest ./output/
```

### Exit Codes

| Code | Meaning                                                |
| :--- | :----------------------------------------------------- |
| `0`  | Success                                                |
| `1`  | General error                                          |
| `2`  | Timeout                                                |
| `3`  | Authentication error                                   |
| `4`  | Credit / subscription limit                            |
| `5`  | Generation failed                                      |
| `6`  | Validation error                                       |
| `7`  | Concurrent generation limit; wait for a slot and retry |

## 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 (text-to-speech)                                    |
| `create music`          | Generate music audio from a prompt                                                  |
| `create extend`         | Extend video duration                                                               |
| `create modify`         | Modify an existing video                                                            |
| `create upscale`        | Upscale video resolution                                                            |
| `create reference`      | Create or edit a video with reference media                                         |
| `create motion-control` | Motion control with character image + reference video                               |
| `create template`       | Create from a template/effect                                                       |
| `template categories`   | List template categories                                                            |
| `template list`         | List templates (with category filter)                                               |
| `template search`       | Search templates by keyword                                                         |
| `template info`         | Get template details                                                                |
| `voice models`          | List voice/TTS providers, models, and supported languages                           |
| `voice presets`         | List preset voices (filterable by model / language / provider)                      |
| `music models`          | List music providers, models, and capabilities                                      |
| `task status`           | Check one ID or batch with space-separated IDs / `--ids id1,id2,...`                |
| `task wait`             | Wait for task completion                                                            |
| `asset list`            | List assets (`--source create\|upload`, `--type video\|image\|audio`, `--off-peak`) |
| `asset upload`          | Upload a local file or HTTPS URL to asset library                                   |
| `asset info`            | Get asset details                                                                   |
| `asset download`        | Download a generated asset                                                          |
| `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                                                               |
| `workspace list`        | List all workspaces                                                                 |
| `workspace status`      | Show current workspace                                                              |
| `workspace switch`      | Switch workspace (interactive or by ID)                                             |
| `workspace manage`      | Open workspace management in browser                                                |
| `account info`          | View account info and workspace credits                                             |
| `account usage`         | View credit usage                                                                   |
| `account slots`         | View current concurrent generation slots (image / video)                            |
| `subscribe`             | Open subscription page                                                              |
| `update`                | Update the CLI to the latest version (`npm i -g pixverse@latest`)                   |
| `config set`            | Set a config value                                                                  |
| `config get`            | Get a config value                                                                  |
| `config list`           | List all config values                                                              |
| `config reset`          | Reset config to defaults                                                            |
| `config path`           | Show config file path                                                               |
| `config defaults`       | Manage per-mode creation defaults                                                   |

## Global Flags

| Flag                  | Description                                               |
| :-------------------- | :-------------------------------------------------------- |
| `--json`              | Output as JSON                                            |
| `-p`                  | Print mode (alias for `--json`)                           |
| `--workspace-id <id>` | Override active workspace for this command (0 = personal) |
| `-V, --version`       | Show CLI version                                          |
| `-h, --help`          | Show help for any command                                 |

## For AI Agents — Advanced Usage

For AI agents (Claude Code, Cursor, Codex, etc.), we **strongly recommend** installing [PixVerse Skills](https://github.com/PixVerseAI/skills) — a comprehensive skill library that teaches agents how to use PixVerse CLI correctly with full model constraints, multi-step pipelines, and error handling.

For lightweight discovery, the public repo also includes a compact machine-readable command manifest at `capabilities.json`; the npm package includes the same file at `dist/capabilities.json`.

**Install via Skills CLI:**

```bash
npx skills add https://github.com/pixverseai/skills --skill pixverse-ai-image-and-video-generator
```

**Or browse on ClawHub:**

[https://clawhub.ai/pixverse-official/pixverse-ai-image-and-video-generator](https://clawhub.ai/pixverse-official/pixverse-ai-image-and-video-generator)

Skills include:

- Per-model parameter constraints (which models support which modes, quality levels, durations, aspect ratios)
- End-to-end workflow pipelines (text-to-video, storyboard-to-video, video production, motion control, etc.)
- Prompt optimization techniques for better generation quality
- Batch creation patterns and error handling strategies

## Links

- [PixVerse Website](https://pixverse.ai)
- [PixVerse Skills](https://github.com/PixVerseAI/skills) — Agent skill library
- [npm Package](https://www.npmjs.com/package/pixverse)
- [Changelog](https://github.com/PixVerseAI/cli/blob/main/CHANGELOG.md)
- [Report Issues](https://github.com/PixVerseAI/cli/issues)

## License

[MIT](LICENSE)