PixVerse CLI：在终端中生成 AI 视频和图像

核对日期：2026-10-13。需要 Node.js >=22.12。默认图像模型为 GPT Image 2.5 Flare，默认视频模型为 PixVerse V6。模型支持与参数因生成模式而异；正式生成前请查询已安装版本的 capabilities 和官方 README。 README · capabilities.json

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

简介

基于浏览器的生成界面适合探索和一次性项目，但有几种场景需要不同的处理方式：

PixVerse CLI 把 AI 视频、图像、语音和音乐生成直接带入了终端工作流。你不再需要在浏览器界面和开发环境之间来回切换，而是可以在编写代码、执行构建、管理部署的同一个命令行里创建、管理和下载 AI 内容。 PixVerse CLI

PixVerse CLI 正是围绕这份清单打造的，并且特别侧重智能体驱动的场景：命令返回结构化 JSON，退出码可预测，每一步都被设计成可以由脚本或自主智能体组合调用，而不是依赖人工点击界面。

前置条件

开始之前，你需要：

Node.js 22.12 或更高版本 —— 使用 node --version 检查
一个 PixVerse 账户 —— 前往 pixverse.ai 注册
有效的 PixVerse 订阅 —— CLI 使用与官网相同的积分系统，因此生成内容需要订阅账户

无需手动复制粘贴 API 密钥。身份验证通过浏览器完成，并将凭证保存在本地。

安装

使用 npm 全局安装 CLI：

npm install -g pixverse

确认安装成功：

pixverse --version

如果不想全局安装，也可以按需通过 npx 运行命令：

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

身份验证

使用以下命令登录：

pixverse auth login

这会打开浏览器窗口进行 OAuth 授权。如果你在通过 SSH 操作或使用无图形界面的机器，登录流程也会给出一个链接，你可以在任意设备的浏览器中打开它完成授权。授权完成后，令牌会保存到 ~/.pixverse/，有效期为 30 天。

检查登录状态和可用积分：

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

account info 会显示你的订阅等级和工作区积分。account usage 详细列出积分消耗情况，account slots 则告诉你可以并发运行多少个生成任务——在启动批量任务前值得先查一下。CLI 会话与浏览器或应用会话互不共享状态，因此退出 CLI 登录（pixverse auth logout）不会影响你的其他会话。

快速开始

如果你只想以最快的方式从零安装到生成第一份成品，可以按以下顺序操作：

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

对于脚本和智能体场景，请始终开启 --json（或其简写 -p），这样标准输出会保持干净、可解析，而进度信息和错误则会输出到 stderr。如果某个任务可能被重复提交——比如网络不稳定或 CI 步骤重试——可以加上 --idempotency-key <key>，避免因重复提交而被重复扣费。

生成图像

文生图是验证环境是否配置正确的最快方式：

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

目前默认的图像模型是 GPT Image 2.5 Flare，但对于任何计划反复运行的任务，建议显式设置 --model，而不是依赖默认值——默认模型会随着新模型上线而变化。--json 会返回可以直接传入下一步的响应：

{
  "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
}

如需更高分辨率，可以选用支持该分辨率的模型：

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

图像模型阵容覆盖了多种不同的使用场景：

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

你也可以把已有图像重新输入并进行转换：

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

然后将文件下载到本地：

pixverse asset download 789012 --type image

生成视频

文生视频的流程与图像生成类似。快速生成一段 5 秒的短片：

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

或者进行完整参数配置：

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

仅在支持原生音频的模型上：--audio 会添加与画面相匹配的 AI 生成环境音。生成完成后，JSON 响应中会包含 video_url，你可以直接传给下载步骤或流水线的下一环节。

不同视频模型在分辨率上限、时长范围以及所支持的生成模式方面差异很大：

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

Seedance、Kling、Veo、Sora、Gemini Omni、Grok Imagine 和 HappyHorse 等合作模型也是 PixVerse 上的选项。可通过同一 CLI 与 PixVerse V6、C1 进行对比。

