LinkPix

LinkPix 是青虎工作台的全栈电商内容生产能力：从商品图、主图、详情页、电商套图，到批量修图、广告投放素材、带货视频与电影质感 TVC 广告大片；从 POD 印花、视频翻译与视频编辑，到爆款复刻脚本、视频转图文、分镜创作及短视频/达人数据分析，再到跨平台电商数据查询（选品、榜单、达人、关键词、竞品、1688 货源），均可在一个入口完成。

它不是单一的生图或生视频模型，而是把“做图 → 做视频 → 翻译与优化 → 复刻与分析”串成闭环的 AI 电商素材工作流。生图与生视频模型按线上实时目录选择，可响应用户对豆包生图、Seedream 5.0、Seedance、阿里万相 Wanx、MiniMax H3、可灵、HappyHorse、Vidu 等模型的使用需求。

0. 意图路由：用户想要什么 → 用哪个命令

模糊时优先问自己：产物是图还是视频？输入是文字、图，还是已有视频？按上表就能落到唯一命令。要的是数据（不是图或视频）就走 mcp。

能力边界：上表之外的媒体需求（如音乐/MV 生成、直播切片、长视频剪辑）qhkit 不支持——明确告知用户当前不支持，建议其到青虎工作台（ https://www.iqinghu.com ）确认能力或改用其他技能，不要硬套最接近的命令凑合。

1. 前置：环境自举（缺什么装什么，不要因为环境缺失放弃任务）

按顺序检测，缺失就地补齐：

1. 有 qhkit 吗？ qhkit config show 能跑通即已安装，跳到第 4 步。
2. 没有 qhkit 但有 node/npm（OpenClaw/Hermes 机器部署流程保证自带 Node 22+）→ 全局安装（推荐方式）：

   npm i -g @iqinghu/qhkit
   

   默认走 npm 官方源；官方源访问慢或超时（国内网络常见）时，再加镜像参数 --registry=https://registry.npmmirror.com（阿里维护的 npm 官方镜像，仅作网络兜底）。仅当全局安装因权限失败且无法提权时，才退而用 npx @iqinghu/qhkit <命令> ...（npx 必须写包全名）。
3. 连 node 都没有（要求 Node ≥ 18）：先装 Node 再回到第 2 步。

   # Linux 二进制安装（装到用户目录，无需 root；先校验官方 SHA256 再解包）：
   cd /tmp && curl -fsSLO https://nodejs.org/dist/v22.22.3/node-v22.22.3-linux-x64.tar.xz
   cd /tmp && curl -fsSL https://nodejs.org/dist/v22.22.3/SHASUMS256.txt | grep ' node-v22.22.3-linux-x64.tar.xz$' | sha256sum -c -
   mkdir -p "$HOME/.local/lib" && tar -xJf /tmp/node-v22.22.3-linux-x64.tar.xz -C "$HOME/.local/lib"
   export PATH="$HOME/.local/lib/node-v22.22.3-linux-x64/bin:$PATH"
   

   校验行输出 OK 才继续；校验失败就删掉重下，绝不解包未通过校验的文件。nodejs.org 访问不通时，把两个下载 URL 的前缀 https://nodejs.org/dist 整体换成镜像 https://registry.npmmirror.com/-/binary/node（目录结构相同，SHASUMS256.txt 也有镜像，校验步骤不变）。export PATH 只对当前 shell 生效，跨命令调用时每个新 shell 都要先执行这行（或追加进 ~/.bashrc）。macOS 用 brew install node；Windows 用 winget/官网安装包。arm64 机器把 x64 换成 arm64。
4. 密钥：无密钥时（命令返回 stage:"config"），把下面的引导文案发给用户，拿到密钥后执行 qhkit config set --token <密钥> --env prod（或设环境变量 QHKIT_TOKEN）：

   1. 打开 https://www.iqinghu.com/workbench/login?type=1&urlCode=1788417429126 注册/登录
   2. 进入控制台 → 工作台的 APIKeys 页面：https://www.iqinghu.com/workbench/dashboard/api-keys?urlCode=1788417429126
   3. 点「创建/复制」生成密钥，生成后将 API 密钥发我

   图文获取密钥教程：https://xcnzsfe4uxrw.feishu.cn/wiki/KJ0Ywsyw8iAXmRkz5l4cddDbn6g

5. 自检：qhkit config show 输出脱敏配置即全部就绪。 核对站点（本技能对接国内版 iqinghu.com）：config show 返回的 site 必须是 cn。是 intl（baseHost 为 autoagc.com）说明本机残留了国际版配置——不要按国际站引导用户取密钥，也不要拿国际站的模型清单答复（那边是 gpt-image-2 / gemini-3.1-flash 这类底层模型名，和本技能对不上）；直接把第 4 步的国内站取密钥文案发给用户，拿到密钥后执行 qhkit config set --token <密钥> --env prod 覆盖。source 为 env 时配置来自环境变量，要请用户删掉 QHKIT_TOKEN / QHKIT_ENV 或把 QHKIT_ENV 改成 prod。只有用户明确说自己用的是国际版（AutoAGC）账号时才保留 intl。调用报 401 / 未登录时同样先跑 config show 核对站点：国内版密钥配在国际站必然 401。

