# 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>`)

Supported modes are `pixverse create` subcommands. Defaults are mode-specific.

| Model | `--model` value | Supported create modes | Quality | Duration | Aspect Ratio |
| :--- | :--- | :--- | :--- | :--- | :--- |
| PixVerse V6 | `v6` | `video` (default), `transition` (2 frames, default), `extend` (default), `reference` (default) | `360p` `540p` `720p` `1080p` | `1`–`15`s | `16:9` `21:9` `4:3` `1:1` `3:4` `9:16` `3:2` `2:3` |
| PixVerse C1 | `pixverse-c1` | `video`, `transition` (2 frames), `reference` | `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` | `video`, `transition` (2 frames), `reference` | `480p` `720p` `1080p` | `4`–`30`s | `auto` `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` |
| Seedance 2.0 Standard | `seedance-2.0-standard` | `video`, `transition` (2 frames), `reference` | `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` | `video`, `transition` (2 frames), `reference` | `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` | `video`, `transition` (2 frames), `reference` | `480p` `720p` | `4`–`15`s | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9` |
| MiniMax H3 | `minimax-h3` | `video`, `transition` (2 frames), `reference` | `768p` `1440p` | `5`–`15`s | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `auto` |
| MiniMax H3 Max | `minimax-h3-max` | `video`, `transition` (2 frames), `reference` | `480p` `768p` `1080p` | `5`–`15`s | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `auto` |
| FLUX 3 | `flux-3.0` | `video` | `720p` `1080p` | `5`–`20`s | `auto` `21:9` `2:1` `16:9` `4:3` `1:1` `3:4` `9:16` |
| Wan 3.0 | `wan-3.0` | `video`, `transition` (2 frames), `reference` | `480p` `720p` `1080p` | `2`–`30`s | `auto` `16:9` `4:3` `1:1` `3:4` `9:16` |
| Google Gemini Omni | `gemini-omni-flash` | `video`, `reference` | `720p` | `3`–`10`s | `16:9` `9:16` |
| Happy Horse 1.0 | `happyhorse-1.0` | `video` | `720p` `1080p` | `3`–`15`s | `16:9` `9:16` `1:1` `4:3` `3:4` |
| Kling 4.0 | `kling-4.0` | `video`, `transition` (2 frames), `reference` | `720p` `1080p` | `3`–`30`s | `16:9` `9:16` `1:1` `21:9` |
| Kling O3 Pro | `kling-o3-pro` | `video`, `transition` (2 frames), `reference` | Selected by model ID | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling O3 Standard | `kling-o3-standard` | `video`, `transition` (2 frames), `reference` | Selected by model ID | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling O3 4K | `kling-o3-4k` | `video`, `transition` (2 frames), `reference` | Selected by model ID | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling 3.0 Pro | `kling-3.0-pro` | `video`, `transition` (2 frames) | Selected by model ID | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling 3.0 Standard | `kling-3.0-standard` | `video`, `transition` (2 frames) | Selected by model ID | `3`–`15`s | `16:9` `9:16` `1:1` |
| Kling 3.0 4K | `kling-3.0-4k` | `video`, `transition` (2 frames) | Selected by model ID | `3`–`15`s | `16:9` `9:16` `1:1` |
| Grok Imagine 1.5 | `grok-imagine-1.5` | `video` | `480p` `720p` `1080p` | `1`–`15`s | Derived from source image |
| Grok Imagine | `grok-imagine` | `video`, `extend`, `reference` | `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` | `video`, `transition` (2 frames) | `720p` `1080p` | `4` `6` `8`s | `16:9` `9:16` |
| Veo 3.1 Standard | `veo-3.1-standard` | `video`, `transition` (2 frames) | `720p` `1080p` `2160p` | `4` `6` `8`s | `16:9` `9:16` |
| Veo 3.1 Fast | `veo-3.1-fast` | `video`, `transition` (2 frames) | `720p` `1080p` `2160p` | `4` `6` `8`s | `16:9` `9:16` |
| Sora 2 Pro | `sora-2-pro` | `video` | `720p` `1080p` | `4` `8` `12`s | `16:9` `9:16` |
| Sora 2 | `sora-2` | `video` | `720p` | `4` `8` `12`s | `16:9` `9:16` |
| PixVerse V5.6 | `v5.6` | `video`, `transition` (2 frames), `reference`, `motion-control` (default) | `360p` `480p` `540p` `720p` `1080p` | `1`–`10`s | `16:9` `9:16` `1:1` `4:3` `3:4` `3:2` `2:3` |
| PixVerse V5.5 | `v5.5` | `modify` (default) | `360p` `540p` `720p` | — | — |
| PixVerse V5 | `v5` | `transition` (3+ frames, default) | `360p` `540p` `720p` `1080p` | `1`–`10`s | — |

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

> MiniMax H3 Max defaults to `768p` and 5 seconds. Text-to-video defaults to `16:9`; image-to-video forces `auto`; reference mode supports both `auto` and fixed aspect ratios, defaults to `auto`, and accepts up to 12 total inputs (9 images, 3 videos, and 3 audios).

> FLUX 3 is available only in `create video`. Text-to-video defaults to `16:9`; image-to-video defaults to `auto` while preserving an explicit fixed ratio. Requests always include the model's fixed safety setting.

> Wan 3.0 defaults to `720p`, 5 seconds, and `auto`, and is available in video, two-frame transition, and reference creation. Reference accepts up to 10 images, 5 videos, and 5 audios (20 total), including audio-only input. Video and audio reference durations are each limited to 15 seconds in aggregate. With a video reference, duration defaults to `auto`; fixed output duration is limited by `30 - reference video duration`.

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

> 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 | Max references | Background (`--background`) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| GPT Image 2.5 Flare _(default)_ | `gpt-image-2.5-flare` | `1080p` `1440p` `2160p` | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` `2:1` `1:2` `21:9` | 16 | `auto` `transparent` `opaque` |
| GPT Image 2.5 Sunburst | `gpt-image-2.5-sunburst` | `1080p` `1440p` `2160p` | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` `2:1` `1:2` `21:9` | 16 | `auto` `transparent` `opaque` |
| GPT Image 2 | `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` | 9 | — |
| Nano Banana 2.1 | `gemini-nano-banana-2.1` | `1080p` `1440p` `2160p` | `auto` `1:1` `3:2` `2:3` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` `1:4` `4:1` `1:8` `8:1` | 14 | — |
| Nano Banana 2 | `gemini-3.1-flash` | `512p` `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 9 | — |
| Nano Banana 2 Lite | `gemini-3.1-flash-lite` | `1080p` | `auto` `1:1` `3:2` `2:3` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` | 14 | — |
| 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` | 3 | — |
| Nano Banana Pro | `gemini-3.0` | `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 9 | — |
| Nano Banana | `gemini-2.5-flash` | `1080p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 3 | — |
| Seedream 5.0 Pro | `seedream-5.0-pro` | `1080p` `1440p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 10 | — |
| Seedream 5.0 Lite | `seedream-5.0-lite` | `1440p` `1800p` `2160p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 6 | — |
| Seedream 4.5 | `seedream-4.5` | `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 6 | — |
| Seedream 4.0 | `seedream-4.0` | `1080p` `1440p` `2160p` | `auto` `1:1` `16:9` `9:16` `4:3` `3:4` `5:4` `4:5` `3:2` `2:3` `21:9` | 6 | — |
| Kling Image O3 | `kling-image-o3` | `1080p` `1440p` `2160p` | `16:9` `9:16` `1:1` `4:3` `3:4` `3:2` `2:3` `21:9` | 10 | — |
| Kling Image V3 | `kling-image-v3` | `1080p` `1440p` | `16:9` `9:16` `1:1` `4:3` `3:4` `3:2` `2:3` `21:9` | 1 | — |

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

