PixVerse CLI

对于开发者和 AI 智能体构建者来说，创意工作流中最大的痛点往往是上下文切换：为了生成一张图或一段视频，不得不离开代码编辑器，打开浏览器，手动点击网页界面。

PixVerse CLI 正是为了解决这一摩擦而生。作为 PixVerse 的官方命令行工具，它将文生视频、图生视频、文生图、唇音同步、音效生成及超分辨率等所有能力，全部转化为可脚本化、可管道化、可被 AI 智能体直接调用的终端命令。

核心优势：为 AI 智能体原生设计

PixVerse CLI 不仅仅是一个包装器，它的设计哲学完全围绕自动化展开：

• 结构化输出：所有命令默认支持 --json 标志，输出机器可读的 JSON 数据（包含 ID、状态、URL 等），便于下游程序解析。
• 确定性退出码：每个错误都有明确的退出码（如 3 代表认证过期，4 代表点数不足），让智能体能精准判断并执行重试或报错逻辑。
• 零 API 密钥管理：采用基于浏览器的 OAuth 登录，令牌自动存储在本地 (~/.pixverse/)，无需在环境变量中硬编码敏感信息。
• 技能生态 (Skills)：提供标准化的 "PixVerse Skills" 文件，可直接教会 Claude Code、Cursor 等智能体如何正确调用 CLI，实现自然语言驱动媒体生成。

本指南将带你完成完整的旅程：从安装到首次生成，然后进入多步骤自动化流水线和智能体原生工作流程。

前提条件

开始之前，你需要：

• Node.js 20 或更高版本 — 使用 node --version 检查
• 一个 PixVerse 账户 — 在 pixverse.ai 注册
• 一个有效的 PixVerse 订阅 — CLI 使用与网站相同的点数系统；只有订阅用户才能生成内容

PixVerse CLI 不需要手动复制任何 API 密钥。认证通过基于浏览器的 OAuth 流程处理，该流程会在本地存储你的令牌。

步骤 1：安装 CLI

使用 npm 全局安装：

npm install -g pixverse

验证安装：

pixverse --version

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

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

步骤 2：认证

运行登录命令：

pixverse auth login

CLI 将打印一个简短的 URL 和一个代码。在浏览器中打开该 URL，输入代码，并使用你的 PixVerse 账户授权。你的令牌会自动存储在 ~/.pixverse/ 中，有效期为 30 天。

验证登录状态并检查可用点数：

pixverse auth status
pixverse account info

account info 命令会显示你的订阅等级、剩余点数以及每日点数重置计划。在运行批处理作业之前，务必检查你的余额。

步骤 3：生成你的第一张图像

文生图是测试设置的最快方式。运行：

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

--json 标志返回结构化输出：

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

要获得更高分辨率的输出，可以指定支持它的模型：

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

PixVerse 支持多种图像模型，每种模型都有不同的分辨率上限和优势：

下载生成的图像：

pixverse asset download 789012

步骤 4：生成你的第一段视频

文生视频的工作方式相同。生成一个 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 v5.6 \
  --quality 1080p \
  --aspect-ratio 16:9 \
  --duration 8 \
  --audio \
  --json

--audio 标志启用 AI 生成的氛围音，匹配你的视频内容。--json 标志在完成时返回一个 video_url，你可以直接将其传递给下载命令或流水线中的下一步。

PixVerse 提供多种具有不同能力的视频模型：

让静态图像动起来

要将照片或生成的图像转换为视频，提供 --image 标志：

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

你可以传递本地文件路径或 URL。本地文件会自动上传——无需手动上传步骤。

步骤 5：运行交互式向导

如果你是首次探索，还不熟悉所有可用的标志，可以不带参数运行任何创建命令以进入引导式向导：

pixverse create video
pixverse create image

向导会逐步引导你完成提示词、模型选择、质量、宽高比、时长和其他选项——在编写脚本之前，这对于发现可用的参数非常有用。

教会你的 AI 智能体生成媒体