更新方式：qhkit 已全局安装时，升级同样由你（智能体）执行全局安装完成：

npm i -g @iqinghu/qhkit@latest

官方源慢或超时时同样加 --registry=https://registry.npmmirror.com。出现以下任一信号就先升级再继续：命令返回 {"ok":false,"stage":"version",...}（版本门禁：有新版时 generate/script 会被直接阻断，message 里就是升级命令，照做即可）；命令返回 {"ok":false,"stage":"runtime","message":"未知命令：<命令>。运行 qhkit --help 查看用法。"}（本机 qhkit 太老、还没有这个命令——注意这条不会被版本门禁拦下，stage 是 runtime 不是 version，别当成用法错误）；stderr 提示有新版本；命令报「模式在线上已下架或配置变更，请升级 qhkit」。升级后重试原命令。（video 的模型清单 0.12.0 起实时读取，线上新增模型不需要升级 CLI；时长自选需要 0.13.0+——旧版本不认模型名 + duration 的写法，报「不支持 N 秒」时先升级；mcp 命令需要 0.14.0+，报「未知命令：mcp」时先升级。）

安装/配置失败时把具体报错告诉用户（常见：无写权限 → 提示用户提权或改用 npx；无网络 → 让用户处理网络）。

2. 统一调用契约（所有命令一致）

qhkit <命令> <action> '<json>'
qhkit <命令> <action> @params.json     # 参数写进文件，避免 shell 转义问题（推荐）

• action 三段式：options（查可选值/列表）→ generate(提交) → status(轮询)；mcp 例外，走 search/list → describe → estimate → call（见第 4 节）。storyboard 多一个 script；ad 用 templates 查模板；pod 另有 products 查产品图库；image/video/ad/pod/workflow 另有 estimate（报价）——与 generate 完全相同的参数，返回本次提交会实际扣除的积分（credits）与余额是否足够（enough），不提交任务。前四个基本不上传文件、秒回；例外：workflow estimate 会真上传本地素材（工作流报价需要真实素材 URL），video estimate 带本地参考视频时也会先上传（按参考视频实际时长计价）。
• stdout 恒为一行 JSON；成功含业务字段，失败为 {"ok":false,"stage":"...","message":"..."} 且退出码 1。把 message 原样转告用户即可。
• Windows 防乱码：Windows 上经 PowerShell 调 qhkit 时，stdout 里的中文会按系统代码页 GBK 解码成乱码（如「专图模型」变成「涓撳浘妯″瀷」），模型名、选项、报错都对不上——看到乱码不要据此判断模型或选项不存在。每条 qhkit 命令在同一行先切 UTF-8 再调用：[Console]::OutputEncoding=[Text.Encoding]::UTF8; qhkit <命令> <action> @params.json；仍有乱码就加全局参数 --out result.json（qhkit 0.15.0+），stdout 只回一行纯 ASCII 的文件路径，再按 UTF-8 读该文件拿完整结果。PowerShell 5.1 还会吞掉命令行 JSON 里的双引号（报「json_args 解析失败」），Windows 上参数一律写进文件走 @params.json。macOS / Linux / Git Bash 不受影响。
• 返回是直接的数据结果（无预渲染呈现字段）：产物 URL 从 images / videos / primaryVideo 取，文本产物在 videoScript / imageText / script，积分在 credits，任务号在各类 taskId 字段。如何展示给用户由你按当前环境决定。
• stderr 可能出现提示行（如版本/模型目录告警），不是错误，不要当成失败。
• 传参里的 uploadedImages / urls / 视频参数直接填本地文件路径即可（CLI 自动上传换取 URL，这是最常见用法）；素材已在公网上时也可以直接填 http(s) URL。唯一例外：video-inspire 的 resourceUrl 只收 http(s) 链接（抖音等平台分享链接，后端按链接拉取，不是上传文件）。
• 图片体积上限 10MB：3–10MB 的本地图 CLI 会在上传后自动追加 COS 缩略参数（2048px 内等比缩小、只缩不放）防止大图导致下游断连，此时 stderr 有一行提示——是提示不是错误。公网 URL 只对青虎/COS 域名做该处理；用户给的外站大图 URL 建议先下载到本地再以路径传入，让 CLI 走这条防线。
• 超过 10MB 被拦下时，不要把问题抛回给用户，你（智能体）就地压缩后重试（目标：2048px 内等比缩小、只缩不放，输出 jpg；压完把新文件路径传回原命令重试一次）。只走两条路，按序探测：
  1. 优先 Python（python --version 或 python3 --version 能跑即可；缺 Pillow 先装：pip install pillow -i https://pypi.tuna.tsinghua.edu.cn/simple）： python -c "from PIL import Image, ImageOps; im=ImageOps.exif_transpose(Image.open('原图')); im.thumbnail((2048,2048)); im.convert('RGB').save('压缩后.jpg', quality=85)"
  2. 没有 Python 就用 Node（qhkit 能跑说明 Node 一定在），用 npm 的 sharp-cli 压缩： npx --yes sharp-cli -i 原图 -o 压缩后.jpg resize 2048（首次联网下载，之后有缓存；官方源慢时加 --registry=https://registry.npmmirror.com） 外站大图 URL 同理：先下载到本地再走上面的流程。两条路都失败才如实告知用户，请其提供 10MB 内的图片；压缩重试仍失败则转述 CLI 的 message，不要反复重试。