| Model | `--model` value | Provider | Speed |
| :--- | :--- | :--- | :--- |
| MiniMax Speech 2.8 HD _(default)_ | `speech-2.8-hd` | MiniMax | `0.5`–`2` |
| MiniMax Speech 2.8 Turbo | `speech-2.8-turbo` | MiniMax | `0.5`–`2` |
| Eleven Multilingual v2 | `eleven-multilingual-v2` | ElevenLabs | `0.7`–`1.2` |
| Eleven v3 | `eleven-v3` | ElevenLabs | `0.7`–`1.2` |
| Eleven Turbo v2.5 | `eleven-turbo-v2.5` | ElevenLabs | `0.7`–`1.2` |

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

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

Video uploads default to a 50 MB limit. Kling O3 reference videos retain their
200 MB limit, and template inputs use their declared limits. Shared API requests
default to a 60-second timeout; `--timeout` controls generation polling separately.

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

# Nano Banana 2.1 detail level: minimal | medium (default) | high
pixverse create image --model gemini-nano-banana-2.1 --detail-level high --prompt "A studio portrait"
```

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

# MiniMax H3 Max reference — the same per-type limits, with 12 inputs maximum in total
pixverse create reference -m minimax-h3-max --images ./char.png --videos ./motion.mp4 --audios ./voice.mp3 --prompt "@image1 follows @video1 and @audio1"

# Wan 3.0 reference — mixed inputs or audio-only, with automatic output duration when video is present
pixverse create reference -m wan-3.0 --videos ./motion.mp4 --audios ./voice.mp3 --duration auto --prompt "Follow @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 | CLI flag |
| :--- | :--- | :--- | :--- |
| MiniMax | `1` | `0.5`–`2` | `--speed` |
| ElevenLabs | `1` | `0.7`–`1.2` | `--speed` |

### Common Creation Flags

These flags are available across most `create` subcommands:

| Flag | Type | Default | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- |
| `--count` | integer | `1` | `1`–`4` count | Number of generation results. |
| `--seed` | integer | — | model-specific | Random seed for reproducible generation. |
| `--off-peak` | boolean | `false` | model-specific | Use off-peak generation where supported. |
| `--relax-mode [boolean]` / `--no-relax-mode` | boolean | — | model-specific | Relax mode: bare flag or true enables; false or --no-relax-mode disables. Omitted unless specified; model support and account entitlement are validated by the backend. Image benefits and video discounts depend on account rights. |
| `--audio` / `--no-audio` | boolean | `true` | model-specific | Enable or disable generated audio where supported. |
| `--multi-shot` / `--no-multi-shot` | boolean | `true` | model-specific | Enable multi-shot generation where supported. |
| `--no-wait` | boolean | `true` | model-specific | Wait for the generated asset unless disabled. |
| `--timeout` | integer | `300` | `1`–`∞` seconds | Polling timeout when waiting for completion. |

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

### Canvas

Canvas lets you build and manage connected creative workflows. A Canvas project
contains nodes for prompts, reference media, generation tasks, and composed
outputs. Dependencies connect those nodes and determine when generation can
start.

The CLI uses these terms consistently:

| Term           | Meaning                                                        |
| :------------- | :------------------------------------------------------------- |
| Canvas project | One Canvas workspace containing nodes and their connections    |
| Node           | One input, generated asset, text artifact, or composition step |
| Dependency     | A connection that requires one node before another can run     |
| Patch          | A validated set of node and dependency changes                 |
| Dispatch       | Starting generation for specific ready nodes                   |
| Dispatch plan  | A confirmation record authorizing one exact batch of nodes     |
| Version        | One saved generation result for a node                         |

Canvas node structure and routing come from the current Canvas capabilities;
model and parameter constraints come from the installed CLI. Query their
combined view instead of copying a fixed catalog from examples.

Create an empty project when starting a new workflow. The name and description
are optional:

```bash
pixverse canvas project create \
  --name "Campaign workspace" \
  --description "Connected image and video workflow" \
  --json