这就是 PixVerse CLI 真正具有变革性的地方。由于每条命令都返回结构化的 JSON 并使用确定性的退出码，任何能够运行 shell 命令的 AI 智能体都可以被教会按需生成图像和视频。

安装 PixVerse Skills

PixVerse Skills 是一个结构化的技能文件库，它能精确地教会智能体如何使用 CLI：每条命令接受哪些标志、哪些模型支持哪些参数、如何将命令链成流水线，以及如何处理错误。

对于支持技能格式的 Claude Code 和其他智能体，可以直接添加 PixVerse 技能：

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

对于 Cursor，技能位于 PixVerse Skills GitHub 仓库的 skills/ 目录中，可以作为上下文直接加载到你的编辑器中。对于基于 Codex 和 LangChain 的智能体，每个技能文件都是独立的 Markdown 文档，可以注入到智能体的系统提示词中。

一旦你的智能体加载了 PixVerse 技能，你就可以给它自然语言指令，例如：

• "根据这张截图生成一个 10 秒的产品演示视频"
• "为这篇博客封面创建四种 16:9 格式的变体"
• "将此图表制作成一个带环境音的 5 秒解说片段动画"

智能体将这些指令转换为正确的 CLI 命令，解析 JSON 输出，并处理轮询和下载——无需人工干预。

Claude Code

在 Claude Code 中，PixVerse CLI 成为智能体自主使用的原生工具。加载 PixVerse 技能后，你可以在任何任务中直接包含媒体生成：

为这篇关于机器学习的博客文章生成一张封面图，
使用 seedream-5.0-lite 模型，1800p 分辨率，16:9 格式，
下载到 ./assets/cover.webp

Claude Code 将调用正确的 CLI 命令，从 JSON 响应中解析图片 URL，并将文件下载到你指定的路径——所有这些都在它编写代码的同一个会话中完成。

一个典型的 Claude Code 工作流程：

# Claude Code 根据你的指令自主运行
IMG=$(pixverse create image \
  --prompt "Abstract visualization of neural network layers, dark background, blue and purple tones" \
  --model seedream-5.0-lite \
  --quality 1800p \
  --aspect-ratio 16:9 \
  --json | jq -r '.image_url')

# 然后将其动画化
pixverse create video \
  --prompt "Slow pan across glowing neural connections" \
  --image "$IMG" \
  --model v5.6 \
  --quality 1080p \
  --duration 6 \
  --json

Cursor

Cursor 用户可以将 PixVerse Skills 作为项目上下文文件加载。将相关的技能文件放入你的 .cursor/ 目录，或添加到你的工作区规则中。加载后，Cursor 完全了解所有 PixVerse CLI 命令，并可以在任何编码任务中生成媒体。

一个常见的 Cursor 工作流程：让智能体根据你正在构建的设计生成一个模拟图像，然后直接在 IDE 会话中将其用作参考——无需离开编辑器。

Codex 和其他智能体

PixVerse CLI 兼容任何能够执行 shell 命令和解析 JSON 的智能体。结构化输出格式——一致的字段名、可预测的错误码以及通过 stderr 分离的错误消息——确保即使是简单的脚本智能体也能可靠地集成生成功能。

退出码契约使错误处理变得简单明了：

自动化流水线

一旦你理解了各个命令，PixVerse CLI 就能解锁强大的多步骤工作流程，完全无需用户交互即可运行。

文本到图像到视频

最有用的流水线之一：从文本提示生成高分辨率图像，然后将其制作成动画视频。

# 步骤 1：生成基础图像
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')

# 步骤 2：将其制作成动画视频
VID_RESULT=$(pixverse create video \
  --prompt "Camera slowly pans across the neon-lit streets" \
  --image "$IMAGE_URL" \
  --model v5.6 \
  --quality 1080p \
  --duration 8 \
  --json)

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

# 步骤 3：下载最终视频
pixverse asset download "$VIDEO_ID" --json

完整视频制作流水线

为了获得更精致的输出，可以将生成与后期处理步骤链接起来：

