bukesiyi-cli

《不可思议》（https://buke41.com）开放 API 的命令行客户端，命令名为 buke。支持交互式终端、脚本、CI 流水线和 AI agent 调用。

支持范围与接入条件

• 支持 API 凭据管理、产品建档、余额查询，以及渲染短片、商品视频和短剧的创建、查询、确认与下载。
• 注册账号无需单独申请 API 访问资格。调用要求 API 服务启用、密钥有效，且账号在密钥所属团队具有制作权限。
• 密钥由账号本人在API 密钥页面创建、查看和吊销。完整密钥仅在创建成功时显示一次。
• 示例使用演示凭据、路径和编号。执行时替换为当前环境配置；程序应解析 JSON 字段，不应逐字匹配中文输出。

安装

运行环境要求 Node.js 20 或更高版本。

npm install -g bukesiyi-cli

安装后验证版本：

$ buke --version
bukesiyi-cli/0.3.3

也可使用 npx bukesiyi-cli <命令> 临时运行，例如 npx bukesiyi-cli whoami。

三步上手

先在API 密钥页面创建密钥，设置名称及有效期（30 天、90 天、180 天、365 天，或长期有效），并安全保存完整密钥。

1. 运行 buke login。核对服务地址后输入密钥；终端输入无回显。CLI 验证凭据成功后保存至本机。

$ buke login
将登录 https://buke41.com
请粘贴 API 密钥（输入不会显示），回车确认：
已登录 https://buke41.com
密钥：CI 机器（bk_test_0123456789abcdef）
所属团队：ws-11111111222243338444555555555555（owner）
权限范围：open:produce
有效期：长期有效
凭据保存在 /home/you/.config/buke/credentials.json（只有本人可读写）

2. 运行 buke whoami，核对账号、团队、权限及有效期。

$ buke whoami
当前登录 https://buke41.com
密钥：CI 机器（bk_test_0123456789abcdef）
所属团队：ws-11111111222243338444555555555555（owner）
权限范围：open:produce
有效期：长期有效
密钥来自：/home/you/.config/buke/credentials.json

3. 停止使用本机凭据时运行 buke logout。该命令删除本机凭据，不吊销服务端密钥。

$ buke logout
已退出登录，本机保存的密钥已删除。这把密钥本身仍然在用，不再使用请吊销它

自动化环境应通过受控环境变量 BUKE_API_KEY 或标准输入提供密钥。管道示例：

$ printf '%s' "$KEY" | buke login
已登录 https://buke41.com
密钥：CI 机器（bk_test_0123456789abcdef）
所属团队：ws-11111111222243338444555555555555（owner）
权限范围：open:produce
有效期：长期有效
凭据保存在 /home/you/.config/buke/credentials.json（只有本人可读写）

禁止将完整密钥写入命令行参数。参数可能被 shell 历史或进程列表记录，CLI 会在执行命令前拒绝此类输入：

$ buke login bk_test_0123456789abcdef_……
错误：密钥不要写在命令行里（会留在 shell 历史和进程列表里）。请用环境变量 BUKE_API_KEY，或者通过管道传给 buke login。刚才这把如果是真的，建议吊销后重新创建。
（错误码 CLI_KEY_IN_ARGV）

命令速查

| 命令 | 功能 | | --- | --- | | buke login | 读取密钥、执行服务端鉴权并保存本机凭据。输入优先级为环境变量、非交互标准输入、交互式终端 | | buke whoami | 查询密钥归属、团队、权限及有效期。优先使用 BUKE_API_KEY，否则读取本机凭据 | | buke logout | 删除本机凭据，不发送网络请求，不吊销密钥 | | buke balance | 查询可用、冻结及已使用额度 | | buke products create / set-images / confirm-lock | 创建产品、上传商品图片、确认外观信息 | | buke shorts catalog / upload / quote / order / status / download / cancel | 查询模板、上传素材、报价、创建订单、查询进度、下载和取消 | | buke videos create / status / message / confirm / download | 创建商品视频任务、查询进度、发送消息、确认制作和下载 | | buke drama create / status / quote / confirm / cancel / download | 创建短剧订单、查询进度、报价、确认制作、取消和下载 | | buke --version | 输出版本号 | | buke --help、buke <命令> --help | 输出命令及选项帮助 |