• 标签类参数（modelLabel、sizePreset、themeLabel 等）必须与 options 返回的候选值逐字一致，不要自造或翻译。拿不准就先调 options。
• video 与 image 的模型清单都是实时的（0.12.0 起直接读线上目录，新增/下架/调价自动跟随，无需升级 CLI），且均无默认模型——modelLabel 必填，缺失会报错并列出当前可选项。当次会话第一次选模型前先跑 options 查 modelLabel/models 拿当前清单，不要凭记忆或本文档的快照直接报模型名。拉不到目录（断网/密钥问题）时命令会明确报错，按提示引导用户检查配置。

⛔ 提交前必须经用户确认（硬规则）：任何会创建任务、消耗积分的 action（各命令的 generate，含 storyboard 的 script；mcp 付费工具的 call 按第 4 节 mcp 的授权规则）发起前，必须先把本次提交的关键参数一次性列给用户——模型/模板、出图张数或视频时长（秒）、尺寸与画质、语言、用到哪几张参考图，以及 estimate 报出的预计扣除积分——等用户明确同意后才能执行提交。参数全部来自用户原话时也要复述确认一遍（口头描述与实际枚举值可能有出入，任务提交后不可取消）。只读 action（options / estimate / status / templates / products / config show，以及 mcp 的 search / list / describe / estimate）无需确认，可直接调用。

3. 轮询规则（重要）

• image generate 自带轮询：命令会阻塞到出图或超时（最长约 14 分钟），返回里直接有图片 URL，不需要再查 status。pod generate 与 ad generate 的图片线同此（阻塞到出图）。
• 其余视频类 generate 只提交（含 ad 的视频线）：立即返回 stage:"pending" + 任务 ID，需重复调 status 直到 stage:"done"（返回里含产物 URL）或报错。
• 建议轮询间隔：图片 15–30 秒；视频 30–60 秒。视频任务最长可达 40 分钟，不要提前放弃，也要告知用户耗时预期。
• 任务提交后不可取消；停止轮询不影响后端继续生成，任务 ID 要保留并告知用户。

4. 命令速查

image — AI 生图（modelLabel 必填，清单实时）

固定两模式（套图模式 / 电商详情图，专属流程）+ 自定义生图家族（实时清单）：businessType=image 下除套图外的全部可见模型，线上新增/下架/调价自动跟随。没有默认模型——modelLabel 必填，先 options 查 modelLabel/models 拿当前清单再选。

时点参考（2026-08-25 目录，仅帮你建立感觉，以 options 实时返回为准）：

2K 档位约为 1K 的两倍；参考图超过免费张数（3 张）后每张另有小额加价——这些 estimate 都会自动算进去。

中间四个是自定义生图家族，入参完全一致（prompt 必填 + 可选 uploadedImages/sizePreset/imageCount），只是画质取向和积分不同。规范标签即线上模型名（历史写法 专图模式 等仍作为别名可用）；用户没指定模型时，把候选（含 models 里的卖点与单价）列给用户选，不要替用户拍板。

⚠️ 全部 6 个模式都接受参考图（自定义生图四模型为可选，是图生图语义，2026-08-20 实测智慧模型带参考图出图与原图细节逐一对齐）。用户给了商品图就传进 uploadedImages，不要只把图的内容转写成 prompt 文字（会丢原图细节），更不要说"某模式不支持参考图"。

# 套图：参考图 + 可选文案 + 发布平台（imageCount 1/6/7/8/9/10，缺省 9）
qhkit image generate '{"modelLabel":"套图模式","uploadedImages":["./素材/商品图.jpg"],"customCopy":"限时5折","platform":"抖音","imageCount":6}'
# 自定义生图：提示词直出，参考图可选（imageCount 1/2/4/6/8/10）
qhkit image generate '{"modelLabel":"专图模型","prompt":"化妆品高端场景图","sizePreset":"默认 1:1 2K（2048×2048）"}'
qhkit image generate '{"modelLabel":"智慧模型","prompt":"化妆品高端场景图","imageCount":2}'
# 自定义生图 + 参考图（用户给了商品图时这样调，严格基于原图出图）
qhkit image generate '{"modelLabel":"智慧模型","prompt":"军绿色应急收音机电商主图，专业棚拍质感","uploadedImages":["./素材/收音机.jpg"],"imageCount":2}'
# 详情图：参考图 + 配色主题
qhkit image generate '{"modelLabel":"电商详情图","uploadedImages":["./素材/商品图.jpg"],"themeLabel":"海洋蓝"}'
# 提示词润色：商品图/产品名/卖点至少给一个，返回 AI 写好的生图提示词（不建任务、不扣生图积分）
qhkit image polish '{"uploadedImages":["./素材/商品图.jpg"],"productName":"保温杯","pointDescription":"钛合金内胆 24h 保温"}'
# 报价：generate 同参数换个 action，返回本次实际会扣的积分（含折扣/画质/免费额度）——报积分给用户前先跑这条
qhkit image estimate '{"modelLabel":"套图模式","uploadedImages":["./素材/商品图.jpg"],"imageCount":6}'
# 选型速查：各模型卖点 + 实时积分 + 免费额度（不确定选哪个时先跑这条）
qhkit image options '{"queryParams":["models"]}'
# 可选值查询（sizePreset/platform/themeLabel/imageCount 因模式而异，务必带 modelLabel 查）
qhkit image options '{"queryParams":["sizePreset","imageCount"],"modelLabel":"图片 5.0 Pro"}'