# 步骤 1：创建基础视频
RESULT=$(pixverse create video \
  --prompt "A product being assembled in slow motion" \
  --model v5.6 \
  --quality 720p \
  --duration 5 \
  --json)
VID=$(echo "$RESULT" | jq -r '.video_id')

# 步骤 2：延长时长
EXTENDED=$(pixverse create extend \
  --video "$VID" \
  --prompt "Continue the assembly sequence" \
  --duration 5 \
  --json | jq -r '.video_id')
pixverse task wait "$EXTENDED" --json

# 步骤 3：添加环境音
WITH_SOUND=$(pixverse create sound \
  --video "$EXTENDED" \
  --prompt "Industrial workshop ambience, soft mechanical sounds" \
  --json | jq -r '.video_id')
pixverse task wait "$WITH_SOUND" --json

# 步骤 4：提升至 1080p
FINAL=$(pixverse create upscale \
  --video "$WITH_SOUND" \
  --quality 1080p \
  --json | jq -r '.video_id')
pixverse task wait "$FINAL" --json

# 步骤 5：下载
pixverse asset download "$FINAL" --json

批量生成

对于需要多个变体的内容流水线，可以并行运行作业：

# 首先检查点数
CREDITS=$(pixverse account info --json | jq -r '.credits.total')
echo "Available credits: $CREDITS"

# 提交四个并行生成任务
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

# 等待每个任务完成并下载
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，允许你在轮询之前提交多个作业。pixverse task wait 命令为你处理自适应轮询——无需手动 sleep 循环。

配置默认值

如果你始终使用相同的模型、质量或宽高比，可以将它们设置为默认值，这样就不必每次都重复标志：

pixverse config defaults set --mode video --model v5.6 --quality 1080p --aspect-ratio 16:9
pixverse config defaults set --mode image --model seedream-5.0-lite --quality 1800p
pixverse config set output-dir ~/Downloads/pixverse

命令行标志总是覆盖你配置的默认值，因此你可以在减少重复的同时保持完全的灵活性。

你可以构建什么

将 PixVerse CLI 集成到你的智能体工作流程中后，可自动化任务的范围显著扩大：

• 文档 — 在文档构建过程中自动生成产品演示视频和截图
• 市场营销 — 运行夜间批处理作业，从单个提示库生成社交媒体内容变体
• 应用开发 — 让你在构建 UI 的同时，让编码智能体生成占位视觉效果、模拟动画或加载屏幕视频
• 内容流水线 — 将 CLI 调用与其他工具（ffmpeg、ImageMagick、云存储）链接起来，构建完全自动化的媒体制作工作流程
• 原型设计 — 在投入完整制作之前，几秒钟内生成快速动态概念以验证想法

CLI 旨在自然适应任何基于 shell 的工作流程。如果你现有的自动化运行在 bash、Python、Node 或 CI/CD 流水线中，PixVerse CLI 可以无缝接入，无需额外的集成开销。

入门检查清单

•  安装 Node.js 20 或更高版本
•  运行 npm install -g pixverse
•  运行 pixverse auth login 并在浏览器中授权
•  运行 pixverse account info 验证点数
•  生成你的第一张图像：pixverse create image --prompt "..." --json
•  生成你的第一段视频：pixverse create video --prompt "..." --json
•  为你的智能体安装 PixVerse Skills（Claude Code、Cursor 或 Codex）
•  使用 pixverse config defaults set 设置你偏好的默认值
•  构建你的第一个自动化流水线

下一步

npm 上的 PixVerse CLI（npm install -g pixverse）让你立即访问所有生成能力。PixVerse Skills 仓库提供结构化的技能文件，教会你的 AI 智能体如何在任何上下文中正确使用这些能力。

一个可靠的 CLI 和一个为智能体准备的技能库的结合意味着，图像和视频生成现在可以与你的代码存在于同一个工作流程中——由同一个智能体在同一个终端中管理，无需切换工具。

从一个命令开始。由此构建。