qhkit

青虎 AI 媒体工具包 CLI。纯 JS、零运行时依赖（仅用 Node 18+ 内置 fetch/FormData），可 npx 分发到任意机器；在青虎自己的 OpenClaw 机器上会自动复用 /root/.openclaw/qinghu_config.json，无需额外配置。

• AI 图像（3 种模式）：套图模式、专图模式、电商详情图
• AI 视频（2 个模型）：Seedance2.0（15s）、电商爆款直出Pro（12s）
• 视频创作 / 编辑：一键成片、角色替换、视频翻译、去水印 / 去字幕 / 画质提升、复刻爆款（videoScript）、视频转图文（imageText）、分镜脚本与分镜图、活动海报

安装 / 运行

# 免安装，直接跑（推荐分发方式）
npx @iqinghu/qhkit image options '{"queryParams":["modelLabel"],"modelLabel":"套图模式"}'

# 或全局安装，命令名为 qhkit
npm i -g @iqinghu/qhkit
qhkit --help

包名是 @iqinghu/qhkit（npx 时用全名）；安装后的命令名是 qhkit。下文示例统一用 qhkit <命令>，未全局安装时把它换成 npx @iqinghu/qhkit <命令> 即可。

要求 Node.js ≥ 18（推荐 20+）。

配置：密钥与服务地址

密钥获取：打开 https://www.iqinghu.com/workbench/dashboard/api-keys，创建 / 复制你的密钥。

CLI 按以下顺序解析 密钥 与 base_host，命中即用：

1. 环境变量 QHKIT_TOKEN=<密钥>（可配合 QHKIT_ENV=prod 或 QHKIT_BASE_HOST）
2. OpenClaw 机器文件 /root/.openclaw/qinghu_config.json（存在即用，无需额外配置密钥）
3. 用户配置文件 ~/.qhkit/config.json（由 config set 写入，供外部机器使用）

# 外部机器首次配置（密钥从上面的地址获取）
qhkit config set --token <你的密钥> --env prod
qhkit config show          # 查看当前解析结果（密钥打码）
qhkit config path          # 打印用户配置文件路径

env=prod → https://www.iqinghu.com；也可用 --base-host 直接指定。域名固定为 iqinghu.com 或 autoagc.com，其他域名会被拒绝。

用法

qhkit <命令> <action> '<json>'
qhkit <命令> <action> @params.json     # @file 读文件，@- 读 stdin

所有命令输出一行 JSON 到 stdout；出错时输出 {"ok":false,"stage":...,"message":...} 并以退出码 1 结束。

AI 图像 image generate | status | options

# 套图模式：参考图 + 自定义文案（有参考图时服务端 SSE 生成提示词）
qhkit image generate '{"modelLabel":"套图模式","uploadedImages":["https://x/a.jpg"],"customCopy":"限时5折","sizePreset":"1:1 商品主图 · 抖音","imageCount":4}'

# 专图模式：纯提示词直出商业大图
qhkit image generate '{"modelLabel":"专图模式","prompt":"化妆品高端场景图","sizePreset":"默认 1:1 2K（2048×2048）"}'

# 电商详情图：参考图 + 配色主题
qhkit image generate '{"modelLabel":"电商详情图","uploadedImages":["https://x/a.jpg"],"themeLabel":"海洋蓝"}'

# 查询状态（generate 内部已自带轮询，最长约 14 分钟）
qhkit image status '{"batchTaskId":"xxxx"}'

# 查询某模式的可选标签
qhkit image options '{"queryParams":["sizePreset","imageCount"],"modelLabel":"专图模式"}'

uploadedImages 支持公网 URL 或本地文件路径（本地文件会先上传换取 URL）。

AI 视频 video generate | status | options

# Seedance2.0：1 张参考图必填，可选 1 个参考视频
qhkit video generate '{"modelLabel":"Seedance2.0","prompt":"户外工作灯广告","uploadedImages":["https://x/a.jpg"],"uploadedVideo":"https://x/ref.mp4"}'

# 电商爆款直出Pro：至少 1 张参考图
qhkit video generate '{"modelLabel":"电商爆款直出Pro","prompt":"解说词：绝了！这款……","uploadedImages":["https://x/a.jpg"]}'

# 视频提交后返回 pending，用 status 轮询结果
qhkit video status '{"videoTaskId":"task-123"}'

视频创作 / 编辑（新增命令）

以下命令统一遵循三段式：options（查可选值 / 预估积分 / 模型或角色列表）、generate（提交任务，返回 stage:"pending" 与 taskId）、status（用 taskId 轮询，返回 stage:"done" 或继续 pending）。长视频任务提交后不可取消，status 只是查询、停止轮询不影响后端执行。

设计约定：generate 只提交不阻塞，轮询交给调用方按需重复 status（视频类任务最长可达 40 分钟）。SSE 类的脚本生成（storyboard script）在单次调用内同步返回。

一键成片 video-quick（VIDEO_QUICK）

qhkit video-quick options  '{"queryParams":["orientation","creative","language","score"],"duration":8}'
qhkit video-quick generate '{"prompt":"户外工作灯广告","duration":8,"creative":"1","orientation":"landscape","language":"zh","uploadedImages":["https://x/a.jpg","https://x/b.jpg"]}'
qhkit video-quick status   '{"videoTaskId":"123456"}'

