vhscli

vhscli

vhscli 是一款多模态 AI 命令行工具：可针对文本、图片、视频和 PDF 进行对话，也可根据提示词生成图片、视频和音频。 它是一个轻量客户端——身份验证、上传和模型执行都在服务端完成，因此用户无需在本地存储任何服务商 API 密钥。

运行 vhscli --help 或 vhscli <command> --help 查看当前帮助信息——CLI 是唯一可信的信息来源。

调用方式

始终通过 npx @getvhs/vhscli@latest 运行，以获取最新的模型、标志和修复。不要固定版本，也不要直接调用 vhscli 二进制文件，即使它已位于 PATH 中——它可能不是最新版本。

npx @getvhs/vhscli@latest <command> ...

为便于阅读，本文中的命令均写作 vhscli ...——运行时请替换为 npx @getvhs/vhscli@latest ...。

需要 Node.js ≥ 24。

顶层命令

vhscli [-v|--version] [-h|--help]
vhscli <command> [options] ...

• -v、--version — 打印版本（仅在未提供命令时生效）
• -h、--help — 显示帮助（根命令和所有子命令均适用）

命令：

• login — 使用 google 登录（打开浏览器；将会话保存到 ~/.vhs/session.json）
• logout — 退出登录并删除本地访问令牌
• whoami [--json] — 打印已登录用户的姓名和电子邮件（读取本地数据；不联网）。普通输出：Name <email>；--json：每行一个事件
• account [--json] — 显示电子邮件和余额（会访问后端）。普通输出：先显示电子邮件，再显示 balance: $X.XX
• models — 列出可用模型
• generate <model> <prompt> -o <path> — 生成图片、视频或音频，等待完成并保存（必须提供 -o）
• submit <model> <prompt> -o <path> — 提交与 generate 相同的任务后立即退出，并打印任务 ID；稍后使用 resume 完成任务
• chat <prompt> — 与 seed-2.0 / a2:seed-2-pro 对话（输入可以是文本、图片、视频或 PDF）
• resume <task_id> -o <path> — 等待一个任务完成并写入其输出
• poll - — 监听来自 stdin 的任务 ID；首个任务完成后打印结果并退出（不写入文件）
• save <task_id> -o <path> — 写入已完成任务的输出（不会等待）

CLI 不在本地存储任何内容：任务保存在 VHS 后端中，任务 ID 是访问任务的唯一凭据。没有项目、数据库或配置——请参阅下文的“任务追踪方式”。

在 generate / submit / resume / save / poll / whoami / account 中使用 --json，会将 NDJSON 事件输出到 stdout，并将普通日志重定向到 stderr（请参阅下文的“--json”）。

身份验证

假设身份验证已配置。如果命令因身份验证错误而失败，请运行 vhscli login，打开浏览器进行 Google OAuth 登录。不要提前运行 vhscli login——该命令需要通过交互式浏览器登录。

模型

• 对话 / 理解（文本 / 图片 / 视频 / PDF）：seed-2.0 （在 vhscli chat 中为 a2:seed-2-pro）
• 生成图片：seedream-5（默认）、seedream-5-pro、 nano-banana-2、nano-banana-pro、gpt-image-2——通过 vhscli generate 使用
• 生成视频：seedance-2（最高 4k）、seedance-2.5（最高 720p）—— 通过 vhscli generate 使用
• 生成音频：seed-audio-1——通过 vhscli generate 使用

提示词指南

调用 vhscli generate（或使用 vhscli chat 进行非简单理解任务）之前，先阅读对应的提示词指南，并据此组织提示词。这些指南简明扼要，针对特定模型，从各提供商的文档中提炼而来，涵盖公式、提示词的开头内容、有效做法和无效做法。适用于一个模型的措辞，用在另一个模型上往往效果不佳，所以不要跳过这一步。

模型	指南文件（提示前阅读）
seed-2.0（由 vhscli chat 使用）	prompt_guide/seed-2.txt
seedream-5、seedream-5-pro	prompt_guide/seedream.txt
nano-banana-2、nano-banana-pro	prompt_guide/nano-banana.txt
seedance-2、seedance-2.5	prompt_guide/seedance-2.txt
gpt-image-2	prompt_guide/gpt-image-2.txt