让静态图像动起来

传入 --image 参数即可把一张照片或生成的图像变成视频：

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

--image 既可以指向本地文件路径，也可以指向远程 URL——本地文件会自动上传，无需单独的上传步骤。任何超过 1920×1920 或 5MB 的图像都会在上传前自动调整大小或压缩；远程 URL 则会按原样由后端校验。

Grok Imagine 1.5 是一个特殊情况：它要求必须传入 --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

参考、转场、动作控制与模板

除了简单的文生视频和图生视频之外，CLI 还提供了几种更专业的生成模式，适用于需要对角色、关键帧或特效进行更精细控制的场景：

# 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

生成语音和音乐

独立的音频生成由两个专用命令提供：create voice 用于文本转语音，create music 用于提示词驱动的音乐生成。二者的输出都会保存为音频资产，因此可以用 task 追踪进度，用 asset list --type audio 列出，用 asset download 下载。如果你只是想给视频加上环境音，请在支持的视频生成命令上使用 --audio / --no-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

在正式使用某个模型之前，先列出可用的语音模型和预设音色：

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

生成一段音乐：

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

添加 --instrumental 可以生成无人声的纯音乐。如果需要指定歌词，--lyrics 支持接收字面文本、本地文件路径，或通过管道传入的标准输入：

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

目前的语音选项涵盖 MiniMax Speech 2.8 和 ElevenLabs 系列，音乐生成则来自 MiniMax Music、ElevenLabs Music 和 Google Lyria 3 Pro。由于这些模型阵容会随时间变化，在编写可复用脚本之前，建议先运行 pixverse voice models 和 pixverse music models 查看当前可用的模型。

交互式向导

如果你还在熟悉有哪些参数可用，可以不带任何参数直接运行生成命令：

pixverse create video
pixverse create image

这会进入一个引导式向导，逐步引导你完成提示词、模型、质量、宽高比、时长以及其他相关选项的设置——是在正式写入脚本前发现可用参数的好方法。

管理资产和工作区

生成只是整个体验的一部分。CLI 还提供了围绕生成流程的管理命令：

pixverse task status <id> 和 pixverse task wait <id> 用于轮询单个任务
pixverse task status --ids 123,456,789 --type video --json 可以在一次调用中检查多个任务
pixverse asset list、asset upload、asset info、asset download 和 asset delete 涵盖视频、图像和音频资产的全生命周期操作
pixverse saved list、saved items、saved new、saved rename、saved add、saved remove 和 saved delete 用于管理收藏文件夹
pixverse template categories、template list、template search 和 template info 用于浏览特效和模板
pixverse voice models、voice presets 和 music models 用于实时发现可用的音频模型
pixverse workspace list、workspace status、workspace switch 和 workspace manage 用于多工作区场景
pixverse account info、account usage 和 account slots 用于检查积分、用量和并发情况
pixverse config set、config list、config path 和 config defaults 用于设置可复用的本地默认值

有了这些命令，一个脚本就可以处理内容创建、组织整理、模板发现、下载以及工作区路由，全程无需离开终端。如果某次调用需要指向默认工作区以外的其他工作区，可以加上 --workspace-id <id>（0 表示个人工作区）。

Canvas 项目与当前模型支持

CLI 现已提供 Canvas 项目、图结构、节点、补丁和调度工作流。编写项目自动化之前，请查看 pixverse canvas --help 和 pixverse capabilities canvas --json。Canvas 能力从服务端实时获取，需要登录；生成能力来自已安装的 CLI。若目录缺少所需模型，请先更新 CLI。

当前目录包括 Seedance 2.5、MiniMax H3/H3 Max、FLUX 3、Wan 3.0、Kling 4K、GPT Image 2.5 Flare/Sunburst 和 Nano Banana 2.1。请按具体模型与模式查询能力，不要沿用另一模型的时长、音频、参考素材或分辨率设置。

