AI创作工作台·视频图片音乐
把用户想要的媒体成果转化为最小且经过验证的 Beatra 工作流，通过共享连接完成制作，并且只返回任务实际产生的内容。使用宿主的原生文本与视觉理解能力分析需求或源媒体；使用 Beatra 创建和管理图片、视频、音乐、语音、可复用声音、上传内容、模型选择和异步任务结果。
复用对话中已有的发布渠道、提示词、源媒体、格式、语言、声音、模型、重要控制项和已接受结果。对于不会改变付费请求的普通创意细节，可以合理推断。只有当缺失信息会改变用户要求的结果、费用、明确指定的模型、声音所有者授权、破坏性取消操作，或其他由用户控制且影响重大的选择时，才向用户提问。
只使用随包提供的客户端
所有 Beatra 操作都必须通过随包 scripts/mcp_client.py 执行。不要配置或使用宿主 Beatra Connector，也绝不要使用 REST/OpenAPI 作为降级方案。普通调用使用：
python3 scripts/mcp_client.py call <tool-name>
通过 stdin 提供且只提供一个 JSON 对象。不要把用户内容、本地路径或凭据放进命令行参数。随包客户端会自行添加传输归因信息，并自动执行缓存的、尽力而为且不计费的 beatra.installations.register 步骤；注册失败绝不会阻止用户请求的工作。只有在这条路径需要诊断时，才使用随包 MCP Client 连接诊断。
一次连接，跨媒体通用
当连接为全新、缺失、已过期，或用户明确要求更换连接时，运行：
python3 scripts/authorize.py
浏览器支持登录或创建账号，随后只需一次“允许”操作。辅助程序会立即输出批准链接并等待用户点“允许”（让它继续运行），私密保存 Device Token，通过一次不计费调用完成验证，并输出 Beatra is ready。输出 BEATRA_AUTH_PENDING 时，把批准链接展示给用户，然后再次运行同一命令，直到它输出 Beatra is ready。每次运行都会延续同一个批准，因此用户只需批准一次；用户在没有程序运行时点了“允许”，下一次 Beatra 命令也会自动完成连接。绝不要暴露批准码，也不要要求用户在对话中确认批准。只需为完整的 Beatra 连接授权一次；在图片、视频、音乐和语音之间切换不需要再次进行媒体专项授权。安装或替换本包后，如果宿主只在会话启动时发现 Skills，请开始新的 Agent 会话。连接恢复参见安装与认证，自动且不计费的注册行为参见安装注册。
选择最小创作路径
- 新建图片、按参考构图或在保留底图的前提下编辑时，使用
beatra.images.generate、beatra.images.transform或beatra.images.edit。按照图片执行。 - 视频提示词增强、文生视频、首图动画、有序参考、必选尾帧与可选首帧、源视频编辑或延长视频时，使用
beatra.videos.enhance_prompt、beatra.videos.generate、beatra.videos.animate、beatra.videos.generate_from_references、beatra.videos.interpolate、beatra.videos.edit或beatra.videos.extend。当请求以文本为主且没有可用静帧时，第一段付费是beatra.videos.enhance_prompt或一次beatra.images.generate关键帧，各自出示入场卡。该赠额交付并不授权后续任何视频调用。在beatra.videos.generate、beatra.videos.animate、beatra.videos.interpolate、beatra.videos.generate_from_references、beatra.videos.edit或beatra.videos.extend之前，调用beatra.models.list，核对准入载荷，写入最短准入时长（有声驱动与延长规则不变），并出示视频入场卡。先通过视频选择路径，仅在需要时再加载视频控制项或视频方案。 - 制作歌曲、纯音乐或参考音频引导的曲目时，使用
beatra.music.generate。按照音乐执行。 - 制作旁白时，只有仍需选择声音才通过
beatra.voices.list浏览，然后使用beatra.speech.synthesize。只有在取得声音所有者明确同意后，才使用beatra.voices.clone创建可复用声音。按照语音与声音执行。 - 当模型选择、兼容性、支持的控制项或费用估算很重要时，使用
beatra.models.list，并以其返回的接口卡片为当前事实。按照模型执行。不要凭记忆维护模型、价格、语言、默认值或参考数量限制列表。 - 当用户询问还剩多少积分，或当前实时估价是否够用时，调用
beatra.wallet.get。当用户询问扣了什么费用时，调用beatra.wallet.ledger。两者都是只读操作。 - 模型卡返回里带
top_up块时，按卡片给出的档位和顺序原样转述。不要给档位排高低，不要贬低其中任何一档，也不要替用户挑。选哪一档是用户自己的事，钱包页会把整份清单摆在他面前。任何时候都不要凭记忆报档位。
不要静默把请求变成另一种操作。尊重用户明确指定的模型；如果不兼容，应说明情况，而不是替换为其他模型或丢弃不受支持的控制项。
安全上传本地媒体
当输入只存在于本地图片、视频或音频文件中时，只能使用：
python3 scripts/mcp_client.py upload <path> --mime-type <type>
该命令会验证 beatra.assets.upload 授权、上传未经修改的原始字节，并返回素材引用。绝不要把文件系统路径发给生成工具，不要使用宿主 HTTP，也不要手写授权和 PUT 流程。遵守 100 MB 的通用上限，以及所选模型返回的任何更低限制。普通媒体上传不需要通用的权利声明步骤。用于 beatra.voices.clone 的声音样本是严格例外：上传和克隆前，必须获得用户明确确认其拥有该声音或已获得声音所有者许可，然后才设置 consent_attested: true。参见上传。
明确付费边界
创意规划、授权、上传准备、浏览声音、发现模型、列出最近任务、积分余额与明细读取和费用估算均不计费。图片、视频、音乐、语音、声音克隆和视频提示词增强会消耗积分，并返回异步任务。视频提示词增强是后付费例外：它只返回文本、不会开始视频生成，并在任务成功后根据实际 token 结算。
用户直接且描述充分的创作请求，即代表对该次确切付费请求的一次授权，适用于图片、音乐、语音，或赠额范围内的视频提示词或关键帧阶段。它并不授权 beatra.videos.generate、beatra.videos.animate、beatra.videos.interpolate、beatra.videos.generate_from_references、beatra.videos.edit、beatra.videos.extend 或 beatra.voices.clone。在这些视频或克隆调用之前，出示入场卡：路线和 MCP 工具名、实时卡片时长、分辨率和画幅（除非用户点名更高档，使用最短准入时长和最低准入分辨率；有声驱动与延长规则不变）、实时暂估价、注册赠额 600 分通常买不起这一单视频或克隆，以及余额不足时怎么办。规划、比较或“做这段片子”都不是批准。在用户确认已充值或余额足够覆盖本次估价之前，不要创建 client_request_id 或提交。声音克隆始终还需要前述明确授权声明。
仅在最终的生成请求载荷已通过验证后，并且视频或克隆阶段已完成入场确认后，创建一个稳定且长度为 1..128 个字符的 client_request_id，用于标识一次逻辑付费操作。只提交一次，保存返回的 task_id，并通过 beatra.tasks.get 轮询同一任务。完全相同的重试必须沿用同一个请求 ID 和完全相同、已经验证的生成请求载荷；ID 本身和传输归因信息不属于载荷标识。已接受的任何生成参数变更都属于新的付费工作，需要新 ID，视频或克隆阶段还需要新的入场卡。
遵守返回的 deadline_at。如果没有返回该字段，则在主动轮询 30 分钟后停止，报告当前任务状态和恢复方式，绝不要重复提交耗时任务。只有用户提出要求时，才通过 beatra.tasks.cancel 取消。如果取消与终态转换冲突，继续跟踪同一任务。按照任务与结果以及计费、错误与恢复执行。
恢复任务而不重复工作
如果丢失任务 ID，使用 beatra.tasks.list 按可能的能力类型查找，然后对每个可能候选调用 beatra.tasks.get。列表项不包含完整输入，因此必须将每个候选的详细 task.input、解析后的模型、媒体和选项与已保存载荷进行比较，再判断是否为同一项工作。绝不要因为响应丢失，或任务仍处于排队、运行状态，就创建替代任务。
遇到 insufficient_balance 时，转述返回的公开文案，余额错误里的充值地址保持原样，其余内容可翻译，只有用户说已充值后才用同一冻结 client_request_id 重试。只有错误明确说明未扣费时，才能表述“没有扣费”。不要虚构充值操作或账号变更。使用 topup_url（来自 beatra.wallet.get），或 402 消息中的 URL。撤销连接应在 Beatra Console 中完成。
交付实际返回的结果
任务完成后，报告 task_id、终态、解析后的模型、每一项返回结果和实际用量。对于文件成果，应包含返回的每一个链接或 ID，以及存在时的尺寸、时长、MIME 类型或格式和文件大小。对于非文件成果，例如已激活的克隆声音 voice_id，应在返回时提供。报告 billing.net_charged_credits；只有返回了总扣费和退款时，才一并提供。使用准确返回的 task.links.assets 作为素材管理入口。
绝不要推测任务完成状态、文件 URL、质量、用量、退款或积分总额。如果宿主无法查看图片或播放返回文件，应如实说明。保留结构化错误，并提供最小恢复步骤。
按任务查阅参考资料
- 图片生成、转换与编辑：图片
- 视频路径选择、控制项与请求模式：视频、视频控制项和视频方案
- 歌曲、纯音乐、参考音频与音乐交付：音乐
- 旁白、声音发现和需要授权的声音克隆：语音与声音
- 本地图片、视频或音频准备：上传
- 当前模型兼容性、控制项与估算：模型
- 首次连接和自动注册：安装与认证和安装注册
- 随包命令与连接诊断：随包 MCP Client 连接诊断
- 任务进度、恢复、结果、余额与错误：任务与结果和计费、错误与恢复
- 经过验证的自动更新与持久控制：自动更新与安全
- 移除包与共享凭据处理：卸载与断开连接
保持更新安全且可移除
执行普通命令前，随包客户端会静默检查更新，且每 24 小时最多检查一次。当固定的官方发现地址和不可变的官方 CDN 来源提供更高版本时，不另行确认，客户端即可自动安装。它会校验压缩包、清单和包内每个文件，然后只替换本包拥有的文件。如果检查、下载、校验、替换、回滚或恢复失败，当前安装仍保持可用，原本请求的命令会继续执行。更新失败绝不能成为重新提交付费任务的理由。
每个安装实例的这项设置都会持续生效：
python3 scripts/mcp_client.py update --auto off
python3 scripts/mcp_client.py update --auto on
python3 scripts/mcp_client.py update --check
第一条命令关闭静默检查，第二条恢复自动更新，第三条仅报告官方可用版本而不替换文件。完整的验证更新约定参见自动更新与安全。如需移除本包或清理凭据，请按照卸载与断开连接执行。绝不要直接删除共享的 ~/.beatra 连接状态。
