gen-ai-use

gen-ai CLI — 使用指南

gen-ai CLI 通过 Picsart API 在终端中生成 AI 图像、视频和音频。

适用场景

请参阅上方说明。

前提条件

已安装并完成身份验证的 Picsart gen-ai CLI（gen-ai login）。请注意，gen-ai whoami 只会读取磁盘上缓存的凭据，如果令牌文件存在且格式正确，就会显示“✓ Authenticated”——它不会检查令牌是否过期，也不会发起网络请求，因此该命令成功并不能证明后续依赖网络的命令也能成功。

运行方法

使用 Agent 的 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
• 高级用法（验证、扩展 VEO、交互模式、管道） → references/ADVANCED.md
• 故障排除（试运行、调试、常见错误） → references/TROUBLESHOOTING.md
• 工作流示例（图像 → 视频、跨模型对比） → references/EXAMPLES.md
• Shell 补全（bash、zsh、fish） → references/COMPLETIONS.md

不适用场景

• SDK 级集成问题 → 参阅 @picsart/ai-sdk 参考文档 / specs/ 源码
• Picsart 网页迷你应用或移动端流程 → 无关
• 尚未纳入目录的新后端模型 → 应先提交后端 MR；模型发布到 @picsart/ai-sdk 后，CLI 会自动获取

安装与身份验证

# 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
• Tab 补全 → references/COMPLETIONS.md
• 所有标志／所有命令 → references/FLAGS.md