gen-ai-use

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gen-ai CLI — Usage Guide

gen-ai CLI — 使用指南

The

gen-ai

CLI generates AI images, videos, and audio from the terminal via the Picsart API.

gen-ai

CLI可通过Picsart API从终端生成AI图像、视频和音频。

When to Use

使用场景

See the description above.

请参考上方描述。

Prerequisites

前置条件

Picsart

gen-ai

CLI installed and authenticated (

gen-ai login

已安装并完成Picsart

gen-ai

CLI的身份验证（执行

gen-ai login

）。

How to Run

运行方式

Use the agent's
terminal
tool to invoke
gen-ai
commands as described in the Procedure below.

使用Agent的
terminal
工具，按照下方步骤调用
gen-ai
命令。

Quick Reference

快速参考

Auth:
```
login
```
,
```
logout
```
,
```
whoami
```

Generation:

generate

remove-bg

change-bg

enhance

vectorize

redo

extend

Models / pricing:

models

models info

models compare

pricing

credits

validate

Batch:
```
batch run
```
,
```
batch status
```
,
```
batch resume
```
Drive:
```
upload
```
,
```
download
```
,
```
list
```
Config:
```
config get | set | list | keys | unset
```

History:

history

history last

history files

history clear

Utilities:
```
completion
```
,
```
update
```

Run

gen-ai <command> --help

for full flag details, or see references/FLAGS.md.

身份验证：
```
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
```
Drive操作：
```
upload
```
,
```
download
```
,
```
list
```
配置：
```
config get | set | list | keys | unset
```

历史记录：

history

history last

history files

history clear

实用工具：
```
completion
```
,
```
update
```

执行

gen-ai <command> --help

查看完整参数详情，或参考references/FLAGS.md。

Procedure

操作步骤

See sections below for the detailed walkthrough.

请查看下方章节获取详细操作流程。

Pitfalls

常见陷阱

Stale model ID — using a name from memory that's been renamed/removed → run
```
gen-ai models
```
first or
```
gen-ai validate -m <id>
```
.
Passing
--image
to a non-i2v video model — it's silently ignored, not auto-mapped. Confirm with
```
gen-ai models info <id>
```
.
Forgetting
--no-input
in CI — the CLI sits waiting for an interactive prompt and the job times out. Always pair
```
--script
```
(or
```
--no-input
```
) with non-TTY contexts.
Mixing
--multi
and
--batch
— they're mutually exclusive
```
--input-dir
```
modes; pick one.

过时的模型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
```
模式，请选择其中一种。

Verification

验证方法

Run

gen-ai whoami

to confirm authentication, then re-run the failed command with

--debug

执行

gen-ai whoami

确认身份验证状态，然后添加

--debug

参数重新运行失败的命令。

Where to look

参考文档位置

Flags & full command list → references/FLAGS.md
Batch generation (manifests, concurrency, stress tests) → references/BATCH.md
Picsart Drive (upload, download, list) → references/DRIVE.md
Advanced (validate, extend VEO, interactive mode, piping) → references/ADVANCED.md
Troubleshooting (dry-run, debug, common errors) → references/TROUBLESHOOTING.md
Example workflows (image → video, cross-model comparison) → references/EXAMPLES.md
Shell completions (bash, zsh, fish) → references/COMPLETIONS.md

参数与完整命令列表 → references/FLAGS.md
批量生成（清单、并发、压力测试）→ references/BATCH.md
Picsart Drive（上传、下载、列表）→ references/DRIVE.md
高级功能（验证、扩展VEO、交互模式、管道操作）→ references/ADVANCED.md
故障排查（空运行、调试、常见错误）→ references/TROUBLESHOOTING.md
示例工作流（图像转视频、跨模型对比）→ references/EXAMPLES.md
Shell补全（bash、zsh、fish）→ references/COMPLETIONS.md

When NOT to use

不适用场景

SDK-level integration questions → consult the
```
@picsart/ai-sdk
```
reference /
```
specs/
```
source
Picsart web miniapp or mobile flows → unrelated
New backend models that aren't in the catalog yet → backend MR first; CLI picks them up automatically once they ship in
```
@picsart/ai-sdk
```

SDK级集成问题 → 请参考
```
@picsart/ai-sdk
```
文档或
```
specs/
```
源码
Picsart网页小程序或移动端流程 → 与此工具无关
尚未加入目录的新后端模型 → 先提交后端MR；一旦模型在
```
@picsart/ai-sdk
```
中发布，CLI会自动同步支持

Install & auth

安装与身份验证

bash

undefined

bash

undefined

Signed binary (no Node required) — recommended

签名二进制文件（无需Node）—— 推荐方式

curl -fsSL https://picsart.com/gen-ai-cli/install.sh | bash

Or via npm (requires Node 22+)

或通过npm安装（需要Node 22+）

npm install -g @picsart/gen-ai

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

undefined

npm install -g @picsart/gen-ai

gen-ai login # OAuth浏览器流程 gen-ai whoami # 验证身份

undefined

Generate

生成内容

bash

undefined

bash

undefined

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)

图像转视频（对于i2v模型，--image会自动映射为startFrame）

gen-ai generate -m veo-3.1 -i ~/photo.jpg -p "camera zooms in" -d 5

undefined

gen-ai generate -m veo-3.1 -i ~/photo.jpg -p "camera zooms in" -d 5

undefined

Image operations

图像操作

bash

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

All operation commands accept the same output flags as

generate

(

--download

--save-to-drive

--drive-folder

--open

--clipboard

--json

--quiet

, etc.). See references/FLAGS.md.

bash

gen-ai remove-bg -i photo.jpg
gen-ai change-bg -i photo.jpg -p "tropical beach sunset"
gen-ai enhance   -i photo.jpg                       # 放大/增强画质
gen-ai vectorize -i logo.png                        # 栅格图转SVG

所有操作命令都支持与

generate

相同的输出参数（

--download

、

--save-to-drive

、

--drive-folder

、

--open

、

--clipboard

、

--json

、

--quiet

等）。详情请参考references/FLAGS.md。

Browse models, check pricing

浏览模型、查看定价

Model IDs change as new versions ship — always check the live catalog:

bash

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

模型ID会随新版本发布而变化，请始终查看实时目录：

bash

gen-ai models                       # 列出模型（可通过--mode、--provider过滤）
gen-ai models info <id>             # 查看模型能力、输入要求、宽高比
gen-ai models compare <a> <b>       # 对比两个模型
gen-ai pricing <model-id>           # 查看信用点成本
gen-ai credits                      # 查看剩余余额

Important defaults

重要默认设置

Drive auto-save — results save to Picsart Drive in folder
```
gen-ai-cli
```
by default. Disable with
```
--no-save-to-drive
```
; use
```
--drive-folder NAME
```
for a custom folder.
startFrame mapping — for i2v models (VEO, Kling i2v, Wan, Luma, Seedance, Runway),
```
-i / --image
```
is auto-mapped to
```
ctx.startFrame
```
.
Script mode —
```
--script
```
=
```
--silent --quiet --json
```
, the right combo for piping or CI.
CI mode — pass
```
--no-input
```
to fail fast instead of hanging on interactive prompts.

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
```
参数可避免等待交互式输入，快速失败。

When to reach for the reference files

何时查看参考文档

Many generations at once, or retry/resume → references/BATCH.md
Files in/out of Drive → references/DRIVE.md
Validation, VEO extension, scripting → references/ADVANCED.md
A command is failing → references/TROUBLESHOOTING.md
Chaining (image → video) or comparing models → references/EXAMPLES.md
Tab completion → references/COMPLETIONS.md
All flags / all commands → references/FLAGS.md

需要批量生成、重试/恢复任务 → references/BATCH.md
处理Drive中的文件 → references/DRIVE.md
验证、扩展VEO、脚本编写 → references/ADVANCED.md
命令执行失败 → references/TROUBLESHOOTING.md
链式操作（图像转视频）或模型对比 → references/EXAMPLES.md
标签补全 → references/COMPLETIONS.md
所有参数/命令 → references/FLAGS.md