popcorn-cli

Popcorn 官方命令行客户端。通过本地配置的 API Key 调用 Popcorn 服务，用于查询可用模型、提交生图 / 生视频任务、查询任务状态，以及按类型查询 / 创建文件夹。

安装

需要 Node.js 18 或更高版本。

npm install -g @baomihuatop/popcorn-cli

安装后确认命令可用：

popcorn-cli --version
popcorn-cli --help

配置 API Key

popcorn-cli config set-key <YOUR_API_KEY>

查看当前配置：

popcorn-cli config show

API Key 会保存在本机配置文件中：~/.popcorn-cli/config.json。

查询可用模型

提交任务前，先查询当前 API Key 可用的模型和参数 schema。

popcorn-cli image models
popcorn-cli video models
popcorn-cli video models --detail <MODEL_ID>

models 默认返回模型清单、model_limit、计费配置、公共调用建议和提交任务所需的参数结构。使用 --detail <MODEL_ID> 查看单个模型完整信息。

提交任务

生图任务：

popcorn-cli image submit -n "demo image" -d "cat test" -p '{"model":"sd-xl-v1","prompt":"a cat"}'

生视频任务：

popcorn-cli video submit -n "demo video" -d "cinematic cat test" -p '{"model":"video-model-id","prompt":"a cinematic cat"}'

关联会话 ID：

popcorn-cli image submit -s <SESSION_ID> -n "demo image" -d "cat test" -p '{"model":"sd-xl-v1","prompt":"a cat"}'

指定 AI 产物文件夹（仅支持 cli_generate）：

popcorn-cli folder list -t cli_generate
popcorn-cli image submit -f <FOLDER_ID> -n "demo image" -d "cat test" -p '{"model":"sd-xl-v1","prompt":"a cat"}'

-n, --name 和 -d, --description 必填；-p, --params 必须是 JSON 对象字符串。具体字段以 image models / video models 返回的 params_schema 为准。

上传资源

上传本地图片、视频或音频资源：

popcorn-cli resource upload ./demo.png --name "demo image" --description "reference image"

指定上传资源文件夹：

popcorn-cli resource upload ./demo.mp4 --folder-id 123 --name "demo video" --description "reference video"

--name 和 --description 必填。资源类型由后端按文件扩展名 / Content-Type 推断，CLI 不再提供 --type。--folder-id 不传则不归属目录；传入时必须是当前用户的 cli_upload 目录 ID，并由后端校验权限。

查询上传资源：

popcorn-cli resource list --name demo --created-from 2026-08-01 --created-to 2026-08-06 --page 1 --page-size 20

返回内容包含 name、description、file_url、created_at，并附带 total/page/page_size 分页信息。

查询任务

按任务 ID 查询单个任务：

popcorn-cli task list -t <TASK_ID>

按会话 ID 查询该会话下的任务：

popcorn-cli task list -s <SESSION_ID>

文件夹

按类型查询文件夹：

popcorn-cli folder list -t cli_generate
popcorn-cli folder list -t cli_upload

创建文件夹：

popcorn-cli folder create -n "角色参考" -t cli_upload
popcorn-cli folder create -n "主角" -t cli_upload -p <PARENT_ID>

type 支持 cli_generate（CLI 生成产物）与 cli_upload（CLI 上传资源）。

常用命令

| 命令 | 说明 | |------|------| | popcorn-cli config set-key <apiKey> | 设置 API Key | | popcorn-cli config show | 查看当前配置 | | popcorn-cli image models | 查询可用生图模型 | | popcorn-cli image models --detail <MODEL_ID> | 查看单个生图模型完整信息 | | popcorn-cli image submit -n <NAME> -d <DESCRIPTION> -p <JSON> | 提交生图任务 | | popcorn-cli video models | 查询可用生视频模型 | | popcorn-cli video models --detail <MODEL_ID> | 查看单个生视频模型完整信息 | | popcorn-cli video submit -n <NAME> -d <DESCRIPTION> -p <JSON> | 提交生视频任务 | | popcorn-cli resource upload <file> -n <NAME> -d <DESCRIPTION> | 上传图片、视频或音频资源 | | popcorn-cli resource list --name <KEYWORD> --page <PAGE> | 查询上传资源 | | popcorn-cli task list -t <TASK_ID> | 按任务 ID 查询任务 | | popcorn-cli task list -s <SESSION_ID> | 按会话 ID 查询任务 | | popcorn-cli folder list -t <TYPE> | 按类型查询文件夹 | | popcorn-cli folder create -n <NAME> -t <TYPE> | 创建文件夹 |

所有命令都支持 --help：

popcorn-cli --help
popcorn-cli image --help
popcorn-cli folder --help
popcorn-cli folder create --help
popcorn-cli resource upload --help

升级

npm install -g @baomihuatop/popcorn-cli@latest

卸载

npm uninstall -g @baomihuatop/popcorn-cli

常见问题

popcorn-cli: command not found

确认 npm 全局安装目录已加入 PATH，或重新打开终端后再试。

未设置 API Key

先执行：

popcorn-cli config set-key <YOUR_API_KEY>

params 不是合法的 JSON

-p 参数必须传入合法 JSON 对象字符串，建议用单引号包裹完整 JSON。