写操作支持 --idempotency-key <键>。未指定时，CLI 自动生成并在结果中返回。重试同一操作必须保留原键和请求内容；新键表示新尝试，可能产生新订单及费用。渲染短片的报价哈希与幂等键绑定，shorts quote 和 shorts order 必须使用相同键。

shorts order --wait、shorts status --wait 和 videos status --wait 轮询原任务。成功退出 0，终态失败或取消退出 9，等待超过 --timeout（默认 600 秒）退出 8。商品视频进入等待回复或确认的状态时退出 0，等待调用方处理。

drama confirm 先获取当前报价；未指定 --yes 时仅展示报价，退出 2。指定 --yes 后才提交费用授权，并校验服务端报价哈希。drama status --wait 在终态或需要人工处理的状态停止：交付成功退出 0，失败或取消退出 9，needs_attention 和 partial 退出 0 并返回处理信息。

等待失败、超时或轮询中断后，应查询原任务。JSON 错误文档中的 recovery 保留任务编号、最后状态和查询命令；shorts order 同时保留幂等键。自定义服务的查询命令保留 --base-url。

drama confirm 失败时同样保留目标订单、最后一次成功查询的状态和已知幂等键，并返回 operation: "confirm"。operationOutcome 区分 not_submitted（确认请求尚未发送）、rejected（服务端明确拒绝）和 unknown（受理结果未知）。acceptance 仅表示原订单是否已确认存在，不表示本次费用确认成功。CLI 不自动重发确认请求；结果未知时应先查询原订单并保留原键。

提交结果不明时，recovery.acceptance 为 unknown，不返回虚构的任务编号。保存原幂等键，在 Studio 核对原请求；不得换键重新下单。CLI 不自动重试。

drama create 支持 --model 和 --resolution。未显式指定模型时，报价前可适配人物参考；显式指定不兼容模型时进入需要处理的状态，不自动替换。drama quote 展示实际制作规格、费用及适配说明。

短剧普通状态 JSON 可包含 order.productionCompatibility 和 order.failures。等待终态失败时，失败数组位于 JSON 顶层 failures，与 error、recovery 并列。素材定位不可确认时返回 reference: null，不推测具体图片；旧记录不会自动补齐证据。修正素材或在 Studio 明确修改规格后，须重新报价和确认，CLI 不自动切换模型或付费重试。

输出与通用选项

完整成片下载只接受 HTTP 200、非空正文及合法视频类型；短剧和渲染短片为 MP4，商品视频同时兼容服务端返回的 QuickTime。HTTP 202 表示文件尚未就绪，命令退出 7，不保存响应或覆盖已有文件。应查询原任务后再次下载，不重新生成。

| 选项 | 作用 | | --- | --- | | --json | 标准输出仅包含一个 JSON 文档：成功时为结果，失败时为结构化错误。适用于脚本和 AI agent | | --base-url <地址> | 指定服务源地址，默认 https://buke41.com。地址须使用 HTTPS 且不包含路径；本机调试允许 http://localhost、http://127.0.0.1、http://[::1]。logout 不接受此选项 |

成功 JSON 示例：

$ buke whoami --json
{
  "baseUrl": "https://buke41.com",
  "key": {
    "id": "0123456789abcdef",
    "name": "CI 机器",
    "scopes": [
      "open:produce"
    ],
    "expiresAt": null,
    "displayPrefix": "bk_test_0123456789abcdef"
  },
  "account": {
    "id": "11111111-2222-4333-8444-555555555555"
  },
  "workspace": {
    "id": "ws-11111111222243338444555555555555",
    "role": "owner"
  },
  "source": "file",
  "credentialsPath": "/home/you/.config/buke/credentials.json"
}