值得了解的脚本化参数

自动化场景下，可预测的输出比任何东西都重要。以下这些参数在脚本和智能体工作流中会频繁用到：

参数	用途
`--json`	返回结构化 JSON 输出
`-p`	`--json` 的简写形式
`--count <n>`	从单次请求生成 1–4 个变体
`--seed <number>`	让生成结果更易复现
`--off-peak`	在可用时使用非高峰定价
`--audio` / `--no-audio`	在支持的视频生成命令上切换音频
`--multi-shot` / `--no-multi-shot`	切换视频的多镜头模式
`--no-wait`	提交任务后立即返回，而不阻塞等待
`--timeout <sec>`	设置轮询超时时间（默认 300 秒）
`--workspace-id <id>`	为单次命令覆盖当前活动工作区
`--trace-id <uuid>`	为请求附加调用方提供的 UUIDv4，便于调试
`--idempotency-key <key>`	安全地重试生成请求，避免重复扣费

文本输入类参数现在可以接受不仅仅是内联字符串。--prompt、--text 和 --lyrics 都可以接收字面字符串、本地文件路径，或使用 - 从标准输入读取：

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

教你的 AI 智能体生成媒体内容

若希望先在应用内体验智能体创作，再进行命令行自动化，可从 PixVerse Agent 开始。

这正是 CLI 从便利工具跃升为能力倍增器的地方。由于每个命令都返回结构化 JSON，并以确定性的退出码结束，任何能够执行 shell 命令的智能体都可以被训练来代替你生成图像、视频、语音和音乐。

安装 PixVerse Skills

PixVerse Skills 是一个专门打造的技能库，用于教智能体掌握 CLI 的参数、模型限制、多步骤流水线以及错误处理模式，而不是让智能体自己从帮助文本里瞎猜。

对于 Claude Code 和其他支持技能格式的工具：

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

加载完成后，智能体就拥有了明确的约束条件，而不必靠试错来推断行为——这对 Cursor、Claude Code、Codex 等框架中的可靠性至关重要。

加载了 PixVerse Skills 之后，你可以给智能体下达这样的自然语言指令：

“根据这张截图生成一段 10 秒的产品演示视频”
“为这张博客封面图生成四个 16:9 格式的变体”
“把这张图表动画化成一段带环境音的 5 秒讲解短片”
“生成三段不同运镜方式的 8 秒 16:9 宣传短片”

智能体会把这些指令转化为正确的 CLI 调用，解析 JSON 响应，处理轮询并下载结果——中间不需要任何人工介入。

Claude Code

在 Claude Code 中，CLI 会成为智能体自主使用的工具。加载 PixVerse Skills 之后，你可以把媒体生成融入任何任务中：

为这篇机器学习博客生成封面图，使用 seedream-5.0-lite 模型，以 2160p、16:9 输出，并下载到 ./assets/cover.webp。

Claude Code 会运行正确的命令，从 JSON 中提取图像 URL，并将文件保存到你指定的路径——所有这些都发生在它同时编辑你代码的同一个会话中。

一个典型的工作流示例：

# 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 用户可以将相关 PixVerse Skills 文件放入 .cursor/ 目录，或添加到工作区规则中。加载后，智能体可依据 CLI 指南在编码任务中生成媒体。

例如，可以让 Cursor 为正在开发的设计生成模拟图，并直接在同一编辑器会话中将其用作参考。

Codex 及其他智能体

任何能够执行 shell 命令并解析 JSON 的智能体都可以驱动这个 CLI。一致的字段命名、可预测的错误码，以及独立输出在 stderr 上的错误信息，意味着即便是简单的脚本化智能体也能顺利集成生成功能，无需做特殊处理。

退出码为智能体提供了清晰的决策路径：