触发条件：用户要求使用上述任一模型生成输出时，先阅读其指南，再编写提示词。对于简单聊天（纯文本问答，不涉及媒体），可以跳过 seed-2.txt。

标准输入提示词

所有接受提示词的命令也支持将 - 作为提示词，表示“从标准输入读取”：

cat my_prompt.txt | vhscli generate nano-banana-pro - -o out.png
echo "what is this?" | vhscli chat - -i photo.jpg

---

vhscli chat — 聊天讨论文本、图像、视频或 PDF

vhscli chat <prompt> [-i <image>...] [-f <pdf>...] [-v <video>] [--fps <n>]

模式由你传入的标志决定：

• 仅提示词 → 文本聊天
• -i → 询问图像相关问题（可重复使用）
• -f → 询问 PDF 文档相关问题（可重复使用）
• -v → 询问单个视频相关问题

选项：

• -i <path> — 要询问的图像（可重复使用 -i 添加更多图像）
• -f <path> — 要询问的 PDF 文档（可重复使用 -f 添加更多文档）
• -v <path> — 单个要询问的视频
• --fps <n> — 从视频中采样的帧数/秒，范围为 0.2–5（默认值：1）

单次调用 — 每次调用相互独立，不会记住之前的调用。输出发送到 stdout，不会保存到磁盘。无法理解视频中的音频。

示例：

vhscli chat "explain how to make sourdough in 5 steps"
vhscli chat "describe the scene. return json with objects, setting, mood." -i photo.jpg
vhscli chat "transcribe all visible text verbatim, preserving line breaks." -i receipt.jpg
vhscli chat "compare image 1 and image 2 in 3 bullets." -i a.jpg -i b.jpg
vhscli chat "summarize this paper in 5 bullets; include a page number per bullet." -f paper.pdf
vhscli chat "list key events with start_time and end_time in HH:mm:ss as json." -v clip.mp4 --fps 2

---

图像模型 — 通用 --size

所有图像模型都使用一个标志指定画幅：

--size <width>x<height>   # default: 1920x1080

一个值同时表示宽高比和分辨率，并且在所有模型中都代表相同的画幅。示例：1920x1080、1024x1024、1080x1920、3840x2160。

CLI 仅检查格式：每条边的范围为 64–4096。后端会将尺寸适配到提供商的要求 — 画幅不会因无法渲染而被拒绝，但返回结果可能有所不同：

模型	尺寸处理方式
gpt-image-2	将两条边调整为 16 的倍数，像素总数限制在 655360–8294400 之间，最长边最大为 3840，宽高比不超过 3:1
seedream-5、seedream-5-pro	将尺寸缩放到 3686400–10404496 像素 — 最低分辨率高于 2K，因此小尺寸画幅会被放大（例如，960x540 → 约 2560x1440）
nano-banana-2、nano-banana-pro	将尺寸四舍五入到最接近的宽高比及最接近的 1K/2K/4K 档位

输出格式由 -o 扩展名决定（.png、.jpg/.jpeg、.webp）；如有需要，CLI 会进行转换。

---

vhscli generate seedream-5 — 生成图像（默认选择）

vhscli generate seedream-5 <prompt> -o <path> [-i <image>...] [--size <WxH>]

选项：

• -o、--output <path> — 输出文件路径，必填（例如 out.jpg）
• -i <path> — 参考图像，最多 14 张（可重复使用 -i 添加更多图像）
• --size <WxH> — 像素尺寸（默认值：1920x1080）；参见通用 --size

示例：

vhscli generate seedream-5 "a red fox in a snowy forest" -o fox.jpg
vhscli generate seedream-5 "swap the outfit" -o out.png -i person.jpg -i outfit.jpg --size 2048x2048

---

vhscli generate seedream-5-pro — 生成图像（Seedream 5.0 专业版）

