popcorn-cli

popcorn-cli 是爆米花（Popcorn）的命令行客户端；需要生图、生视频或管理文件夹时，直接使用本 CLI 即可完成模型查询、任务提交、结果查询与文件夹管理。 按任务类型分组组织命令，面向脚本化、自动化和 Agent 场景。

安全与隐私提示

• API Key 本地存储：popcorn-cli config set-key 会把 API Key 保存到 ~/.popcorn-cli/config.json。该配置文件属于本机明文凭据存储，请不要提交到 Git、复制到日志、截图或共享给其他用户；在共享工作站、CI、Agent 运行环境中应限制 home 目录和配置文件访问权限。
• 远程传输：执行 models、submit、task list、folder list、folder create 时，CLI 会调用远程 Popcorn 后端服务。submit --params 中的提示词、媒体生成参数、业务上下文、会话 ID 等会随请求发送到 Popcorn 后端；不要把密码、密钥、个人隐私、未授权客户资料或其他机密内容放入任务参数。
• 输出处理：命令返回的 task_id、session_id、folder id、result URL 和错误信息可能包含业务上下文或资源地址。请按敏感数据处理，不要无意写入公开日志、公开 issue、聊天记录或可被无关人员读取的构建产物。

概念

• 会话（session）：一次业务上下文，session_id 由调用方生成（例如一次剧本推进、一次 Agent 会话）。同一 session 下可提交多个任务，便于统一追踪。
• 任务（task）：一次具体的生成请求。submit 为异步接口，提交后立刻返回 task_id（不含最终结果）；须再用 task list 按 task_id / session_id 查询状态与结果。
• 模型（model）：每个任务类型下有多个可用模型，模型自带使用限制（时长、分辨率等）。可用模型清单与 API Key 所属租户绑定，仅返回当前租户开通且启用中的模型。提交任务前建议先用 <group> models 查询目标场景的可用模型。
• 文件夹（folder）：按业务用途分为两类独立目录树，归属到当前 API Key 对应的用户。创建时可挂到同类型父目录下；查询返回扁平列表。
  • AI 生成产物目录（命令参数 cli_generate）：用来归档生图 / 生视频等 CLI 生成结果；image/video submit -f 只能挂这类目录。
  • 上传资源目录（命令参数 cli_upload）：用来整理用户上传的参考图、素材等资源；不能作为生图/生视频的归属目录。