套图/详情图需要至少一张参考图；自定义生图必须有 prompt（参考图可选）。generate 返回即含图片 URL（自带轮询）。 sizePreset 逐模型不同（自定义生图四模型的尺寸表各自独立），不要把一个模型的尺寸标签套到另一个模型上——先 options 查。 默认画质是 1K；要 2K（价格约为 1K 两倍）时显式传 "quality":"2K"。套图默认出 9 张（与官网一致）——确认参数时务必把张数、画质与 estimate 积分报给用户，积分数字一律以 estimate 返回值为准。 套图发布平台用 platform 传（淘宝/抖音/拼多多/1688/京东/Amazon/Shopee/TikTok Shop/Lazada/Temu/Ozon/Wildberries/SHEIN，options 查 platform 看全量）：影响套图的构图与文案排版策略，用户提到目标平台就传上。

image-batch — 批量生图玩法（mode 六选一）

官网首页「AI 能力」卡片对应的批量玩法，全部自带轮询（阻塞到出图）。没有数量参数——出图张数由 prompts / 图片 / 动作条数决定（单批上限 10）：

qhkit image-batch options '{}'   # 六种 mode 的参数说明
qhkit image-batch generate '{"mode":"批量生图","prompts":["白底图","户外场景图"],"uploadedImages":["./素材/商品图.jpg"]}'
qhkit image-batch generate '{"mode":"批量改图","prompt":"统一换成纯白背景","uploadedImages":["./a.jpg","./b.jpg"]}'
qhkit image-batch generate '{"mode":"批量替换","referenceImages":["./场景1.jpg","./场景2.jpg"],"productImage":"./产品.jpg","productName":"保温杯"}'
qhkit image-batch generate '{"mode":"主图复刻","referenceImages":["./爆款主图.jpg"],"productImages":["./我的产品.jpg"]}'
qhkit image-batch generate '{"mode":"姿势套图","uploadedImages":["./连衣裙.jpg"],"poseActions":["双手叉腰正面站立","侧身回眸"]}'
qhkit image-batch generate '{"mode":"批量译图","prompt":"翻译成英语","uploadedImages":["./中文主图.jpg"]}'
qhkit image-batch estimate '{"mode":"姿势套图","uploadedImages":["./连衣裙.jpg"],"poseActions":["正面","侧面"]}'   # 报价（姿势套图每张 +0.5 积分）

• 批量生图/改图/替换/姿势套图必须传 modelLabel（自定义生图家族，实时清单、无默认，先 image options 查 modelLabel）与可选 sizePreset/quality；主图复刻与批量译图的模型固定。
• 批量替换的 referenceImages 元素可写 {"url":"...","replaceText":"替换到图中的花瓶位置"} 指定替换部位；主图复刻同理可带 hint（自定义复刻要求），或整体传 "removeText":true 去除参考图文字。
• 批量译图按张计费；姿势套图不走免费额度。

video — AI 生视频（modelLabel 写模型名，时长用 duration 自选，清单实时）

与青虎工作台一致（2026-08 起）：一个模型一个 modelLabel（如 Seedance2.5），时长用 duration 在该模型的范围内按秒自选——区间型（如 Seedance2.5 5–30 秒任选整数）或档位型（如 电商热卖引擎 只有 10 / 15 秒）。duration 必须传（只有一个时长的模型如 Viduq2-turbo 可省略）：没传时 CLI 会报错并给出该模型的可选范围与写法，照提示补上即可。积分按「每秒单价 × 时长」计，所以时长直接影响价格。历史写法 Seedance2.0 15秒 仍可用（等价于 modelLabel + duration），但新写法优先。

模型清单实时读取线上目录：新增/下架/调价/维护/限时折扣自动跟随，没有默认模型——modelLabel 必填，不传会报错并列出当前可选项与各自时长范围。流程固定为：先 options 查 models 拿当前清单、时长范围和能力规则，和用户定下模型与时长后 estimate 报价，确认后 generate。

# 第一步永远是它：当前有哪些模型、各自可选时长（durationRange/durationOptions/defaultDuration）、按秒单价、参考图/视频/音频/画幅规则、活动角标
qhkit video options '{"queryParams":["modelLabel","models"]}'
# 素材既可以是公网 URL，也可以是本地文件路径（本地文件 CLI 会自动上传换取 URL）
qhkit video generate '{"modelLabel":"Seedance2.0","duration":12,"prompt":"户外工作灯广告","uploadedImages":["./素材/商品图.jpg"],"uploadedVideo":"./素材/参考视频.mp4"}'
qhkit video generate '{"modelLabel":"全能电商2.0","duration":8,"prompt":"户外工作灯广告","uploadedImages":["./素材/商品图.jpg"]}'
qhkit video status   '{"videoTaskId":"task-123"}'
# 报价：generate 同参数换个 action——报积分给用户前先跑这条（时长不同价格不同，duration 一定要带上）
qhkit video estimate '{"modelLabel":"Seedance2.0","duration":12,"uploadedVideo":"./素材/参考视频.mp4"}'

