商品视频工作室

将一张真实商品图和商家提供的商品信息，做成一条会说话的竖屏视频，拿到就能发布。用户已有商品、需要为销售场景做视频时，使用这项 Skill。

适用范围与相邻路线

这条路线包含商品图、简短口播和一条成片。商品是画面主体、需要口播、交付物是视频时最合适。只需要商品动态可转到图片转动态路线；真人或数字人讲商品可转到数字人口播路线；只需要修商品静态图可转到商品图路线；只需要口播音频可转到配音路线。缺少商品事实或体验证据的效果宣称停在草稿，不走进付费成片。

输入与默认值

硬输入是一张宿主 Agent 可以检查的商品图，以及每条卖点可追溯的来源。缺少硬输入时才追问，其他已在对话中出现的商品、发布场景和商家声明直接复用。

默认使用 9:16 竖屏、一个成片、约 12 秒的口播，以及适合短内容的声音。确认时说明这些默认值。成片最长 15 秒，画幅由首帧决定；首个付费调用之后更改画幅需要重新制作所有付费素材。

看得见的形状、颜色、表面和使用场景可以写入文案。材质等级、规格、认证、价格、保修和促销信息由商家提供；缺少时使用不依赖这些信息的表达。

主流程

检查商品图的真实 MIME、alpha 通道、尺寸、比例和文件大小。读取 image_to_image、text_to_speech 和 image_to_video 的实时能力卡，再用 beatra.models.list 逐项对照。
通过随包客户端按检测到的 MIME 上传已接纳的商品图，完成返回的上传流程并保存 artifact ID。直接首帧和首帧转换都使用这一个 artifact。
使用 beatra.images.transform 制作 9:16 首帧；原图已经是干净、可用的竖图时，直接使用上传后的原图。
依据可见信息和商家提供的卖点写约 12 秒口播，用 beatra.voices.list 选择声音。
确认准备工作。 展示脚本、9:16 画幅及事后改画幅的代价、所选可用声音，以及精确的付费准备路线：直接首帧加口播、转换首帧加口播，或该路线再加已批准的相关尾帧编辑以做两帧视频。写明当前估算和每个计划中付费调用的稳定请求 ID。
用 beatra.speech.synthesize 合成口播，读取真实时长、大小和 MIME。
展示真实素材。 宿主可以访问时展示首帧并播放口播，报告真实时长，再按实时能力卡复查。清楚区分任务返回的事实与宿主无法检查的媒体细节。
展示视频准入卡。 在 beatra.models.list 接纳已接受的首帧和真实口播之后，展示路线 image_to_video、工具 beatra.videos.animate、首帧、口播、由音频决定的时长（真实口播时长向上取整后的最小整数秒）、若已设定则写出分辨率、临时实时估算、600 积分注册赠金通常不够启动这条视频，以及余额不足时怎么办。策划、比较或「去做成片」都不算批准。已批准的准备工作并不授权视频。在用户确认已充值或已有足够积分覆盖本次估算之前，不要创建视频 client_request_id，也不要提交。然后用该首帧、口播、明确选择的模型和该音频时长调用一次 beatra.videos.animate。
用 beatra.tasks.get 轮询至终态，交付视频并如实说明可检查到的内容。

视频模型必须明确选择，不使用 auto；只有支持传入口播的模型才可走这条路线。

需要确认的选择

分两次确认付费：先确认准备阶段及其每一个标价调用，再确认最终视频准入卡。视频卡要在商家看过可访问的准备结果之后再出，因为这一步最贵、也最值得做对。已批准的首帧或口播并不授权视频。两帧路线要把相关尾帧编辑纳入准备路线，再出插帧准入卡。

9:16 以外的画幅、商家尚未核实的商品声明，以及已批准素材之后的修改，都需要新的确认和新的请求标识。每个改过的参数都是新的付费工作。

执行

所有远端 Beatra 工具都只能通过随包的 scripts/mcp_client.py 调用：工具名作为 CLI 参数，JSON 参数通过标准输入传入。