错误 JSON 示例：

$ buke whoami --json
{
  "error": {
    "code": "CLI_NOT_LOGGED_IN",
    "message": "还没有登录。先运行 buke login，或者设置环境变量 BUKE_API_KEY",
    "retryable": false,
    "traceId": null
  }
}

环境变量

| 变量 | 作用 | | --- | --- | | BUKE_API_KEY | 优先使用的 API 密钥；设置后不读取本机凭据文件。login 验证后将其保存至本机 | | BUKE_BASE_URL | 服务源地址。--base-url 优先于该变量；未配置时使用 https://buke41.com | | BUKE_CONFIG_DIR | 凭据目录，须为绝对路径，支持展开开头的 ~。默认依次采用 $XDG_CONFIG_HOME/buke、~/.config/buke；Windows 使用 %APPDATA%\buke |

凭据保存在 credentials.json 中。macOS 和 Linux 上文件权限仅允许当前用户读写。文件包含明文密钥，不得提交至代码仓库、写入镜像或直接共享。

启用 Node.js 环境代理时，CLI 会拒绝可能经代理传输密钥的本机 HTTP 请求。本机调试可通过 NO_PROXY 排除回环地址：

export NO_PROXY='localhost,127.0.0.1,[::1]'

退出码

| 退出码 | 含义 | 当前支持 | | --- | --- | --- | | 0 | 成功 | 是 | | 2 | 参数或用法错误 | 是 | | 3 | 未登录、鉴权失败或账号不可用 | 是 | | 4 | 余额不足 | 是 | | 5 | 服务端、网络或本机错误 | 是 | | 6 | 报价或幂等冲突 | 是 | | 7 | 请求受限或操作尚未就绪 | 是 | | 8 | 等待超时 | 是 | | 9 | 任务失败 | 是 | | 10 | 接口或资源不可访问 | 是 | | 130 | 收到中断信号 | 是 |

信号中断采用 128 + 信号编号：SIGINT 为 130，SIGTERM 为 143，SIGHUP 为 129。脚本应结合退出码及 error.code 分支处理；需要等待时遵循 error.retryAfterSeconds。

错误码

OPEN_API_ 前缀表示服务端返回的错误；CLI_ 前缀表示本机参数、配置、网络或输出处理错误。--json 模式使用 error.code 标识错误，服务端错误同时提供 error.traceId。