• 生成的视频自带声音（所有模型都是）：台词、旁白、口播、音效等由 prompt 决定。

options 的 models 每个模型一条，给全选型所需字段：时长规格 durationMode（range 区间 / options 档位 / fixed 固定）+ durationRange 或 durationOptions + defaultDuration；creditsPerSecond（按秒单价）与 credits（默认时长的参考价）；description/propertyTags（效果、稳定性、提示词要求、画质）、activityBadge（如「限时6折」）、free、supportsBatch:false（只能生成 1 条）、maintenance、notice（如「即将下线」）、category；参考素材规则（见下）。

时点参考（2026-09-24 国内版目录，仅帮你建立感觉，以 options 实时返回为准）：10 个模型、时长 5–30 秒自选。Seedance2.5（5–30 秒，参考图必填，参考视频≤10、参考音频≤3，约 3.6 积分/秒）、阿里wanx3.0（5–30 秒，限时折扣，参考视频≤5 且「参考视频总时长 + 生成时长」≤30 秒，约 1.8 积分/秒）、Seedance2.0/全能电商2.0（5–15 秒，经典带货档，参考视频≤3）、MiniMax H3（5–15 秒，约 1 积分/秒性价比档，768p，有 超宽屏 21:9，收参考音频不收参考视频）、可灵3.0 Omni（5–15 秒，参考图必填，仅 jpg/png）、Viduq3-turbo（原「品牌质感大片」，5–16 秒，参考图必填，提示词要求「精准」）、Viduq2-turbo（原「品牌质感大片 5秒」，仅 5 秒首尾帧，免费额度内，只能 1 条）。

怎么选：

• 默认推荐顺序（用户没点名模型时）：Seedance2.5 → 阿里wanx3.0 → Seedance2.0 → 全能电商2.0。按这个顺序列候选（含时长范围与按秒单价），排第一的标为推荐，用户没有异议就用它；某个模型不满足本次条件（没有必填的参考图、时长超出范围、不支持用户要的参考视频/音频、维护中）就顺延到下一个，并告诉用户原因或请用户补齐素材。其他模型只在用户点名时使用；用户点名了就以用户为准。

• 按用户诉求在 models 里过滤：要模仿运镜 → supportsReferenceVideo: true；要用用户自带的音频 → supportsReferenceAudio: true；纯文字起步 → referenceImageRequired: false；要长视频（>15 秒）→ 看 durationRange 上限。

• 时长：用户说了时长就用用户的（CLI 会校验是否在该模型范围内，超出会报错并给出可选范围）；没说就先问用户，或提议 defaultDuration 并在确认参数时明确告诉用户时长、可以改——提交时一定显式传 duration。带货短视频常见 8–15 秒。

• 提示词要求（propertyTags 的「提示词要求」）：「简单/简洁」的模型一句话卖点即可；「精准」的模型（如 Viduq3-turbo、阿里wanx3.0）给一句话会出废片，先帮用户把镜头、光影、材质补充完整再提交。

• maintenance: true 的模型不可提交（CLI 会拦截），notice 里有「即将下线」的不要再推荐。

• 参考图规则按模型走（options 的 models 里逐条给出）：multi_reference 多张（上限见 maxReferenceImages，7–30 张不等）、每张可带 imageUsage 用途文案；first_frame 只收 1 张首帧；first_last_frame 收 2 张（首帧在前、尾帧在后），这两种模式不接受用途文案。referenceImageRequired: true 的模型强制要图：用户没给商品图时先要图，不要只凭文字描述提交；estimate 返回里带 referenceImageRequired: true 就说明本次入参还没有图，确认参数时一并向用户索要。referenceImageRules 给出格式、最短边、宽高比要求，不符的本地图 CLI 会在上传前报错。

• 参考视频（uploadedVideo）只有 supportsReferenceVideo: true 的模型支持，可传数组，上限见 maxReferenceVideos；referenceVideoRules 给出格式、单条时长、总时长，以及个别模型的「参考视频总时长 + 生成时长」上限（inputOutputDurationLimit）——超了 CLI 会报错并算出当前还能选的最长生成时长，照着调 duration 或换短一点的参考视频。

• 参考音频（uploadedAudio，用户自带的音频文件）只有 supportsReferenceAudio: true 的模型支持，上限见 maxReferenceAudios；referenceAudioRules 给出格式（多为 wav/mp3）与时长要求。

• orientationLabel 逐模型不同（models 里 orientationLabel 给全）：常见 竖屏 9:16（默认）/ 横屏 16:9 / 方屏 1:1 / 3:4 / 4:3，个别模型有 超宽屏 21:9；新画幅 code 会原样透传，照 options 返回的写。

• languageLabel 可选（如 英语，17 种语言与生图一致），不传由服务端按提示词决定；count 1–8（supportsBatch: false 的模型只能 1）。

