文字转语音与视频配音
把文字变成能直接用的配音：先按用户需要的时长写好带标记的配音稿，并给出三个音色方向，再用选定的声音来读，用于视频、广告、播客、有声书，或让一套角色各用各的声音。
你会拿到什么
第一条回复写成文字，此时还没有连接任何服务：
- 一张配音稿表：每一句编号；要念的文字标出短停顿（
/）、长停顿（//）、加粗的重读词，以及难词的读音；写上这一句的字数或词数，以及估计秒数；最后一行给出总字数或总词数、总时长，以及所用的朗读速率。 - 三个音色方向，彼此在年龄、质感或情绪上分开：性别和年龄、质感、语速、写成声音能照着做的情绪，以及它适合的场合。
- 按用途多给一样：播客的开场、正文各段、结尾和读音表；有两个或更多人说话时给角色声线表；用户要用自己的声音时给录音指引。
连上 Beatra 之后，每一项都根据定稿的配音稿来做：
- 选定音色的配音：每一条一个文件；实时配音模型卡片要求把文字分段时，按顺序交付各段；用户要给视频配字幕时，旁边附一个字幕文件。
- 单人播客一集，用一个主持人的声音；需要时，片头音乐和片尾音乐作为单独的文件。
- 有声书或长课程，用一个声音：先交一小段试听，再一章一章做。
- 多角色录音：每一句一个编号片段，标明说话人，按剧本顺序，可以直接放进音频或视频剪辑软件里组装。
- 用户本人声音的可复用克隆，然后用它来读上面任何一种。
生成文件的类型、大小和时长由模型决定，交付时如实说明。
几种做法
- 配音稿。 默认的第一条回复：标好标记、对齐时长的配音稿，和三个音色方向。
- 配音。 一个声音读一条：广告、宣传片、产品介绍、短视频旁白、讲解、问候、粤语，或用户提供的译文。
- 单人播客。 一个主持人读这一集；片头音乐和片尾音乐可选，各自单独一张确认卡。
- 有声书和长篇朗读。 一个声音读一本书或一门长课程，先交试听段，再一章一章做。
- 多角色。 对白、广播剧、双主持人播客和双角色广告：每个说话人一个声音，旁白另有自己的声音。
- 你自己的声音。 用一段干净的样本克隆一次，然后用在上面任何一条路线里。
适用范围和相邻做法
有人想把文字读出来时用它：他们写好的稿子、一个可以写成稿子的主题、一篇要做成播客的文章、一段书，或一段对白。它做的是声音，交付的音频文件可以直接放进视频剪辑、播客托管或课程页面。成片视频、出镜讲解、对口型、剪辑或清理已有录音、转写、翻译，以及把片段和音乐混成一集成片，属于视频、出镜或剪辑流程。音色用音色库里的、用户本人的，或已得到说话人许可的；拿到一个文件、一段公开录音或公众人物的视频，都不算同意。要求听起来像某一位指名的真实人物时，改写成年龄、质感、语速和情绪；真实人物的声音，只有从他们自己的样本克隆、并且得到他们的许可，才能使用。
输入和默认值
硬性输入是要配音的文字，或一个可以凭常识来写的主题。给了其中一样，就一次写完整个第一条回复，什么都不问。这段配音讲的是用户自己的公司、产品或个人，却没有给出相关事实时，用一句话请对方补上，同时照样交一份完整配音稿，第一行标「示例」，用一个明显虚构的名字，比如「示例公司」。文字和主题都没给时，用一句话问这段配音是做什么用的，并交一份完整的「示例」：一家社区咖啡馆的一分钟品牌旁白。在这两种情况下，这句只有一句话的提问就是这条回复唯一的下一步，用来代替第 1 步结尾的那个下一步。用户只问怎么录一段声音样本时，直接回答，不附示例稿。
用户给过的时长、用途、语气、音色、语言和用词都沿用。默认值：用用户的语言，MP3，每一条一个声音；有角色阵容时每个说话人一个声音，另加一个旁白；语速按体裁来：
- 中文：讲解、广告、短视频、播客和问候，每分钟 220–260 字（一分钟是 230–250 字）；故事、有声书和戏剧，每分钟 180–220 字。
- 英文：讲解、广告、短视频、播客和问候，大约每分钟 140–160 个词；故事、有声书和戏剧，每分钟 120–150 个词。
交付之前先数一遍配音稿：偏短就加句子，偏长就删句子。绝不要交出一份偏短的草稿再问要不要加长。没有给时长时，按内容来写，并写明估计的时长范围。用户提供的稿子逐句保留：只加停顿、重读和读音标记，只有用户说可以改，才改句子。必须照读的品牌名、人名和数字，保持用户写的原样。从主题写出来的稿子只用常识和通行做法：不要编造研究、数据、奖项、客户名称或个人经历。
主流程
- 写配音稿。 第一条回复不调用任何工具（不开链接、不查资料、不看日期），不要求登录，也不报价格，并且不把这些写作规则复述出来。为耳朵来写：一口气一句，中文大约不超过 25 个字，英文大约不超过 15 个词；广告和短视频里，最重要的一句落在前 3 秒。短停顿标
/，长停顿标//，重读词加粗；每个多音词、每个生僻字和每个专名都标上带声调的拼音，标在整个词上，绝不只标其中一个字；数字、日期、单位和外来词写成念出来的样子。这条流程自己写的广告稿里，用户给过的产品数字保留他们给的依据，否则就不写这个数字。然后给出三个音色方向（此时都不点名具体音色）和这一用途多出来的那一样。播客的材料是一篇没有贴进来的文章时，只给结构，用「文章的第一个观点写在这里」这样的占位，什么都不编。有角色阵容时，列出每个角色的年龄、性情，以及音色彼此隔多远，并且每一句前面写上说话人。用自己的声音时，给出录音指引（安静的房间、只有一个人说话、没有音乐、正常语速、一段真正会用的文字，大约 10 秒到 5 分钟，最大 20 MB；以实时克隆模型卡片上的限制为准），说明克隆本身是单独的付费步骤，价格写在它的确认卡上，并给一条关于朗读状态的提示，不再给三个音色方向。结尾用用户的语言只给一个下一步：回复一个音色方向的编号，比如「1」，就去选定具体音色，先报价，对方同意后再做音频；用自己的声音时：把录好的样本发来，先看克隆的价格。 - 定稿。 要拿去配音的文字必须是定稿。如果还是「示例」，先问是用示例，还是换成自己的文字。用户改了用途、产品或主题，先把改好的配音稿给他看。
- 定音色。 调用
beatra.voices.list，只带选定的音色方向能定下来的筛选条件（gender、age_group、language、query），只保留ready的音色，并选最接近的一个。返回了preview_url时把它给用户；听它不花钱，也不做付费试音。固定不透明的voice_id及其compatible_models；绝不要把显示名称写进voice，使用之前要重新查询记住的voice_id。 - 克隆用户的声音（只有对方要求时才做）。上传任何文件之前，先确认这是本人的声音，或已得到说话人的许可；拿到一个文件、一段公开录音或公众人物的视频，都不算同意。然后用
python3 scripts/mcp_client.py upload "<file>" --mime-type <type>上传干净的样本，调用beatra.models.list并传{"capability": "voice_clone"}，把样本和这张实时克隆模型卡片对照，并出示克隆确认卡，带上配音制作流程（references/workflow.md）里余额不足时的那条说明；然后等用户说已经充值，或说余额本来就够。只提交一次beatra.voices.clone，并带上consent_attested: true，用beatra.tasks.get查进度，然后固定返回的voice_id。一份样本只克隆一次；用这个新声音读稿，要另出一张确认卡。 - 配音。 调用
beatra.models.list并传{"capability": "text_to_speech"}，保留一张实时配音模型卡片：固定的音色在compatible_models里列出了它，并且它支持这种语言。把标好的配音稿转成要发送的文字：/变成逗号，//变成句号，并去掉加粗。这张卡片带有script_markup时，每个标出的读音写成{pron <word> <reading>}（带声调数字的拼音），两句之间较长的停顿可以写成{pause <seconds>}；否则把容易读错的词改写成不会读错的写法，并且先把这个改动给用户看。只有这张卡片列出了对应的取值时，才把音色方向里的语速写进speed、情绪写进emotion；两者作用于整次调用，所以需要另一种情绪的一句要单独成块。用户要给视频配字幕、并且这张卡片列出了这个控制项时，设置subtitle_enable: true。这张卡片的文字上限要求分段时，在段落结束处切开。用即将提交的那些确切字段，通过beatra.speech.validate（不扣费）给每一块报价，为这一条出一张确认卡，列出它的各个块，然后每一块用这张确认卡上写明的确切模型提交一次beatra.speech.synthesize，并逐个查进度。 - 单人播客。 用固定的主持人音色，按第 5 步来读开场、正文和结尾。片头或片尾音乐在配音之后，各自单独一张确认卡：调用
beatra.models.list并传{"capability": "text_to_music"}，读取suno-6这张卡片，然后提交一次beatra.music.generate，带上model: "suno-6"、instrumental: true、一个标题，以及写明预期长度的提示词。没有时长字段；报告真实长度，以及结果返回的每一条片段。音乐是单独的文件，绝不混进配音里。 - 有声书和长篇朗读。 先用大约一分钟的试听段（开头，加上最难读的名字）单独出一张确认卡。用户听过并同意之后，每一章单独一张确认卡，交付一个文件；实时配音模型卡片要求把文字分段时，按顺序交付各段。出第一章的确认卡之前，说清有多少章，因此后面有多少张确认卡；每一章单独同意。
- 多角色。 定稿角色声线表，每个角色一个
voice_id，旁白也包括在内，选择彼此容易分辨的音色。出确认卡之前说明：结果是按剧本顺序编号的片段，不是一个混好的文件。把配音稿切成语音块，每一块是同一个说话人连续的一轮；舞台指示绝不念出来。用beatra.speech.validate给这些块报价，每一场出一张确认卡，列出每一块的编号、说话人、音色和价格，然后每一块提交一次beatra.speech.synthesize，并查进度。出第一场的确认卡之前，说清有多少场，因此后面有多少张确认卡；每一场单独同意。改过的一句单独成块，单独一张确认卡。 - 交付。 按剧本顺序报告真实的文件、时长、大小、格式、字幕文件（如果有）和
billing.net_charged_credits。你听不见这段音频：直接说明发音、节奏，以及克隆声音像不像，都要用户自己听了才能核对。提醒用户公开发布音频时标注「AI 生成」。结尾只给一个这条流程能做的下一步，比如「回复『换成 2』，听另一个音色方向；我先报价」。
请求体、标稿怎么转换成要发送的文字，以及一个完整的配音示例，见配音制作流程（references/workflow.md）。
连接就绪之前
如果一轮结束时「允许」还没完成，就先把所有不需要连接的内容按用户要的格式交付：标好的配音稿和它的时长表、三个音色方向、播客结构或角色声线表，以及录音指引。这一轮交付的就是这些文字。用一句话说明：付费步骤在用户点完「允许」后的下一条消息里继续；「允许」只是完成连接，每个付费步骤在下一条消息里仍要等它当时的确认卡。不要用别的工具或服务填补空档，也不要说出任何没有经过实时调用返回的音色、模型、价格或结果。
需要确认的决定
配音稿、音色方向、角色声线表和录音指引都免费。它们不等于同意付费。
每次付费调用之前，先出一张当时的制作确认卡，然后等待：
- 内容：要做什么，用用户自己的话说，写上选定音色的名称和 ID，并写明由哪一类调用来做（克隆、配音或音乐）。
- 积分：刚从
beatra.speech.validate或模型卡片读到的实时价格。绝不用记忆里的数字。 - 次数：每一块一次付费调用。只有同一条、同一章或同一场的各个块可以共用一张确认卡，每一块单独一行；每一次克隆和每一次音乐调用都各自单独一张确认卡。
- 标识：每次调用一个新的不透明
client_request_id。文字、音色、模型或控制项一变，就换一个新的标识。 - 如果到此为止：配音稿和音色方向仍然能用。
- 如果余额不足：原样转述官方提示和其中的充值链接。在用户说已经充值之前，不要再次提交。
克隆、配音和音乐各自单独出确认卡。同意了试听段，并不覆盖各章；同意了一章，并不覆盖下一章；同意了克隆，并不覆盖用这个声音来读。绝不悄悄更换音色或模型。所有远程 Beatra 工具都只通过随包的 scripts/mcp_client.py 调用：工具名作为命令参数，JSON 参数从标准输入传入。
不要配置、调用或使用宿主 Beatra Connector。
不要用 REST/OpenAPI 作为降级方案。
如果创建调用的响应或任务编号丢了，先调用 beatra.tasks.list，再调用 beatra.tasks.get，与定稿的请求逐项比对。只有确认不存在这个任务时，才用同一个 client_request_id 再次提交完全相同的内容。失败的一块在新的确认卡上重做，并换一个新的 client_request_id；再发送旧的标识，只会取回那个失败的任务。只有用户要求取消时，才调用 beatra.tasks.cancel，再用 beatra.tasks.get 确认这个任务。
用户问还剩多少积分时，调用 beatra.wallet.get。问扣了哪些费用时，调用 beatra.wallet.ledger。模型卡片返回 top_up 内容时，按卡片列出的顺序原样转述各档充值，不排序，也不替用户选。
按任务查阅
- 需要标稿转换、音色、克隆、配音、多角色和音乐的请求示例，以及一个完整的配音示例时，读配音制作流程（references/workflow.md）。
- 任务卡住、没收到回应、某个词读错了、价格看起来不对，或用户想要一个混好的文件时，读出问题时怎么办（references/faq.md）。
- 连接还没就绪时，读安装与授权（references/installation-and-auth.md）。
- 首次使用登记，读安装登记（references/installation-registration.md）。
- 任务创建之前调用就失败时，读随包 MCP Client 连接诊断（references/mcp-connection.md）。
- 任务在排队、进行中或找不到时，读任务与结果（references/tasks-and-results.md）。
- 扣费、退款或没收到回应需要通用规则时，读计费、错误与恢复（references/billing-errors-and-recovery.md）。
- 用户想停止使用并断开连接时，读卸载与断开连接（references/uninstall-and-disconnect.md）。
更新与安全
本 Skill 会自动更新。内置客户端每天最多一次从 Beatra 官网读取本渠道的版本信息
（中国大陆网络走 www.beatra.cn 与 cdn.beatra.cn）。有新版本时，它下载官方发布包，
逐个文件校验 SHA-256，再替换本 Skill 自己的文件；你放进这个目录的其他文件不会被
改动。替换过程中断时，下次运行会自动恢复到替换前的状态。除此之外，它不下载或执行
任何其他代码，只通过 HTTPS 与 Beatra 官方服务通信；你选择上传的文件只会传到
Beatra 为这次上传签发的一次性地址。
关闭自动更新：python3 scripts/mcp_client.py update --auto off。关闭后，客户端每天
最多提示一次在你安装它的商店里更新的命令。详见更新与安全（references/updates-and-security.md）。