vhscli generate seedream-5-pro <prompt> -o <path> [-i <image>...] [--size <WxH>]

标志和提示词指南与 seedream-5 相同，但这是专业版：提示词遵循度更高、细节更精细，不过每张图像大约需要 2 分钟，而非几秒。默认优先使用普通版 seedream-5；用户要求最高品质时，或复杂提示词让 seedream-5 一再遗漏细节时，再选择 seedream-5-pro。-o 优先使用 .png（其他扩展名也可使用 — CLI 会进行转换）。

示例：

vhscli generate seedream-5-pro "a lone lighthouse on a cliff at dusk, long exposure, crashing surf" -o lighthouse.png
vhscli generate seedream-5-pro "add a flock of birds across the sky, keep the style" -i scene.png -o birds.png

由于生成速度较慢，生成多张图像时很适合搭配使用 vhscli submit（见下文）：先全部提交，然后逐个 poll + save（或 resume）。

---

vhscli generate nano-banana-2 — 生成图像（Google）

vhscli generate nano-banana-2 <prompt> -o <path> [-i <image>...] [--size <WxH>]

选项：

• -o、--output <path> — 输出文件路径，必填（例如 out.png）
• -i <path> — 参考图像，最多 14 张（重复使用 -i 可添加更多）
• --size <WxH> — 像素尺寸（默认：1920x1080）；将按最接近的 21:9/16:9/3:2/4:3/5:4/1:1/4:5/3:4/2:3/9:16 比例提供， 并采用最接近的 1K/2K/4K 分辨率

示例：

vhscli generate nano-banana-2 "remove the man from the photo, keep everything else" -i photo.jpg -o clean.png
vhscli generate nano-banana-2 "90s skateboarder poster, vertical composition" -o poster.png --size 1080x1920
vhscli generate nano-banana-2 "a glossy candle in a bell jar on a marble counter, soft light" -o candle.png

---

vhscli generate nano-banana-pro — 生成图像（Google，高级版）

vhscli generate nano-banana-pro <prompt> -o <path> [-i <image>...] [--size <WxH>]

尺寸设置和标志与 nano-banana-2 相同。更高质量的同系列模型——文本渲染效果更好，纹理也更丰富。

示例：

vhscli generate nano-banana-pro "studio portrait, cinematic lighting, three-quarter framing" -o portrait.jpg --size 1536x2048
vhscli generate nano-banana-pro "a sun-drenched minimalist living room with a 3d armchair from this sketch" -i sketch.jpg -o room.png

---

vhscli generate gpt-image-2 — 生成或编辑图像（OpenAI）

vhscli generate gpt-image-2 <prompt> -o <path> [-i <image>...] [--size <WxH>]

选项：

• -o、--output <path> — 输出文件路径，必填（例如 out.png）
• -i <path> — 用于编辑的参考图像（重复使用 -i 可添加更多）
• --size <WxH> — 像素尺寸（默认：1920x1080）；参见共享的 --size

需要透明背景时，请使用 png 或 webp。

示例：

vhscli generate gpt-image-2 "a children's book drawing of a veterinarian examining a cat" -o vet.png
vhscli generate gpt-image-2 "replace the background with a starry night, keep the subject unchanged" -i photo.jpg -o night.png
vhscli generate gpt-image-2 "ultra-wide landscape of the swiss alps at golden hour" --size 3840x2160 -o alps.jpg

---

vhscli generate seedance-2 — 生成视频

vhscli generate seedance-2 <prompt> -o <path>
                           [--first-frame <image>] [--last-frame <image>]
                           [-i <image>...] [-v <video>...] [-a <audio>...]
                           [--ratio <r>] [--resolution <res>] [--duration <n>]
                           [--no-audio]

根据标志选择模式：

• 仅提供提示词 → 文本生成视频
• --first-frame → 根据该帧制作动画（也可选用 --last-frame）
• -i / -v / -a → 用作参考素材

选项：

