gen-ai-use

gen-ai CLI — 使用ガイド

gen-ai CLI は、Picsart API を介してターミナルから AI 画像、動画、音声を生成します。

使用するタイミング

上記の説明を参照してください。

前提条件

Picsart gen-ai CLI がインストールされ、認証済みであること（gen-ai login）。gen-ai whoami はディスク上のキャッシュされた認証情報のみを読み取り、正しい形式のトークンファイルが存在すれば「✓ Authenticated」と報告します。トークンの有効期限は確認せず、ネットワーク通信も行わないため、このコマンドが成功しても、その後のネットワーク依存コマンドが成功する証明にはなりません。

実行方法

以下の手順に従って、エージェントの terminal ツールから gen-ai コマンドを実行してください。

クイックリファレンス

• 認証： login、logout、whoami
• 生成： generate、remove-bg、change-bg、enhance、vectorize、redo、extend
• モデル／料金： models、models info、models compare、pricing、credits、validate
• バッチ： batch run、batch status、batch resume
• ドライブ： upload、upload-to-drive、download、list
• 設定： config get | set | list | keys | unset
• 履歴： history、history last、history files、history clear
• ユーティリティ： completion、update

フラグの詳細については、gen-ai <command> --help を実行するか、references/FLAGS.md を参照してください。

手順

詳しい手順については、以下の各セクションを参照してください。

注意点

• 古いモデル ID — 名前が変更または削除されたモデル名を記憶に頼って使用する → 先に gen-ai models を実行するか、gen-ai validate -m <id> を実行してください。
• i2v 以外の動画モデルに --image を渡す — 自動的にマッピングされず、無視されます。gen-ai models info <id> で確認してください。
• CI で --no-input を忘れる — CLI が対話型プロンプトを待ち続け、ジョブがタイムアウトします。TTY のない環境では、必ず --script（または --no-input）を組み合わせてください。
• --multi と --batch を併用する — これらは相互排他的な --input-dir モードです。どちらか一方を選んでください。

検証

gen-ai whoami を実行して認証を確認し、その後、失敗したコマンドを --debug 付きで再実行してください。それでも失敗する場合、ログインの問題と決めつける前にエラーの種類を確認してください。AuthError（「Not authenticated...」）は認証情報に実際に問題があることを意味し、gen-ai login で解決できます。NetworkError（メッセージに「fetch failed」などの通信障害やプロキシ／接続に関するヒントが含まれる場合）は、CLI のプロセスがネットワークに接続できないことを意味します。login を再実行しても解決せず、ネットワークアクセスの復旧またはエスカレーションが必要です。

参照先

• フラグと全コマンド一覧 → references/FLAGS.md
• バッチ生成（マニフェスト、並行処理、ストレステスト） → references/BATCH.md
• Picsart Drive（アップロード、ダウンロード、一覧表示） → references/DRIVE.md
• MCP ツールが URL として必要とするローカルファイル → picsart-add-media
• 高度な使い方（validate、VEO の拡張、対話モード、パイプ処理） → references/ADVANCED.md
• トラブルシューティング（ドライラン、デバッグ、よくあるエラー） → references/TROUBLESHOOTING.md
• ワークフロー例（画像 → 動画、モデル間の比較） → references/EXAMPLES.md
• シェル補完（bash、zsh、fish） → references/COMPLETIONS.md

使用しないケース

• SDK レベルの統合に関する質問 → @picsart/ai-sdk のリファレンス／specs/ のソースを参照してください
• Picsart の Web ミニアプリまたはモバイルのフロー → 対象外です
• まだカタログにない新しいバックエンドモデル → 先にバックエンドの MR を作成してください。リリースされると CLI が自動的に @picsart/ai-sdk から取得します

インストールと認証

# Signed binary (no Node required) — recommended
curl -fsSL https://picsart.com/gen-ai-cli/install.sh | bash

# Or via npm (requires Node 22+)
npm install -g @picsart/gen-ai

gen-ai login     # OAuth browser flow
gen-ai whoami    # verify

生成

# Interactive wizard
gen-ai generate

# Image, fully specified
gen-ai generate -m flux-2-pro -p "a sunset over mountains" -s

# Image-to-image
gen-ai generate -m gemini-3.1-flash-image -i ~/photo.jpg -p "make it watercolor"

# Text-to-video
gen-ai generate -m kling-v3-pro -p "a cat playing piano" --ar 16:9

# Image-to-video (--image is auto-mapped to startFrame for i2v models)
gen-ai generate -m veo-3.1 -i ~/photo.jpg -p "camera zooms in" -d 5

画像操作

gen-ai remove-bg -i photo.jpg
gen-ai change-bg -i photo.jpg -p "tropical beach sunset"
gen-ai enhance   -i photo.jpg                       # upscale / enhance
gen-ai vectorize -i logo.png                        # raster → SVG

すべての操作コマンドは、generate と同じ出力フラグ（--download、--save-to-drive、--drive-folder、--open、--clipboard、--json、--quiet など）を受け付けます。references/FLAGS.md を参照してください。

モデルの閲覧、料金の確認

新しいバージョンのリリースに伴いモデル ID は変更されるため、必ず最新のカタログを確認してください。

gen-ai models                       # list (filter --mode, --provider)
gen-ai models info <id>             # capabilities, inputs, aspect ratios
gen-ai models compare <a> <b>       # side-by-side
gen-ai pricing <model-id>           # credit cost
gen-ai credits                      # remaining balance

重要なデフォルト設定

• Drive の自動保存 — 結果はデフォルトで Picsart Drive の gen-ai-cli フォルダーに保存されます。--no-save-to-drive で無効にできます。カスタムフォルダーを使用するには --drive-folder NAME を指定してください。
• startFrame のマッピング — i2v モデル（VEO、Kling i2v、Wan、Luma、Seedance、Runway）では、-i / --image が自動的に ctx.startFrame にマッピングされます。
• スクリプトモード — --script は --silent --quiet --json と同じです。パイプ処理や CI に適した組み合わせです。
• CI モード — 対話型プロンプトで停止せず、すぐに失敗するよう --no-input を指定してください。

リファレンスファイルを参照する場合

• 一度に多数の生成を行う場合、または再試行／再開する場合 → references/BATCH.md
• Drive とのファイルの入出力 → references/DRIVE.md
• 検証、VEO の拡張、スクリプト作成 → references/ADVANCED.md
• コマンドが失敗する場合 → references/TROUBLESHOOTING.md
• 連鎖処理（画像 → 動画）またはモデルの比較 → references/EXAMPLES.md
• タブ補完 → references/COMPLETIONS.md
• すべてのフラグ／コマンド → references/FLAGS.md