PixVerse CLI: Generate AI Videos and Images in Terminal

Checked on 2026-10-13: Node.js >=22.12 is required. GPT Image 2.5 Flare is the default image model; PixVerse V6 is the default video model. Model support and controls vary by creation mode. Use the installed capabilities and the official README before a production run. README · capabilities.json

pixverse --version
pixverse capabilities create --json
pixverse canvas --help

Introduction

Every creative workflow has a bottleneck — the moment you have to leave your code editor, open a browser, and manually click through a web interface to generate a piece of media. For developers, AI agents, and anyone building automated content pipelines, that context switch is friction that adds up fast.

PixVerse CLI eliminates that bottleneck. It is the official command-line interface for PixVerse, giving you access to PixVerse generation and workspace workflows directly from your terminal. Text-to-video, image-to-video, text-to-image, image-to-image, transitions, voice generation, music generation, reference video, motion control, templates, upscaling, and asset management are all scriptable, pipeable, and available without touching a browser. For the shortest install path and agent setup overview, start from the official PixVerse CLI page.

What makes PixVerse CLI particularly useful is its design philosophy: it was built with AI agents in mind. Commands can return structured JSON with --json or -p, exit codes are deterministic, and every pipeline step is composable. This means you can teach Claude Code, Cursor, Codex, or any other agent to generate images, videos, voice, and music on your behalf with fewer fragile handoffs.

Prerequisites

Before starting, you need:

• Node.js 22.12 or higher — check with node --version
• A PixVerse account — sign up at pixverse.ai
• An active PixVerse subscription — the CLI uses the same credit system as the website; only subscribed users can generate content

PixVerse CLI does not require any API keys to be manually copied. Authentication is handled through a browser-based OAuth flow that stores your token locally.

Step 1: Install the CLI

Install globally with npm:

npm install -g pixverse

Verify the installation:

pixverse --version

If you prefer not to install globally, you can also run commands via npx:

npx pixverse create video --prompt "A cat walking on Mars"

Step 2: Authenticate

Run the login command:

pixverse auth login

The CLI opens a browser for OAuth device authorization. You can also copy the URL and finish authorization from any browser on any device, which is useful for SSH and headless environments. Your token is stored automatically in ~/.pixverse/ and is valid for 30 days.

To verify you are logged in and check your available credits:

pixverse auth status
pixverse account info
pixverse account slots
pixverse capabilities canvas --json

The account info command shows your subscription tier, workspace credits, and usage context. pixverse account usage helps you review credit consumption, while pixverse account slots shows the current concurrent generation slots for image and video jobs. CLI sessions are independent from PixVerse web/app sessions, and you can remove the stored CLI token with pixverse auth logout. Always check your balance and available slots before running batch jobs.

Quick Start Commands

If you only need the shortest path from installation to a generated asset, start with this sequence:

npm install -g pixverse
pixverse auth login
pixverse create image --prompt "A photorealistic forest path at golden hour" --json
pixverse create video --prompt "A sunset over ocean waves" --model v6 --quality 720p --duration 5 --json

For agent and CI workflows, keep --json or -p enabled so stdout stays machine-readable while progress and errors stay on stderr. For production retries, add --idempotency-key <key> to creation commands so repeated submissions do not accidentally create duplicate charged jobs.

Step 3: Generate Your First Image

Text-to-image generation is the fastest way to test your setup. Run:

pixverse create image --prompt "A photorealistic forest path at golden hour" --json

The current GitHub README lists GPT Image 2.5 Flare as the default image model. For reproducible automations, still set --model explicitly and check the live CLI help or capabilities.json before batch work. The --json flag returns structured output:

{
  "image_id": 789012,
  "status": "completed",
  "image_url": "https://...",
  "prompt": "A photorealistic forest path at golden hour",
  "model": "gpt-image-2.5-flare",
  "width": 1440,
  "height": 1440
}