• -o、--output <path> — 输出文件路径，必填（.mp4、.webm 或 .mov；建议使用 .mp4）
• --first-frame <image> — 用作首帧
• --last-frame <image> — 用作尾帧（需要 --first-frame）
• -i <path> — 参考图像，最多 9 张（重复使用 -i）。与 --first-frame 冲突
• -v <path> — 参考视频，最多 3 个（重复使用 -v）。与 --first-frame 冲突
• -a <path> — 参考音频，最多 3 个（重复使用 -a）。需要 -i 或 -v， 与 --first-frame 冲突
• --ratio <r> — 宽高比（默认：16:9）。可选：21:9、16:9、 4:3、1:1、3:4、9:16
• --resolution <res> — 480p、720p、1080p 或 4k（默认：720p）。 仅支持小写
• --duration <n> — 时长（秒），4–15（默认：5）
• --audio / --no-audio — 切换音轨（默认：--audio）。 传入 --no-audio 可生成静音视频

默认生成时长为 5s、分辨率为 720p、宽高比为 16:9，且包含音频。任务在云端运行，可能需要几分钟——CLI 会自动轮询。如果不想阻塞，可使用 vhscli submit seedance-2 ...（相同标志）立即分离任务，之后再使用 vhscli resume <task_id> -o cat.mp4（submit 会打印任务 ID）。在轮询期间中断的 vhscli generate 任务也可用同样的方式完成。

示例：

# text-to-video
vhscli generate seedance-2 "a cat jumping off a couch" -o cat.mp4 --duration 6 --ratio 16:9

# animate a still image
vhscli generate seedance-2 "camera pans right" -o pan.mp4 --first-frame start.jpg

# with a first and last frame
vhscli generate seedance-2 "morph between these" -o morph.mp4 --first-frame a.jpg --last-frame b.jpg

# reference-based with audio
vhscli generate seedance-2 "lip sync the words" -o out.mp4 -i face.jpg -a voice.mp3

---

vhscli generate seedance-2.5 — 生成视频（最高支持 720p）

vhscli generate seedance-2.5 <prompt> -o <path>
                             [...same flags as seedance-2 except --resolution]

模型支持的参数与 seedance-2 相同（比例、时长、首帧/尾帧、参考素材、 音频），但 --resolution 仅接受 480p 或 720p（默认：720p）。 如需 1080p / 4k，请使用 seedance-2。提示词指南与 seedance-2 相同。

示例：

vhscli generate seedance-2.5 "a woman in a red dress walks through a rainy neon-lit alley, slow tracking shot" -o alley.mp4
vhscli generate seedance-2.5 "animate this photo: gentle pan to the right" --first-frame photo.jpg -o pan.mp4

---

vhscli generate seed-audio-1 — 生成语音音频

vhscli generate seed-audio-1 <prompt> -o <path> [-i <audio>...]

选项：

• -o、--output <path> — 输出文件路径，必填（必须为 .mp3）
• -i <path> — 用于克隆或混合的参考语音片段，最多 3 段 （重复使用 -i 可添加更多）。每段时长应 ≤30s，且大小应 ≤10MB

输出始终为 mp3。

示例：

vhscli generate seed-audio-1 "Welcome to VHS." -o welcome.mp3
vhscli generate seed-audio-1 "Read this in the reference voice." -i voice.mp3 -o out.mp3
vhscli generate seed-audio-1 "Blend these voices." -i v1.mp3 -i v2.mp3 -o blend.mp3

---

如何跟踪任务——generate、submit、resume、poll 和 save 的共同点

一次生成在 VHS 后端中对应一行记录。CLI 不会写入数据库或旁置文件，因此任务 ID 是任务唯一的标识——丢失它，就会让你付费生成的内容无从找回。

• generate 会提交任务、等待完成，并保存到 -o。它会先打印 ID，因此运行中断后可以继续。
• submit 会打印 ID（task_id: <uuid>），然后退出，不会等待。它会验证 -o，但此时不会写入任何内容。
• resume <task_id> -o <path> 会等待一个任务，并写入其输出（一步完成 poll + save）。
• poll - 会从标准输入读取多个 ID 并持续监视，打印最先完成的任务。
• save <task_id> -o <path> 会写入已完成任务的输出；如果任务仍在运行，则会报错。