```

Pass the project ID after the command:

```bash
pixverse canvas graph get 123456789 --json
pixverse canvas node get 123456789 --node-id image_01 --json
```

To automatically arrange and save the entire project's layout:

```bash
pixverse canvas arrange "$PROJECT_ID" --json
pixverse canvas graph get "$PROJECT_ID" --json
```

Read the graph after arranging to get the updated positions and `edit_version`.

For reliable automation, inspect capabilities → read the project → validate the
patch → apply the patch → dispatch generated nodes → check node status:

```bash
# 1. Create a project when needed and retain project_id
pixverse canvas project create --json

# 2. Check the current Canvas capabilities
pixverse capabilities canvas \
  --node-type image_generate \
  --selector text_to_image \
  --model qwen-image \
  --json
pixverse canvas node schema --node-type image_generate --json

# 3. Read the project and retain edit_version
pixverse canvas graph get "$PROJECT_ID" --json

# 4. Validate and apply the same patch input
pixverse canvas patch dry-run "$PROJECT_ID" --patch patch.json --json
pixverse canvas patch apply "$PROJECT_ID" --patch patch.json --json

# 5. Start generation only for diff.executable_node_ids from patch apply
pixverse canvas dispatch "$PROJECT_ID" \
  --node-ids image_01,video_01 \
  --edit-version 13 \
  --json