分工记清楚：多模型间权衡选型 → options 的 models（实时目录：时长范围、按秒单价、卖点、免费额度、maintenance 维护拦截、notice、activityBadge）；确定模型与时长后向用户报积分 → estimate（与提交走同一个计价接口，时长、折扣、条数、参考视频实际时长全都算进去，返回值就是实扣值；带本地参考视频时会先上传，需要等一会儿）。options 里的 credits 只是默认时长的参考价，不要拿它报价。

video-quick — 一键成片

qhkit video-quick generate '{"prompt":"户外工作灯广告","duration":8,"creative":"1","orientation":"landscape","language":"zh","uploadedImages":["./素材/图1.jpg","./素材/图2.jpg"]}'
qhkit video-quick status   '{"videoTaskId":"123456"}'

uploadedImages 1–7 张；duration 8–60；creative 2=创意成片、其余=真实成片；orientation landscape|portrait|square；language zh|en。

video-replace — 角色替换/换脸

qhkit video-replace options  '{"queryParams":["characters"],"personal":false,"characterType":"REALITY"}'   # 角色库选人，取 icon 当人物图
qhkit video-replace generate '{"originalVideoUrl":"./素材/原视频.mp4","uploadedImages":["./素材/人物.jpg"],"duration":12}'
qhkit video-replace status   '{"videoTaskId":"123456"}'

必填：原视频（本地文件或 URL）+ 1 张人物图 + duration（原视频时长秒数）。

video-translate — 视频翻译

qhkit video-translate generate '{"videoUrl":"./素材/带货视频.mp4","sourceLanguage":"zh","targetLanguage":"en","package":"全部"}'
qhkit video-translate status   '{"videoTaskId":"..."}'

sourceLanguage zh|en；目标语言 14 种（无 ru，可 options 查）；源=目标允许（同语言重配音/压字幕场景）。package：全部（字幕+语音+对口型）/字幕语音/仅字幕。

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

qhkit video-edit generate '{"action":"remove_watermark","urls":["./素材/视频.mp4"]}'
qhkit video-edit generate '{"action":"remove_subtitle","urls":["./素材/视频.mp4"]}'
qhkit video-edit generate '{"action":"video_super_resolve","urls":["./素材/视频.mp4"],"resolution":"4k","fps":60}'
qhkit video-edit status   '{"videoTaskId":"VIDEO_EDIT:xxxxx"}'

action 三选一（去字幕就是 remove_subtitle）；超分需 resolution 1080p|2k|4k + fps 30|60；urls 1–10 个。

video-inspire — 复刻爆款 → 视频脚本

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

产物是脚本文本，不是视频；拿到脚本后可续接 video / video-quick 生成成片。

⏱ 耗时与第 3 节的通用视频轮询预期不同：脚本通常 1 分钟内出，轮询 20–30 秒一次即可；超过 10 分钟仍是 pending，说明后端已判超时失败，不要按「视频最长 40 分钟」继续空等，重新提交一次即可。

video-to-text — 视频转图文

qhkit video-to-text generate '{"id":276,"playVideo":"https://x/v.mp4"}'
qhkit video-to-text status   '{"id":276}'               # data 非空即图文正文

id/视频 URL 通常取自 video-inspire status 的返回。

storyboard — 分镜脚本 + 分镜图（两段式）

qhkit storyboard script   '{"uploadedImages":["./素材/商品图.jpg"],"productName":"保温杯","pointDescription":"316不锈钢·24h保温"}'   # 同步返回脚本全文
qhkit storyboard generate '{"prompt":"<上一步脚本全文>","uploadedImages":["./素材/商品图.jpg"],"viewDirection":"landscape"}'
qhkit storyboard status   '{"taskId":"..."}'

先 script（单次调用同步出脚本），再把脚本全文作为 prompt 提交 generate（商品图 1–5 张）。

ad — 广告素材（模板驱动，视频 / 图片两条线）

qhkit ad templates                      # 模板列表：templateId、materialType（AD_VIDEO/AD_IMAGE）、数量与时长约束
qhkit ad estimate '{"templateId":3}'
qhkit ad generate '{"templateId":3,"prompt":"户外工作灯促销广告","uploadedImages":["./素材/商品图.jpg"]}'
qhkit ad status   '{"videoTaskId":"..."}'   # 视频线模板
qhkit ad status   '{"batchTaskId":"..."}'   # 图片线模板

• 必须先 templates 拿 templateId（模板由运营配置，随时增减）；CLI 按模板 materialType 自动走视频线或图片线，modelSkuId 由服务端按模板覆盖，不用选模型。
• 视频线 generate 只提交（轮询 status，任务 ID 在 videoTaskId）；图片线 generate 自带轮询，返回即含图片 URL（任务 ID 在 batchTaskId）。
• duration / orientation / 生成数量必须落在模板允许范围内（templates 返回里逐项给出），越界会在提交前被本地拦截。

pod — POD 印花素材（提取 / 贴合 / 裂变）

qhkit pod options  '{"queryParams":["mode","quality","imageCount"]}'
qhkit pod products '{}'                  # 产品分类列表；{"category":"..."} 查该分类的产品底图（贴合选品用）
qhkit pod estimate '{"mode":"STAMP_FISSION","imageCount":4}'
qhkit pod generate '{"mode":"STAMP_EXTRACT","prompt":"保留主体图案","images":["./素材/印花衫.jpg"]}'
qhkit pod generate '{"mode":"STAMP_APPLY","prompt":"贴合自然","images":["https://x/p.png"],"productImages":["https://x/shirt.jpg"],"positions":["胸前居中"]}'
qhkit pod status   '{"taskId":"..."}'