For higher resolution output, specify a model that supports it:

pixverse create image \
  --prompt "A photorealistic forest path at golden hour" \
  --model seedream-5.0-lite \
  --quality 2160p \
  --aspect-ratio 16:9 \
  --json

PixVerse supports several image models, each with different resolution ceilings and aspect-ratio support:

pixverse capabilities create image --json
pixverse capabilities create image --model gpt-image-2.5-flare --json

You can also transform an existing image with image-to-image:

pixverse create image \
  --prompt "Turn this product photo into a clean watercolor illustration" \
  --image ./product-photo.png \
  --model gpt-image-2.0 \
  --json

To download the generated image:

pixverse asset download 789012 --type image

Step 4: Generate Your First Video

Text-to-video works the same way. Generate a 5-second clip:

pixverse create video --prompt "A sunset over ocean waves" --json

For a fully customized generation:

pixverse create video \
  --prompt "A cinematic drone shot over a misty mountain valley at dawn" \
  --model v6 \
  --quality 1080p \
  --aspect-ratio 16:9 \
  --duration 8 \
  --audio \
  --json

For models that support native audio, --audio requests an audio-enabled generation. The --json flag returns a video_url on completion that you can pass directly to a download command or the next step in a pipeline.

PixVerse provides multiple video models with different quality, duration, and mode support:

pixverse capabilities create video --json
pixverse capabilities create reference --model seedance-2.5 --json

Partner models such as Seedance, Kling, Veo, Sora, Gemini Omni, Grok Imagine, and HappyHorse are options on PixVerse. Use the same CLI surface to compare them against PixVerse V6 and C1.

Animate a Static Image

To turn a photo or generated image into a video, provide the --image flag:

pixverse create video \
  --prompt "Gentle wind moves through the scene" \
  --image ./product-photo.jpg \
  --model v6 \
  --quality 1080p \
  --json

You can pass a local file path or a URL. Local files are uploaded automatically — no manual upload step required. Local image inputs larger than 1920x1920 or 5MB are automatically resized or compressed before upload; remote image URLs are validated by the backend as-is.

For Grok Imagine 1.5, an image is required and the output aspect ratio follows that image:

pixverse create video \
  --prompt "Slow camera push-in, subtle fabric motion, clean native ambience" \
  --image ./campaign-poster.png \
  --model grok-imagine-1.5 \
  --quality 720p \
  --duration 6 \
  --json

Use Reference, Transition, Motion Control, and Templates

The current CLI supports more than simple text-to-video and image-to-video. These creation modes are useful when you need more control over characters, keyframes, edits, or effects:

# Create a transition between keyframes
pixverse create transition --images ./frame1.png ./frame2.png

# Generate speech audio from text
pixverse create voice --text "Welcome to the launch" --voice-id <preset_voice_id> --output ./voiceover.mp3

# Generate music from a prompt
pixverse create music --prompt "A cinematic synth-pop intro with bright percussion" --auto-lyrics
pixverse create music --prompt "Uplifting piano theme for a product reveal" --instrumental --duration-seconds 60

# Extend a generated video
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 to 2160p
pixverse create upscale --video <video_id> --quality 2160p

# Generate video with reference images
pixverse create reference --images ./char1.png ./char2.png --prompt "Two friends walking in a park"

# Seedance 2.0 reference can mix image and video inputs
pixverse create reference \
  --model seedance-2.0-standard \
  --images ./character.png \
  --videos ./motion.mp4 \
  --prompt "@image1 follows the motion in @video1"

# Seedance 2.0 models support up to 9 reference images
pixverse create reference \
  --model seedance-2.0-standard \
  --images ./char1.png ./char2.png ./char3.png ./char4.png \
  --prompt "@image1 and @image2 walk through the scene together"

# Motion control with a character image and motion reference video
pixverse create motion-control --image ./character.png --video ./dance.mp4

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

Step 5: Generate Voice and Music