每个会写入文件的命令都必须指定 -o。任务记录了使用的模型和请求内容，但只有你知道文件应该保存在哪里。CLI 会严格写入 -o 指定的位置——不会更改保存位置或避免文件名冲突，因此如果不能覆盖文件，请先检查路径。

所有操作都以任务 ID 为键，并且是幂等的，所以如果命令中途失败，重新运行时会接入已有任务，而不是重复付费。需要在提交返回前记录 ID 时，可以使用 --task-id <uuid> 自行指定 ID。

vhscli chat 不需要跟踪任务——它运行很快，并将结果打印到标准输出。

---

vhscli submit——提交任务后退出（不等待）

vhscli submit <model> <prompt> -o <path> [...same flags as `vhscli generate <model>`]

submit 接受与 generate 相同的模型和选项（seedance-2、seedance-2.5、seedream-5、seedream-5-pro、nano-banana-2、nano-banana-pro、gpt-image-2、seed-audio-1）。唯一的区别是，后端接收任务后，submit 会打印 task_id: <uuid> 并退出，不会轮询。它会检查 -o，但要等到你恢复任务或保存结果时才会写入内容。

适用于以下情况：

• 任务耗时较长（例如 seedance 视频），你不想让终端一直处于阻塞状态。
• 你想并行提交多个任务，之后再获取结果（poll + save）。

请保存打印出的 ID。 如果只有一个任务，使用 vhscli resume <task_id> -o <path> 完成后续操作。如果有多个任务，请使用下方的 poll + save。这台机器不会替你记住任务信息。

使用 --task-id <uuid> 可以使用你指定的 ID 提交任务，而不是生成一个新 ID，这样你就能在提交返回前记下 ID。如果丢失 ID 会导致付费任务无法找回，请使用此选项：先生成 UUID 并保存，再提交任务。如果命令在打印任何内容前就退出，请重新运行完全相同的命令——后端记录和提交操作都以该 ID 为键且具有幂等性，因此重跑会接入同一任务，而不会启动第二个任务。

示例：

# kick off a video, get the terminal back, finish later
vhscli submit seedance-2 "a robot dancing in tokyo at night" -o robot.mp4
# prints: task_id: 7d3c1b2a-...
# ... do other work ...
vhscli resume 7d3c1b2a-... -o robot.mp4

# fan out several image jobs, then collect as they finish
vhscli submit seedream-5 "a red fox in a snowy forest" -o fox.jpg   # task_id: <id1>
vhscli submit seedream-5 "a blue jay on a branch"      -o jay.jpg   # task_id: <id2>
vhscli submit seedream-5 "an orca breaching"           -o orca.jpg  # task_id: <id3>
# then poll + save (see below) — not a multi-id resume

---

vhscli resume——按任务 ID 完成一个已提交的生成任务

vhscli resume <task_id> -o <path>

该命令接受 submit 打印的 ID 和要写入的路径。resume 会：

• 在服务端查找任务（如果服务端不存在该 ID，则报错并退出）。
• 从任务本身获取使用的模型，并在等待前检查 -o 是否与该模型的输出类型匹配。
• 如果任务仍在运行，则等待其完成。
• 将媒体保存到 -o。扩展名决定保存格式；如有需要，CLI 会进行转换。它会严格写入指定位置——不会更改保存位置，也不会添加 (N)。

可以安全地重复运行：命令会从服务端重新读取已完成的任务，不会重新提交任务。每次调用只处理一个 ID——如需并行处理多个任务，请使用 poll + save，或在并行 shell 中分别为每个 ID 运行一次 resume。

适合使用 resume 的情况：

• 你运行了 vhscli submit ...，现在想获取单个任务的结果。
• vhscli generate ... 运行中断（按下 ctrl-c、程序崩溃、关闭终端或网络中断）——它会在开始等待前打印 ID。

示例：

vhscli resume 7d3c1b2a-... -o fox.png

---

vhscli poll — 监视多个任务；打印第一个完成的任务

vhscli poll -