# 6. Check only the nodes involved in this workflow
pixverse canvas graph status "$PROJECT_ID" \
  --node-ids image_01,video_01 \
  --json
```

`--patch` accepts a JSON literal, a local file path, or `-` for stdin. The input
contains a `graph_patch` object without an outer request wrapper. For example,
`patch.json` can contain:

```json
{
  "schema_version": "canvas_agent_graph.v1",
  "base_edit_version": 12,
  "nodes": [
    {
      "node_id": "script_01",
      "node_type": "script",
      "title": "Opening scene",
      "artifact": { "text": "A wide establishing shot at sunrise." }
    }
  ]
}
```

Keep all IDs as strings. `base_edit_version` must be a non-negative safe integer.
Starting in `1.4.13`, `dry-run` and `apply` send this value unchanged even when
it differs from the latest Graph `edit_version`. Both commands still read the
latest graph and capabilities for all other input and contextual validation.

For the same project and unchanged patch file, `dry-run` and `apply`
automatically derive the same stable idempotency key. Use
`--idempotency-key` only when your workflow needs to supply its own retry key.

Additional Canvas operations:

```bash
# Bind a specific batch of ready nodes to a dispatch plan
pixverse canvas dispatch rebind "$PROJECT_ID" \
  --dispatch-plan-id plan-20260817-001 \
  --node-ids image_01,video_01 \
  --json

# After confirmation, dispatch the same nodes with rebind's edit_version
pixverse canvas dispatch "$PROJECT_ID" \
  --dispatch-plan-id plan-20260817-001 \
  --node-ids image_01,video_01 \
  --edit-version "$REBIND_EDIT_VERSION" \
  --json

# List, inspect, and apply saved node versions
pixverse canvas node versions "$PROJECT_ID" --node-id video_01 \
  --page 1 --page-size 20 --json
pixverse canvas node version "$PROJECT_ID" --node-id video_01 \
  --history-id "$HISTORY_ID" --json
pixverse canvas node version apply "$PROJECT_ID" --node-id video_01 \
  --history-id "$HISTORY_ID" --json

# Run generation again for a specific failed node
pixverse canvas node rerun "$PROJECT_ID" --node-id video_01 \
  --edit-version 13 --json

# Extract the full audio track from a video node
pixverse canvas node extract-audio "$PROJECT_ID" \
  --node-id audio_extract_01 \
  --source-node-id video_01 \
  --json