代码	含义	智能体应采取的行动
0	成功	解析 JSON 输出
1	一般错误	检查 stderr 并使用校验后的输入重试
2	超时	使用更长的 `--timeout` 重试
3	授权过期	重新执行 `pixverse auth login`
4	积分不足	检查余额并通知用户
5	生成失败	尝试不同的参数
6	校验错误	检查参数取值
7	并发限制	等待可用任务槽位后重试

自动化流水线

一旦熟悉了各个独立命令，真正的价值就会体现在那些无需人工值守就能运行的多步骤流水线中。

文生图再生成视频

生成一张高分辨率图像，然后将其动画化：

# 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

完整视频制作流水线

如果想要更精致的成品，可以把生成与后期处理串联起来。当支持的视频模型自带的原生音效已经足够时，使用 --audio 或 --no-audio；当你需要一份独立的音频资产用于后续合成时，使用 create voice 或 create music：

# 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

批量生成

对于需要同时生成多个变体的内容流水线，可以并发运行任务，而不是逐一串行处理：

# 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

--no-wait 会在提交任务后立即返回任务 ID，让你可以先排队提交多个任务，再统一进行轮询。记录每次 --no-wait --json 响应中的任务 ID 和已解析的参数——这份记录正是让批量任务日后可复现的关键。当需要从单个提示词生成多个变体时使用 --count <n>；当你希望用一次状态查询覆盖多个正在运行的任务，而不是逐一轮询时，使用批量的 task status --ids。pixverse task wait 会自动为你处理自适应轮询。

配置默认值

如果你发现自己在每次调用中都在重复设置同样的模型、质量或宽高比，不妨一次性设置好：

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

命令行中的参数始终优先于已配置的默认值，因此设置默认值并不会牺牲任何灵活性。如果某次运行需要针对非默认工作区，可以在默认设置之上再加上 --workspace-id <id>。

你可以构建什么

把 CLI 接入智能体或脚本之后，能实现的自动化范围相当广泛：

文档编写 —— 在文档构建流程中自动生成产品演示视频和截图
营销 —— 每晚运行批量任务，从一个提示词库生成多种社交媒体内容变体
应用开发 —— 让编码智能体在你构建实际界面的同时，生成占位视觉素材、模拟动画或加载页面视频
音频工作流 —— 生成配音草稿、提示词转音乐曲目，或用于后期编辑的独立音频资产
内容流水线 —— 将 CLI 调用与 ffmpeg、ImageMagick 或云存储工具串联，构建完全自动化的制作流水线
原型验证 —— 几秒钟内生成快速的动态概念，在投入完整制作之前先验证想法

由于本质上只是 shell 命令，这个 CLI 可以无缝嵌入 bash、Python、Node 或 CI/CD 流程，无需任何额外的集成工作。

快速上手清单

保持 CLI 最新

使用内置更新命令保持本地 CLI 为最新版本：

pixverse update

也可以直接通过 npm 更新：

npm install -g pixverse@latest

模型和参数的变化速度往往比大多数文档都快，因此对于发布级别的变更，请直接查看官方来源：

截至本次更新，PixVerse V6 仍是默认视频模型，GPT Image 2.5 Flare 仍是默认图像模型，同时 Seedance 2.0 Mini、专用的 create voice/create music 命令、音频资产管理、收藏文件夹、工作区切换、config defaults、capabilities.json 清单、pixverse update、文本输入的标准输入支持，以及 --trace-id 和 --idempotency-key 都已成为当前工具集的一部分。 PixVerse CLI

CLI 带来的可能性

PixVerse CLI、GitHub 仓库和 npm（npm install -g pixverse）提供生成、任务查询、资产、模板、语音、音乐与工作区管理。PixVerse Skills 为智能体补充使用指南。

CLI 与智能体技能结合后，图像、视频、语音和音乐可由同一个智能体在同一终端中处理，并融入代码工作流。

先完成一条命令，再逐步构建流水线。