• mode 三选一：STAMP_EXTRACT 印花提取（从图片提取干净印花）/ STAMP_APPLY 印花贴合（把印花贴到产品图上，必须传 productImages，底图可用 products 选）/ STAMP_FISSION 印花裂变（衍生同风格新印花，imageCount 1/2/4/6/8/10）。中英文别名（提取/贴合/裂变、extract/apply/fission）也认。
• generate 自带轮询（返回即含图片 URL）；images 1–10 张；提取/贴合的出图张数 = images 张数，不用传 imageCount。
• 免费额度：提取/贴合在仅提交 1 张图时有单张免费额度，传 "freeTask":true 免积分提交（用户明确要省积分/试用时优先建议）。

workflow — AI 工作流应用（青虎工作台「AI 应用」）

qhkit workflow list                                    # 线上目录：名称 / code / id / 目录价 / 计费方式
qhkit workflow options  '{"workflow":"电影质感TVC广告大片"}'   # 该应用的表单字段（中文字段名、必填、可选项）
qhkit workflow benefit  '{"workflow":"wf_001"}'         # 订阅与免费次数
qhkit workflow estimate @params.json
qhkit workflow generate @params.json
qhkit workflow status   '{"logId":"75141"}'
qhkit workflow stop     '{"logId":"75141"}'

• workflow 收应用名 / code / id，名称模糊匹配（全角半角括号、首尾空格都容忍）；名字对不上时用 list 返回的 code。
• list / options 返回里 supportsSchedule: true 表示该应用支持定时 / 周期执行——那是工作台里的配置，CLI 只能一次性提交，用户想要定时就引导他去工作台设。
• options 不传 workflow 时不报错，返回的是 stage:"list" 的全量目录（等同 list）。看到 stage:"list" 说明你漏传了 workflow，补上再查一次，别把目录当成字段表。
• fields 的键就是 options 返回的中文字段名（label），一字不差地照抄。字段表由线上定义，不要凭快照硬编，先跑 options。中文键建议用 @params.json 传参，避免 shell 转义问题。
• 图片/视频字段填本地路径即可（CLI 自动上传）；选择类字段填中文选项名。
• 音频字段（如仿拍类应用的「声音」）和图片/视频一样，本地路径直接给就行：音频与视频共用上传通道，2026-08-18 实测 .mp3 上传通过。若真遇到「不支持的文件类型」，如实告诉用户改用已上传的音频链接，不要反复重试。
• 字段校验从严，不会静默截断：单值字段（单图 / 单视频 / 选择类 / 数字 / 普通文本）传了多个值会直接报「字段「X」只接受 1 个值，收到 N 个」；数组字段超 maxCount、文本超 maxlength、值不匹配 pattern 也都在提交前报错。别靠"多传几个反正它只取第一个"——先看 options 里该字段有没有 isArray / maxCount，是单值就只给一个。
• 只提交不阻塞：generate 返回 logId，用 status 每 15 秒轮一次到 stage:"done"；工作流最长可跑约 40 分钟。
• generate 返回里带 logIdUncertain: true 时要多一步核对：这次没拿到 taskId，logId 是按「该应用最新一条任务」兜底取的，可能指向上一次任务。拿到 status 结果后先看 createTime 是不是刚才那一刻，对不上就去工作台「AI 应用 - 任务」确认，不要把上一次的产物当成这次的交付。
• 产物在 videos/primaryVideo（视频）、images（图片）、files（数据类应用的 xlsx）、texts（文本产物，如数据引擎的分析结论、生成的文案——别漏了它，有些应用只出 texts 不出文件）；credits 是实扣值，refundedCredits 是预扣多退回的部分。
• 多为订阅制付费应用：未订阅且免费次数用完时 generate 会被直接拦下，如实转告开通入口，不要重试。

mcp — 青虎电商数据工具（选品 / 榜单 / 达人 / 关键词 / 竞品 / 1688 货源）

用户说的"青虎 MCP 工具 / 青虎数据工具 / 青虎数据接口"指的就是本命令——不需要、也不要去宿主环境里找或配置 MCP server，直接用 CLI。工具有 200+ 个且持续增加，不要凭记忆写工具名，一律现查。

能做什么（平台 × 功能类型，具体工具以 search / list 为准）：

qhkit mcp search   '{"query":"<用户原话或你提炼的需求>"}'       # ① 3~5 个候选：name / 中文名 / 平台 / 功能类型 / 简介
qhkit mcp describe '{"names":["<name>","<name>"]}'            # ② 完整说明 + inputSchema + 计费（一次 ≤8 个，免费）
qhkit mcp estimate '{"names":["<name>"]}'                     # ③ 单次基价（青虎积分）
qhkit mcp call     '{"name":"<name>","params":{}}'            # ④ 用户同意后调用，credits 为实扣积分
qhkit mcp list     '{"platform":"shopee","category":"店铺"}'  # 兜底：全量工具名，可按 platform / category 过滤