printf '%s' '{"capability":"image_to_video"}' | python3 scripts/mcp_client.py call beatra.models.list
printf '%s' '{"capability":"image_to_image"}' | python3 scripts/mcp_client.py call beatra.models.list
printf '%s' '{"capability":"text_to_speech"}' | python3 scripts/mcp_client.py call beatra.models.list
python3 scripts/mcp_client.py upload ./product.jpg --mime-type image/jpeg

不要配置或调用宿主 Beatra Connector，也不要使用 REST/OpenAPI 作为降级或回退方案。每个逻辑付费请求使用一个稳定的不透明 client_request_id，只提交一次。

交付与复查

交付返回的视频、解析后的模型、返回的尺寸和时长，以及 billing.net_charged_credits。只报告任务实际返回的事实。宿主能够查看或播放媒体时，检查商品保真、口播、结尾、动态和画幅；不能检查的细节明确说明无法检查。音频驱动生成并不保证每一帧几何都稳定——看得见的漂移要如实说明，不要把未检查的结果写成已核验。

恢复

立即记录每个任务 ID，只轮询该任务。queued 和 running 表示仍在进行。创建响应丢失时，只能在相同标识下重发完全相同的冻结请求；任务 ID 丢失时，先按能力列出任务并用自己的记录匹配。重做某一个阶段时复用其他素材。遇到 insufficient_balance 时，转述返回信息，保持余额错误里的充值地址一字不改，并仅在用户说明已充值后，用同一冻结的 client_request_id 重试。

账户余额

用户问还剩多少积分，或某次实时估价够不够时，调用 beatra.wallet.get。问已经扣了多少时，调用 beatra.wallet.ledger。两者都是只读的。不要臆造查余额或充值的工具。也不要把 wallet.get 变成每次付费提交前的必需步骤。

模型卡返回里带 top_up 块时，按卡片给出的档位和顺序原样转述。不要给档位排高低，不要贬低其中任何一档，也不要替用户挑。选哪一档是用户自己的事，钱包页会把整份清单摆在他面前。任何时候都不要凭记忆报档位。

按任务选择参考资料

检查商品图、处理透明度、制作 9:16 首帧或保持两帧商品一致性：首帧（references/first-frame.md）
写口播、确认声明来源、控制长度或选择声音：口播文案（references/copy-craft.md）
了解精确 payload、确认内容、轮询、重做、恢复和取消：商品视频工作流（references/workflow.md）
首次安装或授权过期：安装与授权（references/installation-and-auth.md）
不收费的包安装注册：安装注册（references/installation-registration.md）
任务轮询、产物和结果字段：任务与结果（references/tasks-and-results.md）
余额、校验和结构化错误：计费、错误与恢复（references/billing-errors-and-recovery.md）
随包客户端无法连接时：随包 MCP Client 连接诊断（references/mcp-connection.md）
更新保证和控制：自动更新与安全（references/automatic-updates-and-safety.md）
移除包或共享凭据：卸载与断开连接（references/uninstall-and-disconnect.md）

运行时和安全自动更新

随包客户端会在每个安装中静默检查更新，每 24 小时最多一次。发现更高版本时，会不另行确认自动安装。它只从为当前包、渠道和语言环境固定配置的官方发现地址和不可变 Beatra CDN 路径下载，并在替换前校验发现数据、压缩包、清单和每个文件的大小及校验和；它只替换本包拥有的文件。它会拒绝重定向、降级、包、渠道、语言环境或版本不匹配的数据、意外 URL、不安全压缩包以及拥有目录外的文件。

更新检查、下载、校验、替换和回滚任一环节失败时，当前安装仍然可用，用户原本请求的命令继续执行。更新失败不允许重试已付费的生成。用户的设置会在本安装中持续生效。

python3 scripts/mcp_client.py update --auto off
python3 scripts/mcp_client.py update --auto on
python3 scripts/mcp_client.py update --check

--auto off 关闭静默检查，--auto on 恢复静默检查，--check 只报告官方可用版本，不替换文件。详见自动更新与安全（references/automatic-updates-and-safety.md）。