```

Important constraints:

- A `video_compose` node references completed source media only through
  `payload.tracks`. Omit `depends_on` entirely; composition timeline materials
  do not create Canvas dependency edges.
- `dispatch` and `graph reconcile` require explicit node IDs and the current
  `edit_version`; the CLI does not intentionally start every ready node in a
  project.
- Dispatch states `partial` and `failed` return a non-zero exit code. Add
  `--require-dispatch` when `skipped` or `no_ready_nodes` should also stop an
  automated workflow.
- Existing dependencies cannot be cleared or replaced in place. For an
  agent-created node, delete it in one patch, read the project again, then
  create a replacement with a new `node_id` and the complete desired
  dependencies in a second patch. Deleted IDs remain reserved, so do not reuse
  the old ID; redirect all downstream dependencies and node references to the
  replacement ID.
- Applying a version may return `applied=false` when that version is already
  current. This is a successful no-op. Read the project again before the next
  change.
- Audio extraction accepts a trusted source video node, not a raw media path.
  The CLI creates the target audio node when needed and extracts the complete
  audio track.

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

`create template` supports more template types with ordered image, video, and
text inputs. Read `template info <id> --json` for the template's input
requirements, then supply the matching inputs:

```bash
pixverse create template --template-id <id> --image ./first.png ./second.png --json
```

When fewer images than slots are supplied, reserve images for required slots
and fill any remaining optional slots from left to right. Empty arguments are
accepted only when they match this mapping, for example
`--image "" ./required.png` for optional-then-required image slots. Selecting a
later optional slot while skipping an earlier optional slot is unsupported and
is rejected before upload or generation.

Use `--video` or `--prompt` only when the template exposes the corresponding
input slot. Templates with fixed output settings reject quality, duration,
aspect-ratio, seed, count, off-peak and idempotency overrides. Templates with
ordered input fields return `outputs` with media IDs and types; the CLI waits for each image/video
output unless `--no-wait` is set. Use `task status` / `task wait` with those
media IDs to check results later.

### 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                                                       |
| `capabilities`               | Show the installed static CLI capability bundle                                     |
| `capabilities create`        | Show structured Create modes, models, parameters, defaults, and limits              |
| `capabilities canvas`        | Query merged Canvas and CLI capabilities, or the raw Canvas response with `--raw`   |
| `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                                                   |
| `canvas project create`      | Create an empty Canvas project with an optional name and description                |
| `canvas arrange`             | Automatically arrange and save all nodes in a Canvas project                        |
| `canvas graph get`           | Get a Canvas project's nodes, connections, and edit version                         |
| `canvas graph status`        | Get the generation status of Canvas nodes                                           |
| `canvas graph invalid-nodes` | Show Canvas validation issues and invalid node details                              |
| `canvas graph reconcile`     | Recover generation for specific Canvas nodes                                        |
| `canvas node get`            | Get details for a Canvas node                                                       |
| `canvas node schema`         | Show the current schema for a Canvas node type                                      |
| `canvas node versions`       | List saved versions for a Canvas node                                               |
| `canvas node version`        | Get a saved version for a Canvas node                                               |
| `canvas node version apply`  | Set a saved version as the current Canvas node version                              |
| `canvas node rerun`          | Run generation again for a specific Canvas node                                     |
| `canvas node extract-audio`  | Extract the full audio track from a Canvas video node                               |
| `canvas patch dry-run`       | Validate Canvas changes without saving them                                         |
| `canvas patch apply`         | Apply validated changes to a Canvas project                                         |
| `canvas dispatch`            | Start generation for specific ready Canvas nodes                                    |
| `canvas dispatch rebind`     | Bind specific ready Canvas nodes to a dispatch plan                                 |

## 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) |
| `--region <region>`   | Service region: `global` or `cn` (default: `global`)      |
| `-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 includes the same machine-readable
capability bundle at `capabilities.json` that the npm package installs as
`dist/capabilities.json`. Query the installed version directly without signing
in or making a network request:

```bash
pixverse capabilities --json
pixverse capabilities create --json
pixverse capabilities create video --model v6 --json
```

The file uses a normalized compact encoding to avoid repeating shared
parameters and model metadata. `capabilities create` expands the selected mode
and model into a query-ready structure.

Canvas node schemas and route mappings are queried live instead of being
duplicated in the bundled file. Use
`pixverse capabilities canvas --node-type <type> --json` to combine them with
the installed CLI's model and parameter rules. Use
`pixverse capabilities canvas --raw --json` or
`pixverse canvas node schema --node-type <type> --json` when the unmodified
Canvas response is required.

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