The current GitHub README documents standalone audio through dedicated creation commands. Use create voice for text-to-speech and create music for prompt-to-music generation. Voice and music outputs are saved as audio assets, so you can track them with task, list them with asset list --type audio, and download them with asset download --type audio. For native video ambience, use --audio or --no-audio on supported video creation commands.

Generate voice audio:

pixverse create voice \
  --text "Welcome to the launch. Here is what changed this week." \
  --model speech-2.8-hd \
  --voice-id <preset_voice_id> \
  --output ./voiceover.mp3 \
  --json

Browse voice models and preset voices:

pixverse voice models --json
pixverse voice presets --model speech-2.8-hd --json

Generate music:

pixverse create music \
  --prompt "A bright cinematic synth-pop track for a 30-second product reveal" \
  --auto-lyrics \
  --duration-seconds 30 \
  --json

For instrumental tracks, use --instrumental. For lyrics-capable models, pass lyrics as literal text, a local file path, or stdin:

pixverse create music \
  --prompt "Uplifting electronic pop with a confident chorus" \
  --lyrics ./lyrics.txt \
  --json

Current voice model families include MiniMax Speech 2.8 and ElevenLabs models. Current music model families include MiniMax Music, ElevenLabs Music, and Google Lyria 3 Pro. Use pixverse voice models and pixverse music models for the live catalog before scripting a production workflow.

Step 6: Run the Interactive Wizard

If you are exploring for the first time and are not yet familiar with all the available flags, run any creation command without arguments to enter the guided wizard:

pixverse create video
pixverse create image

The wizard walks you through prompt, model selection, quality, aspect ratio, duration, and other options step by step — useful for discovering what parameters are available before scripting them.

Beyond Generation: Manage Your Assets and Workspace

The current PixVerse CLI also includes management commands that help you build end-to-end terminal workflows:

• pixverse task status <id> and pixverse task wait <id> for task polling
• pixverse task status --ids 123,456,789 --type video --json for batch status checks
• pixverse asset list, asset upload, asset info, asset download, and asset delete for video, image, and audio asset lifecycle operations
• pixverse saved list, saved items, saved new, saved rename, saved add, saved remove, and saved delete for saved folders
• pixverse template categories, template list, template search, and template info for discovering effects and templates
• pixverse voice models, voice presets, and music models for live audio model discovery
• pixverse workspace list, workspace status, workspace switch, and workspace manage for multi-workspace operations
• pixverse account info, account usage, and account slots for credit, usage, and concurrency checks
• pixverse config set, config list, config path, and config defaults for repeatable local defaults

This makes it straightforward to automate not only creation, but also organization, template discovery, audio discovery, download, workspace routing, and delivery in one script. If you need to run one command against a different workspace, use the global --workspace-id <id> flag; 0 targets your personal workspace.

Canvas Projects and Current Model Support

The CLI now includes Canvas project, graph, node, patch, and dispatch workflows. Inspect pixverse canvas --help and pixverse capabilities canvas --json before building a project automation. Canvas capabilities require an authenticated session and are retrieved from the service; creation capabilities describe the installed CLI. Update the CLI when a model is missing from its bundled catalog.

The current catalog includes Seedance 2.5, MiniMax H3/H3 Max, FLUX 3, Wan 3.0, Kling 4K, GPT Image 2.5 Flare/Sunburst, and Nano Banana 2.1. Resolve capabilities for the specific model and mode rather than reusing another model’s duration, audio, reference, or resolution settings.

Script-Friendly Flags

Most automation depends on predictable output and predictable runtime behavior. These flags are especially useful in scripts and AI-agent workflows:

Flag	Use It For
--json	Return structured JSON output
-p	Short alias for --json
--count <n>	Generate 1–4 variations from one request
--seed <number>	Set a seed where the selected model supports it
--off-peak	Use off-peak pricing when available
--audio / --no-audio	Enable or disable audio generation on supported creation commands
--multi-shot / --no-multi-shot	Enable or disable multi-shot mode for video
--no-wait	Submit the job and return immediately
--timeout <sec>	Set the polling timeout, defaulting to 300 seconds
--workspace-id <id>	Override the active workspace for a single command
--trace-id <uuid>	Attach a caller-supplied UUIDv4 to API requests for debugging and observability
--idempotency-key <key>	Safely retry creation requests without accidentally creating duplicate charged jobs

Text input flags are now easier to automate. --prompt, --text, and --lyrics can accept a literal string, a local file path, or - for stdin:

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

Teaching Your AI Agent to Generate Media

For teams that prefer a guided, app-based starting point before moving into command-line automation, PixVerse Agent provides an agent-oriented creation workflow in the PixVerse app.

This is where PixVerse CLI becomes genuinely transformative. Because commands can return structured JSON and use deterministic exit codes, any AI agent that can run shell commands can be taught to generate images and videos on demand.

Installing PixVerse Skills

PixVerse Skills is a structured skill library that teaches agents how to use the CLI correctly: command flags, model constraints, multi-step pipelines, and robust error handling.

For Claude Code and other agents that support the skills format, add the PixVerse skills directly:

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

For Cursor, Claude Code, Codex, and other agent frameworks, this skill improves reliability by giving the agent explicit constraints instead of forcing it to infer them from scratch.

Once your agent has the PixVerse skills loaded, you can give it natural-language instructions like:

• “Generate a 10-second product demo video from this screenshot”
• “Create four variations of this blog cover image in 16:9 format”
• “Animate this diagram into a 5-second explainer clip with ambient sound”
• “Generate three 8-second 16:9 promo clips with different camera motions”

The agent will translate those instructions into the correct CLI commands, parse the JSON output, and handle polling and downloads — no manual intervention required.

Claude Code

In Claude Code, PixVerse CLI becomes a native tool the agent uses autonomously. After loading the PixVerse skills, you can include media generation directly in any task:

Generate a cover image for this blog post about machine learning, use the seedream-5.0-lite model at 2160p in 16:9 format, download it to ./assets/cover.webp

Claude Code will invoke the correct CLI commands, parse the image URL from the JSON response, and download the file to your specified path — all within the same session where it is also writing your code.

A typical Claude Code workflow:

# Claude Code runs this autonomously based on your instruction
IMG=$(pixverse create image \
  --prompt "Abstract visualization of neural network layers, dark background, blue and purple tones" \
  --model seedream-5.0-lite \
  --quality 2160p \
  --aspect-ratio 16:9 \
  --json | jq -r '.image_url')

# Then animates it
pixverse create video \
  --prompt "Slow pan across glowing neural connections" \
  --image "$IMG" \
  --model v6 \
  --quality 1080p \
  --duration 6 \
  --json

Cursor

Cursor users can load PixVerse Skills as a project context file. Place the relevant skill files in your .cursor/ directory or add them to your workspace rules. Once loaded, Cursor has full awareness of every PixVerse CLI command and can generate media as part of any coding task.

A common Cursor workflow: ask the agent to generate a mockup image based on a design you are building, then use it as a reference directly in your IDE session — without ever leaving the editor.

Codex and Other Agents

PixVerse CLI is compatible with any agent that can execute shell commands and parse JSON. The structured output format — consistent field names, predictable error codes, and stderr-separated error messages — ensures that even simple scripting agents can integrate generation reliably.

The exit code contract makes error handling straightforward:

Code	Meaning	Agent Action
0	Success	Parse JSON output
1	General error	Check stderr and retry with validated inputs
2	Timeout	Retry with longer --timeout
3	Auth expired	Re-run pixverse auth login
4	Out of credits	Check balance, notify user
5	Generation failed	Try different parameters
6	Validation error	Review flag values
7	Concurrency limit	Wait for an available slot, then retry