• duration 8–60（默认 8）；creative 仅 2 为创意成片，其余为真实成片；orientation landscape|portrait|square；language zh|en；uploadedImages 1–7 张。

角色替换 / 模特换脸 video-replace（VIDEO_REPLACE）

# 可选：先从角色库选人物（取返回项的 icon 作为人物图）
qhkit video-replace options  '{"queryParams":["characters"],"personal":false,"characterType":"REALITY"}'
qhkit video-replace generate '{"originalVideoUrl":"https://x/v.mp4","uploadedImages":["https://x/face.jpg"],"duration":12}'
qhkit video-replace status   '{"videoTaskId":"123456"}'

• 必填 originalVideoUrl + 1 张人物图 + duration（原视频时长秒）。

视频翻译 video-translate

qhkit video-translate options  '{"queryParams":["sourceLanguage","targetLanguage","package"]}'
qhkit video-translate generate '{"videoUrl":"https://x/v.mp4","sourceLanguage":"zh","targetLanguage":"en","package":"全部"}'
qhkit video-translate status   '{"videoTaskId":"..."}'

• package：全部（字幕+语音+对口型）/ 字幕语音 / 仅字幕（也接受 full|voice|subtitle 或 3|2|1）。目标语言 14 种（不含 ru），需与源语言不同。

视频去水印 / 去字幕 / 画质提升 video-edit

qhkit video-edit options  '{"queryParams":["action","resolution","fps","score"],"action":"video_super_resolve","urls":["https://x/v.mp4"],"resolution":"4k","fps":60}'
qhkit video-edit generate '{"action":"remove_watermark","urls":["https://x/v.mp4"]}'
qhkit video-edit generate '{"action":"remove_subtitle","urls":["https://x/v.mp4"]}'
qhkit video-edit generate '{"action":"video_super_resolve","urls":["https://x/v.mp4"],"resolution":"4k","fps":60}'
qhkit video-edit status   '{"videoTaskId":"VIDEO_EDIT:xxxxx"}'

• action：remove_watermark / remove_subtitle（去字幕，以后端为准）/ video_super_resolve（需 resolution 1080p|2k|4k、fps 30|60）。urls 1–10 个（公网 URL 或本地文件）。

复刻爆款视频 video-inspire → videoScript

qhkit video-inspire generate '{"resourceUrl":"https://v.douyin.com/xxxx/"}'
qhkit video-inspire status   '{"inspireTaskId":276}'   # 成功返回 videoScript

爆款视频转图文 video-to-text → imageText

# id / fileUrl 通常取自 video-inspire status 的返回（link 入口用 playVideo，upload 入口用 inspireVideoUrl）
qhkit video-to-text generate '{"id":276,"playVideo":"https://x/v.mp4"}'
qhkit video-to-text status   '{"id":276}'              # data 非空即 imageText 正文

分镜脚本与分镜图 storyboard（两段式）

qhkit storyboard options  '{"queryParams":["models","score","viewDirection"]}'
qhkit storyboard script   '{"uploadedImages":["https://x/p.jpg"],"productName":"保温杯","pointDescription":"316不锈钢·24h保温"}'
qhkit storyboard generate '{"prompt":"<上一步得到的脚本全文>","uploadedImages":["https://x/p.jpg"],"viewDirection":"landscape"}'
qhkit storyboard status   '{"taskId":"..."}'

• script 用 SSE 同步产出脚本正文；generate 用脚本全文 + 商品图（1–5 张）创建分镜图任务。

活动海报 poster

qhkit poster options  '{"queryParams":["mode","language","themeLabel"]}'
qhkit poster generate '{"prompt":"全场8折 限时抢购","mode":"快图","themeLabel":"海洋蓝","language":"简体中文"}'
qhkit poster status   '{"taskId":"..."}'

• mode：快图（M4/QUICK_GENERATION）/ 精图（M3/ACCURATE_GENERATION）；themeLabel 见 options；默认尺寸 750×3688 webp。

开发

npm test        # 端到端冒烟测试（不联网，覆盖新增命令的 options 与校验）
node bin/cli.js image options '{"queryParams":["modelLabel"]}'
node bin/cli.js video-edit options '{"queryParams":["action"]}'

本机联调时若不在 OpenClaw 机器上，可用 OPENCLAW_CONFIG_PATH 指向别处或不存在的路径。开发 / 测试环境仅限内部使用（面向用户禁用），内部同学用 --base-host / QHKIT_BASE_HOST 显式指定。

日志默认写入 ~/.qhkit/logs/<ai_image|ai_video>/<日期>/runtime-<pid>.log，可用 QHKIT_LOG_DIR 覆盖；写日志全程 best-effort，不影响主流程。

发布到 npm

npm pack --dry-run          # 先确认打包清单，避免误传敏感文件
npm login                   # 或在 ~/.npmrc 配置 _authToken（对 @iqinghu scope 有写权限的 token）
npm publish                 # publishConfig.access=public 已声明；scoped 包首发也会公开发布

@iqinghu/qhkit 挂在 npm iqinghu 组织下，发布需要一个对 @iqinghu scope 有 Read and write 权限的 token。scoped 包默认私有，本包已在 package.json 里声明 publishConfig.access=public，首发即公开（也可显式 npm publish --access public）。版本号发布后不可覆盖，改动后需 npm version patch 再发。