从标准输入读取任务 ID，每行一个，并且只打印一个——第一个完成的任务——然后退出。不写入任何文件，也不接受 -o。与 vhscli save <task_id> -o <path> 配合使用。

标准输出只包含该 ID，不含其他内容（可直接传入管道）；供人阅读的状态信息会写入标准错误。使用 --json 时，则会输出单行 {"event":"task","task_id":"...","state":"done"|"error"|"missing"}。

运行 poll 期间可以持续传入 ID；每个 ID 到达后都会立即开始监视。 一个结果就会结束进程，因此驱动程序需要保留自己的待处理 ID 列表，移除刚刚收到结果的 ID，然后用其余 ID 再次轮询——重新发送任何尚未收到报告的 ID。每次最多运行一个 poll，绝不要让它空等。

立即再次轮询的开销很小：如果某个任务在上次 poll 退出时完成，会通过状态检查直接返回结果，无需等待。不存在对应任务的 ID 会报告 missing，而不是永远挂起。

示例：

id=$(printf '%s\n' "${ids[@]}" | vhscli poll -) && vhscli save "$id" -o "$id.png"

扇出循环示意：

left=("${ids[@]}")
while [ ${#left[@]} -gt 0 ]; do
  id="$(printf '%s\n' "${left[@]}" | vhscli poll -)"
  vhscli save "$id" -o "$id.png"
  left=($(printf '%s\n' "${left[@]}" | grep -vFx "$id"))
done

---

vhscli save — 写入已完成任务的输出

vhscli save <task_id> -o <path>

将已完成任务的输出写入 -o 指定的位置，然后退出。它绝不会等待：仍在运行的任务会导致错误（负责等待的是 poll）。可以安全地重复运行——结果会从任务中读取，不会重新生成。

优先使用 save，不要自行获取结果 URL：结果封装因模型而异，下载文件会以原子方式落盘；如果提供商的格式与 -o 扩展名不同，文件会进行转换。任务出错时，会返回任务的错误。

示例：

vhscli save 7d3c1b2a-... -o cat.png

---

理解本地图片、视频和 PDF

**不要使用 Read 工具或任何内置文件读取功能来“查看”图片、视频或 PDF。**这种方式要么会失败，要么只会给出乱码片段。理解本地视觉内容或文档内容的唯一正确方式是使用 vhscli chat 和 -i / -v / -f。

vhscli chat "what's happening?" -i photo.jpg
vhscli chat "transcribe the speech" -v clip.mp4 --fps 2
vhscli chat "summarize this paper" -f paper.pdf

视觉内容／文档理解的提示词范例

vhscli chat 可以理解图片、PDF 和视频帧，但无法处理视频中的音频。如果要解析答案，请要求输出结构化 JSON，并明确列出每个所需字段。请明确指定格式（时间戳样式、单位、语言）。

图片 — 描述／分类：

vhscli chat "describe the scene. return json {objects:[{label,bbox?}], setting, mood, dominant_colors:[]}." -i photo.jpg
vhscli chat "classify the image into one of: cat, dog, bird, other. return json {label, confidence_0_1, reasoning}." -i pic.jpg

图片 — OCR／文本提取：

vhscli chat "transcribe all visible text verbatim, preserving line breaks and reading order. do not paraphrase." -i receipt.jpg
vhscli chat "extract the receipt as json {merchant, date_iso, items:[{name, qty, unit_price, line_total}], subtotal, tax, total, currency}." -i receipt.jpg

图片 — 比较（在提示词中为图片编号）：

vhscli chat "compare image 1 and image 2. return json {same_subject:bool, differences:[], which_is_better, why}." -i a.jpg -i b.jpg
vhscli chat "image 1 is the original, image 2 is an edit. list every visible change as json {changes:[{region, before, after}]}." -i orig.png -i edit.png

PDF — 总结／概述（始终要求标注页码）：

vhscli chat "summarize this paper in 5 bullets. each bullet must include the source page as {page:int, point:string}. return json {bullets:[...]}." -f paper.pdf
vhscli chat "extract the outline as json [{page, heading_level, heading, bullets:[]}]." -f doc.pdf

PDF — 问答／提取：

vhscli chat "answer using only this document. question: what is the experimental setup? return json {answer, citations:[{page, quote}]}." -f paper.pdf
vhscli chat "extract every table as json [{page, title?, headers:[], rows:[[...]]}]." -f report.pdf

视频 — 事件／时间线（注明时间戳格式）：

vhscli chat "list key events. return json [{start_time, end_time, event}]. use HH:mm:ss." -v clip.mp4 --fps 2
vhscli chat "describe the movement sequence and any safety risks. return json [{start_time, end_time, event, danger:'none'|'low'|'med'|'high'}]. HH:mm:ss." -v clip.mp4 --fps 3

视频 — 时序问答／计数：

vhscli chat "at what timestamp does the referee first appear? return json {timestamp_hms, evidence}." -v match.mp4 --fps 2
vhscli chat "count how many distinct people appear. return json {count, per_person:[{first_seen_hms, description}]}." -v scene.mp4 --fps 3

为视频选择 --fps（默认值为 1，范围为 0.2–5）：

• 3–5 — 统计动作、体育赛事、快速剪辑、密集运动。
• 1 — 常规描述、对话场景。
• 0.2–0.5 — 长时间静态片段、人数统计、缓慢变化的监控画面。

FPS 越高，细节越丰富，但消耗的 token 更多，速度也更慢。FPS 越低，成本越低，但可能漏掉短暂事件。

提示

• 始终将提示词用引号括起来。
• vhscli generate / vhscli submit / vhscli resume / vhscli save 必须指定 -o。路径相对于当前工作目录；输出格式由扩展名决定，CLI 会在需要时进行转换。CLI 会准确写入该路径并覆盖已有文件，因此如果需要保留现有文件，请自行选择一个空闲名称。
• 短选项支持不带空格的形式：-ofoo.jpg。长选项支持使用 =：--size=1920x1080。
• 要传入以短横线开头的提示词，请使用 --： vhscli generate seedream-5 -o x.jpg -- "-weird prompt"。
• 参考图片（-i、--first-frame、--last-frame）可以使用任何常见格式；非 JPEG/PNG 输入（例如 HEIC、WebP、TIFF、BMP）会在上传前转换为 JPEG。
• 参考文件会上传到临时云存储，供提供商获取，并会自动过期。每次运行都会重新上传，因此反复传入大型参考文件时，每次都会产生上传开销。
• 命令未知？vhscli 会推荐最接近的匹配项。

--json（脚本编写）

为 generate、submit、resume、save、poll、whoami 或 account 添加 --json，即可在标准输出中每行输出一个 JSON 对象，同时将日志输出到标准错误：

{"event":"submitted","task_id":"..."}
{"event":"progress","task_id":"...","elapsed_s":42}
{"event":"task","task_id":"...","state":"done"|"error"|"missing","message":"..."}
{"event":"done","task_id":"...","path":"/abs/out.mp4","hash":"sha256:...","size":123}
{"event":"whoami","user_id":"...","email":"...","name":"..."}
{"event":"account","user_id":"...","email":"...","name":"...","balance_usd":14.04}
{"event":"error","message":"...","code":"auth"|"credit"|"network"}

• 后端接受任务后会立即触发 submitted — 保存 task_id，之后即使发生崩溃，也可以在任何已登录的机器上运行 vhscli resume <task_id> -o <path> --json 恢复任务。该 ID 就是完整的任务凭据；无需本地数据。
• task 是 poll 在被监视的 ID 达到某种结果（done / error / missing）时输出的内容。它不会写入文件 — 后续请使用 save。
• done.path 是写入的文件（始终是你指定的 -o）；hash 是其内容的 sha256 哈希值。由会写入文件的命令输出（generate、resume、save）。
• error 中的 code 仅在可采取操作的失败情况下出现：auth（登录）、credit（充值）、network（可尝试重试）。没有代码就表示只有错误消息。命令失败时会输出 error 并以 1 退出。