Automation Pipelines

Once you understand the individual commands, PixVerse CLI unlocks powerful multi-step workflows that run entirely without user interaction.

Text to Image to Video

One of the most useful pipelines: generate a high-resolution image from a text prompt, then animate it into a video.

# Step 1: Generate a base image
IMG_RESULT=$(pixverse create image \
  --prompt "A cyberpunk cityscape at night, neon lights reflecting on wet pavement" \
  --model gemini-3.1-flash \
  --quality 2160p \
  --aspect-ratio 16:9 \
  --json)

IMAGE_URL=$(echo "$IMG_RESULT" | jq -r '.image_url')

# Step 2: Animate it into a video
VID_RESULT=$(pixverse create video \
  --prompt "Camera slowly pans across the neon-lit streets" \
  --image "$IMAGE_URL" \
  --model v6 \
  --quality 1080p \
  --duration 8 \
  --json)

VIDEO_ID=$(echo "$VID_RESULT" | jq -r '.video_id')

# Step 3: Download the final video
pixverse asset download "$VIDEO_ID" --json

Full Video Production Pipeline

For polished output, chain creation with post-processing steps. Use --audio or --no-audio when you want native sound on supported video creation commands, then use create voice for text-to-speech audio and create music for standalone music assets that you will combine downstream:

# Step 1: Create the base video
RESULT=$(pixverse create video \
  --prompt "A product being assembled in slow motion" \
  --model v6 \
  --quality 720p \
  --duration 5 \
  --audio \
  --json)

VID=$(echo "$RESULT" | jq -r '.video_id')

# Step 2: Extend duration
EXTENDED=$(pixverse create extend \
  --video "$VID" \
  --json | jq -r '.video_id')

pixverse task wait "$EXTENDED" --json

# Step 3: Upscale to 2160p
FINAL=$(pixverse create upscale \
  --video "$EXTENDED" \
  --quality 2160p \
  --json | jq -r '.video_id')

pixverse task wait "$FINAL" --json

# Step 4: Download
pixverse asset download "$FINAL" --json

# Optional: create a separate voiceover asset
pixverse create voice \
  --text "The final reveal starts now." \
  --voice-id <preset_voice_id> \
  --output ./voiceover.mp3 \
  --json

Batch Generation

For content pipelines that require multiple variations, run jobs in parallel:

# Check credits and concurrent generation slots first
pixverse account info --json
pixverse account slots --json

# Submit four parallel generations
pixverse create video --prompt "Sunrise over mountains" --no-wait --json > /tmp/v1.json &
pixverse create video --prompt "Sunset over ocean" --no-wait --json > /tmp/v2.json &
pixverse create video --prompt "Stars over a desert" --no-wait --json > /tmp/v3.json &
pixverse create video --prompt "Aurora over a frozen lake" --no-wait --json > /tmp/v4.json &
wait

# Check all returned task IDs in one batch status call
IDS=$(jq -r '.video_id' /tmp/v1.json /tmp/v2.json /tmp/v3.json /tmp/v4.json | paste -sd, -)
pixverse task status --ids "$IDS" --type video --json

# Wait for each and download
for f in /tmp/v1.json /tmp/v2.json /tmp/v3.json /tmp/v4.json; do
  ID=$(jq -r '.video_id' "$f")
  pixverse task wait "$ID" --json
  pixverse asset download "$ID" --json
done

The --no-wait flag submits the job and returns immediately with a task ID, allowing you to submit multiple jobs before polling. With --no-wait --json, record the returned task IDs and resolved creation parameters for logging and reproducibility. Use --count <n> when you want multiple variations from one prompt, and use batch task status --ids when you want one status response for several running jobs. The pixverse task wait command handles adaptive polling for you.

Configuring Defaults

If you consistently use the same model, quality, or aspect ratio, set them as defaults so you do not have to repeat flags every time:

pixverse config defaults set video model v6
pixverse config defaults set video quality 1080p
pixverse config defaults set image model seedream-5.0-lite
pixverse config set output-dir ~/Downloads/pixverse
pixverse config defaults show
pixverse config list
pixverse config path

Command-line flags always override your configured defaults, so you retain full flexibility while reducing repetition. For workspace-specific automation, add --workspace-id <id> to a command when you want to override the active workspace for that single run.

What You Can Build

With PixVerse CLI integrated into your agent workflow, the range of automatable tasks expands considerably:

• Documentation — auto-generate product demo videos and screenshots as part of your doc build process
• Marketing — run nightly batch jobs that produce social media content variations from a single prompt library
• App development — let your coding agent generate placeholder visuals, mockup animations, or loading screen videos while you build the UI
• Audio workflows — generate voiceover drafts, prompt-to-music tracks, or audio assets for later editing
• Content pipelines — chain CLI calls with other tools (ffmpeg, ImageMagick, cloud storage) to build fully automated media production workflows
• Prototyping — generate quick motion concepts in seconds to validate ideas before committing to full production

The CLI is designed to fit naturally into any shell-based workflow. If your existing automation runs in bash, Python, Node, or a CI/CD pipeline, PixVerse CLI slots in without any additional integration overhead.

Getting Started Checklist

• Install Node.js 22.12 or higher
• Run npm install -g pixverse
• Run pixverse auth login and authorize in browser
• Run pixverse account info to verify credits
• Run pixverse account slots before concurrent batch work
• Generate your first image: pixverse create image --prompt "..." --json
• Generate your first video: pixverse create video --prompt "..." --json
• Generate your first voice asset: pixverse create voice --text "..." --json
• Generate your first music asset: pixverse create music --prompt "..." --json
• Explore templates with pixverse template list
• Install PixVerse Skills for your agent (Claude Code, Cursor, or Codex)
• Set up your preferred defaults with pixverse config defaults set
• Build your first automation pipeline

Keeping the CLI Up to Date

Use the built-in updater to keep your local CLI current:

pixverse update

You can also use npm directly:

npm install -g pixverse@latest

Because PixVerse CLI is an actively updated tool rather than a one-time launch, treat this article as a practical field guide and the official sources as the live reference layer. The official PixVerse CLI page is the shortest install and agent-onboarding path, while GitHub remains the place to track release-level changes and newly supported models:

• PixVerse CLI GitHub repository
• PixVerse CLI capabilities manifest
• PixVerse CLI Changelog

The current docs highlight PixVerse V6 as the default video model, GPT Image 2.5 Flare as the default image model, Google Gemini Omni video support, Nano Banana 2 Lite and Seedream 5.0 Pro image support, Seedance 2.0 Mini support, mode-specific PixVerse v5 and v5.5 workflows, dedicated create voice and create music commands, audio asset management, saved folders, workspace switching, config defaults, capabilities.json for agents, pixverse update, stdin support for text inputs, --trace-id, and --idempotency-key for safer retries.

Next Steps

The official PixVerse CLI page, PixVerse CLI on GitHub, and npm (npm install -g pixverse) give you immediate access to generation, task polling, asset management, templates, saved folders, account checks, audio model discovery, and workspace controls from a single interface. The PixVerse Skills repository adds agent-ready guidance so Claude Code, Cursor, Codex, and other tools can run these workflows with stronger reliability.

The combination of a reliable CLI and an agent-ready skill library means image, video, voice, and music generation can live in the same workflow as your code — managed by the same agent, in the same terminal, without switching tools.

Start with a single command. Build from there.

Related Resources

• PixVerse V6 AI Video Generator Review
• Best AI Video Models in One Platform
• Seedance 2.0 Now Available on PixVerse
• Grok Imagine Now Available on PixVerse
• PixVerse AI Platform Guide

Generate videos, images, voice, and music from your terminal with PixVerse.