| 错误码 | 退出码 | 处理方式 | | --- | --- | --- | | CLI_USAGE | 2 | 参数不符合命令要求。运行 buke --help 或子命令帮助核对用法 | | CLI_KEY_IN_ARGV | 2 | 命令行参数包含密钥，命令未执行。改用环境变量、标准输入或交互式输入；真实密钥应按泄露处理 | | CLI_KEY_MISSING | 2 | 未提供密钥，或标准输入未在 30 秒内结束。检查输入来源 | | CLI_KEY_MALFORMED | 2 | 密钥格式无效。检查前缀、截断及空白字符 | | CLI_BASE_URL_INVALID | 2 | 服务地址无效，或包含路径、参数、用户信息。使用 HTTPS 源地址 | | CLI_BASE_URL_INSECURE | 2 | 非回环地址使用 HTTP，或本机 HTTP 请求会经代理发送。改用 HTTPS 或正确配置 NO_PROXY | | CLI_BASE_URL_MISMATCH | 2 | 目标服务与本机凭据绑定地址不符，请求未发送。使用原地址或为新地址重新登录 | | CLI_NOT_LOGGED_IN | 3 | 环境变量和本机均无可用凭据。运行 buke login 或设置 BUKE_API_KEY | | CLI_CONFIG_DIR_INVALID | 2 | 凭据路径无效。将 BUKE_CONFIG_DIR 设为绝对路径或以 ~/ 开头的路径 | | CLI_CREDENTIALS_UNREADABLE | 5 | 凭据文件损坏、类型不符或权限不足。修正权限，或删除本机凭据后重新登录 | | CLI_CREDENTIALS_WRITE_FAILED | 5 | 无法保存或删除凭据。修正目录权限，或通过 BUKE_CONFIG_DIR 指定可写目录 | | CLI_NETWORK | 5 | 网络连接失败。检查地址、网络、代理和证书；确认配置正确后有限重试 | | CLI_TIMEOUT | 5 | 请求超过时限；JSON 请求默认 15 秒、成片下载默认 120 秒。检查网络或代理；涉及提交时先核对原请求结果 | | CLI_REDIRECT | 5 | 目标服务返回重定向，CLI 未跟随。核对服务源地址后重新登录 | | CLI_BAD_RESPONSE | 5 | 响应不符合 API 结构。检查服务地址、代理或网关；仅对可重试状态采用有限退避 | | CLI_DOWNLOAD_NOT_READY | 7 | 下载接口返回 HTTP 202，文件尚未就绪。查询原任务后再次下载；CLI 不保存响应为成片、不自动重试，也不重新生成 | | CLI_WAIT_TIMEOUT | 8 | 等待达到时限，任务并未因此失败。按 recovery.statusCommand 查询原任务，不重新下单 | | CLI_TASK_FAILED | 9 | 原任务进入失败或取消终态。查询原任务，核对原因、已完成内容及计费；新制作需要重新报价和授权 | | CLI_INTERRUPTED | 130 | 进程收到中断信号。SIGTERM 和 SIGHUP 分别退出 143、129；提交被中断时先核对原任务 | | CLI_INTERNAL | 5 | 未预期的本机错误。提交脱敏错误信息、命令及版本号以供排查 |

网络配置：

• 自签名证书使用 NODE_EXTRA_CA_CERTS 指定受信任根证书，不得关闭证书校验。
• CLI 默认不主动启用代理。Node.js 支持环境代理时，可通过 NODE_USE_ENV_PROXY=1 启用，并配置 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。Node.js 24.18 支持该方式，20.19 和 22.19 不支持；应结合实际 Node.js 版本验证代理行为。

HTTP 404 应结合 error.code 排查。OPEN_API_NOT_FOUND 可能来自服务未启用、路径或方法不匹配。产品、模板、订单错误则需核对资源编号及所属账号或团队。API 的结构化 404 退出 10；无法解析为 API 响应的 404 退出 5。不能仅凭 404 判断服务已停用。

安全须知

• API 密钥授权以所属账号和团队身份执行操作，应仅存储于受控环境。
• 密钥暴露于命令行参数、URL、日志、截图或对话后，应立即吊销并替换。
• buke logout 仅删除本机文件；服务端吊销须通过API 密钥页面执行。修改登录密码不会自动吊销 API 密钥。
• 日志和支持请求仅使用公开密钥标识、请求编号和错误码；不得包含完整凭据。
• 不同机器、流水线和 agent 应使用独立密钥，并设置符合用途的有效期。

从仓库源码运行

CLI 开发者可参考仓库 docs/open-api/cli.md 第 2.2 节进行构建、源码运行和本机链接。普通接入使用 npm 发布包。

许可

CLI 代码按 MIT 许可发布，许可全文见包内 LICENSE。服务调用仍受账号用户协议约束；《不可思议》的名称和标识不在 MIT 许可范围内。

联系我们

• 网站：https://buke41.com
• 客服邮箱：[email protected]

提交问题时提供命令、CLI 和 Node.js 版本、请求时间，以及脱敏后的错误码、错误说明和请求编号。不得发送完整密钥、凭据文件或含客户素材的完整响应。