vhscli

vhscli

vhscli はマルチモーダル AI 用のコマンドラインツールです。テキスト／画像／動画／PDF についてチャットしたり、プロンプトから画像、動画、音声を生成したりできます。 シンクライアントのため、認証、アップロード、モデルの実行はすべてサーバー側で行われ、ユーザーがプロバイダーの API キーをローカルに保存することはありません。

現在のヘルプを確認するには、vhscli --help または vhscli <command> --help を実行してください。CLI が正確な情報源です。

実行方法

最新のモデル、フラグ、修正を使用できるよう、常に npx @getvhs/vhscli@latest 経由で実行してください。バージョンを固定したり、PATH 上に存在していても vhscli のみで実行したりしないでください。古い可能性があります。

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：イベントを1行で出力します
• 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> — 1つのタスクの完了を待ち、その出力を書き込みます
• poll - — 標準入力からタスク ID を監視し、最初に完了したタスクを表示して終了します（ファイルは書き込みません）
• save <task_id> -o <path> — 完了済みタスクの出力を書き込みます（完了を待つことはありません）

CLI はローカルに何も保存しません。タスクは VHS バックエンドに保存され、タスク ID のみで参照できます。プロジェクト、データベース、設定ファイルはありません。詳しくは、以下の「タスクの追跡方法」を参照してください。

generate／submit／resume／save／poll／whoami／account で --json を指定すると、NDJSON イベントが標準出力に出力され、通常のログは標準エラー出力に振り分けられます（以下の「--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）

各呼び出しは独立したワンショットで、前回の呼び出しの内容は記憶されません。出力は標準出力に送られ、ディスクには保存されません。動画内の音声は理解されません。

例：

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

すべての画像モデルで、フレームサイズを指定するフラグは1つです。

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

1つの値でアスペクト比と解像度をまとめて指定でき、どのモデルでも同じフレームを意味します。例：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 と同じフラグおよびプロンプトガイドを使用しますが、こちらはプロティアです。プロンプトへの忠実度が高く、より細部まで描写できますが、生成には数秒ではなく1枚あたり約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（または、1つずつ 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 を指定します。

デフォルトでは、5秒、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 を繰り返します）。各クリップは30秒以下、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 バックエンドの1行のレコードです。CLI はデータベースにもサイドカーファイルにも書き込みません。そのため、タスク ID だけがタスクを特定する手段です。失うと、料金を支払ったタスクが宙に浮いてしまいます。

• generate は送信、待機を行い、-o に保存します。最初に ID を出力するため、中断した場合も再開できます。
• submit は ID（task_id: <uuid>）を出力して、待機せずに終了します。-o は検証されますが、この時点では何も書き込まれません。
• resume <task_id> -o <path> は1つのタスクを待機して、その出力を書き込みます（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）を受け取ります。違いは、バックエンドにタスクが登録されると、task_id: <uuid> を出力して、ポーリングせずに終了する点だけです。-o は確認されますが、再開または保存するまで何も書き込まれません。

次のような場合に使用してください。

• 処理に時間がかかる場合（例：seedance の動画）や、ターミナルを占有したくない場合。
• 複数のタスクを並列で送信し、後から結果を取得したい場合（poll + save）。

出力された ID を控えてください。 1つのタスクなら、vhscli resume <task_id> -o <path> で完了できます。複数のタスクなら、以下の poll + save を使用してください。このマシン上に、タスクを代わりに記憶しておくものはありません。

--task-id <uuid> を指定すると、新しい ID ではなく、選択した ID で送信できます。これにより、送信が返る前に ID を書き留めておけます。料金を支払ったタスクを ID の紛失で宙に浮かせたくない場合に使用してください。UUID を生成して保存してから送信します。コマンドが何も出力する前に終了した場合は、同じコマンドを再実行してください。バックエンドのレコードと送信はどちらもその ID をキーとしており、冪等なため、再実行すると2つ目のタスクを開始するのではなく、同じタスクに接続します。

例：

# 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 を指定して送信済みの生成タスクを1つ完了する

vhscli resume <task_id> -o <path>

submit が出力した ID と、書き込み先のパスを指定します。resume は次の処理を行います。

• サーバー上でタスクを検索します（ID が見つからない場合は致命的エラーになります）。
• タスク自体から実行されたモデルを特定し、待機する前に -o がそのモデルの出力形式に合っているかを確認します。
• タスクがまだ実行中の場合は、完了するまで待機します。
• メディアを -o に保存します。拡張子によって保存形式が決まり、必要に応じて CLI が変換します。指定した場所にそのまま書き込みます。保存先の変更や (N) の付加は行いません。

安全に再実行できます。完了済みのタスクはサーバーから再読み込みされ、再送信されることはありません。1回の呼び出しで指定できる ID は1つです。複数のタスクを並行処理するには、poll + save を使用するか、ID ごとに別のシェルで resume を実行してください。

resume を使用する場面：

• vhscli submit ... を実行し、1つのタスクの結果を取得したい場合。
• vhscli generate ... が中断された場合（Ctrl-C、クラッシュ、ターミナルを閉じた、ネットワーク切断など）。待機を始める前に ID が出力されています。

例：

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

---

vhscli poll — 多数のタスクを監視し、最初に完了したものを出力

vhscli poll -

標準入力からタスク ID を1行に1つずつ読み込み、最初に完了したものを1つだけ出力して終了します。ファイルは書き込まず、-o も受け付けません。vhscli save <task_id> -o <path> と組み合わせてください。

stdout にはその ID だけが出力され、それ以外は何も出力されません（パイプでそのまま使えます）。人が読める状態は stderr に出力されます。--json を指定すると、代わりに {"event":"task","task_id":"...","state":"done"|"error"|"missing"} の1行だけが出力されます。

poll の実行中も ID を追加できます。追加された ID は届いた時点で監視が始まります。結果を1つ返すとプロセスは終了するため、ドライバーは未処理の ID を独自に一覧で管理し、結果が返された ID を取り除いて、残りの ID でもう一度 poll します。報告されたことを確認できなかった ID は再送信してください。poll は同時に0個または1個だけ実行し、何も待っていない状態の 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 です）。安全に再実行できます。結果は再生成されず、タスクから読み戻されます。

結果 URL を自分で取得するより、save を使うことをおすすめします。結果エンベロープはモデルごとに異なり、ダウンロードはアトミックに行われ、プロバイダーの形式が -o の拡張子と異なる場合はファイルが変換されます。タスクがエラーになった場合は、そのタスクのエラーが返されます。

例：

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

---

ローカルの画像、動画、PDF の読み取り方

**画像、動画、PDF を「見る」ために Read ツールや、組み込みのファイル読み取り機能を使わないでください。**その方法は失敗するか、文字化けした断片が表示されます。ローカルの視覚情報や文書の内容を理解する正しい方法は、-i / -v / -f を指定して vhscli chat を使うことだけです。

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 を上げると詳細になりますが、トークン数が増え、処理も遅くなります。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 を追加すると、ログは stderr に出力され、stdout には 1 行につき 1 つの 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 は、監視対象の ID が結果（done／error／missing）に達したときに poll が出力するものです。ファイルは書き込みません。続けて save を実行してください。
• done.path は書き込まれたファイル（常に指定した -o）で、hash はその内容の sha256 です。書き込みを行うコマンド（generate、resume、save）が出力します。
• error に含まれる code は、対処可能なエラーの場合にのみ表示されます。auth（ログイン）、credit（チャージ）、network（再試行で解決する可能性があります）が該当します。コードがない場合、メッセージに記載された内容がすべてです。コマンドが失敗すると error を出力し、終了コード 1 で終了します。