• 找工具：search 直接传用户原话即可（CLI 会剥掉"青虎 / MCP / 工具"之类的套话，effectiveQuery 回显实际检索词）。返回 stage:"menu" 说明用户没说要查什么——把菜单里的能力列给用户问清楚，不要随便挑一个工具调。没说平台时候选会跨平台混排，先问清平台。候选都不对：换个说法（写清平台 + 对象，如「Shopee 店铺榜单」）再 search 一次 → list 按平台看全量 → 仍没有就如实说青虎暂不支持，不要用名字相近的工具凑合，也不要改用浏览器抓网页。
• 填参数：照 describe 的 inputSchema 填，不要猜。call 会先本地校验，不合法返回 stage:"validate"（未发起、未扣费），按 details.inputSchema 改完重试。日期、站点、类目 ID 这类值看说明里写的来源（类目 ID 先用类目工具查，别编）；related 列的是同类的后续步骤工具。
• 计费与授权：billing.free:true 的工具不扣积分。付费工具首次调用前，把本次要用的全部工具（中文名 + 用途）和 estimate 的基价一次性列给用户，征得同意后本会话内不再重复询问；用户只同意一部分时，未同意的不调用。基价只是单次参考，按结果量计费的工具实扣会更高，报价说「约 X 积分起，以实际扣费为准」。实扣以 call 返回的 credits 为准（已是青虎积分），不要引用业务数据里自带的积分字段。同一轮付费调用不超过 10 次；参数报错先想清楚再重试，不要连环试错。
• 用结果：小结果直接在 data 里；大结果返回 large:true + file（完整 JSON 文件路径）+ 记录数、字段与前几条预览——后续筛选、统计、导出都基于 file，不要逐行抄写，也不要凭预览推断全量。记录多时整理成表格文件交付，回复里结论先行，数字标明平台、站点与周期。
• 角色为 ERP 的工具（妙手 / 晓风 / 蜂鸟及 ERP 授权）需要专用技能指导，本技能不调用；用户要上货、铺货或做 ERP 操作时，告诉用户需要使用对应的 ERP 技能。
• 失败时转述 message；401 CLI 已自动重试过，先 qhkit config show 确认密钥再请用户检查。

5. 与用户的交互节奏

• 报价规则（硬性）：凡是要把积分消耗数字报给用户（确认参数、答复"要花多少积分"），image/video/ad/pod/workflow 必须先跑 estimate（generate 同参数），报它返回的 credits；不要引用本文选型表或 options 里的数字报价——那是会漂移的快照/目录价，estimate 才是实扣值。enough:false 时提前告知余额不足。estimate 失败（stage:"estimate"）或该命令不支持 estimate（video-quick 等）时，如实说「以实际扣费为准」，不要编数字。mcp estimate 只给单次基价（baseCredits），按第 4 节 mcp 的口径报。
  • workflow estimate 有一种「成功但没报出价」的分支：返回 ok:true / stage:"estimate"，但没有 credits，只有 creditsNotice（线上未返回预估积分，文案里给的是目录价）。这不是失败，别当报错处理，也别把缺失的 credits 读成 0 或自己补一个数——把 creditsNotice 的原话转告用户即可。
  • video estimate 带本地参考视频时会先上传（服务端按参考视频实际时长计价）；只想问价可以先给已有的 http(s) URL。
  • workflow estimate 会真实上传本地素材（image/ad/pod 的 estimate 都不上传）：工作流报价需要真实素材 URL，按视频秒数计费的应用尤其依赖它。素材大时报价会等上传，只想问价可以先给一个已有的 http(s) URL。
• 提交前必须确认（见第 2 节硬规则）：无论参数是否齐全，generate 前都要把模型/模板、张数或时长、尺寸/画质、语言、参考图与 estimate 预估积分列给用户，用户明确同意后才提交。意图模糊（没说清模式/尺寸/语言等且默认值可能不符预期）时，先用 options 的候选值和用户对齐再确认，不要替用户猜大参数。
• 提交后立即告知：任务 ID、预计耗时、正在轮询；完成后汇报产物。
• 交付（产物要让用户当场看见）：交付格式以工作区 AGENTS.md「媒体产物的交付格式」节为准， 本技能不另行规定；不要只甩一串裸 URL 让用户自己点开——那等同于没交付。
  • 青虎工作台 web 会话：图片、视频只发 artifact 标记行，每个产物单独一行、原样输出、 不放进代码块：<qinghu-artifact type="image" title="简短中文名" url="https://..." /> （视频用 type="video"）。不要写 ![](url) / [视频](url) 这类 markdown 内联； 产物 URL 从返回的 images / videos 等数据字段取。
  • IM 类环境（飞书、微信等）：不渲染 artifact 标记，按宿主/渠道自己的附件约定发送媒体， 正文里的说明文字要保留。
  • 拿不准当前环境怎么呈现时，默认走 artifact 标记行。
• 同轮交付：产物必须和「生成完成」写在同一轮回复里，不允许先回一句「完成了」、 等用户追问「图呢」再补发。image/video 的 generate 返回里带 credits（本次实扣积分）， 同轮一并告知「本次实际消耗 X 积分」。
• 失败时：转述 CLI 的 message（已是面向用户的中文），常见原因：积分不足、内容审核未通过、模型维护中——按提示引导用户，不要重试轰炸。