VoiceMaster

目标

为短视频文案生成可直接交付的 AI 配音结果。优先输出单个 mp3 文件；无法本地合并时，返回分段下载卡片并明确片段顺序。使用 SenseAudio 官方接口文档：

• - INLINECODE1
• INLINECODE2
• INLINECODE3

先检查环境变量 SENSEAUDIO_API_KEY。如果已经存在，直接使用；如果不存在，再提示用户提供 API Key 或先在终端设置环境变量。不要把密钥写进 SKILL.md、脚本源码或提交记录。

内置音色映射

始终优先使用用户显式指定的 voice_id。未指定时，根据文案语气、角色设定和平台风格，从下表选择最贴近的音色，并在同一项目内保持角色映射稳定。

在当前 SenseAudio key 权限有限时，仅默认使用已确认可用的以下音色：

• - child_0001_b：可爱萌娃，平稳
• INLINECODE8：儒雅道长，平稳
• INLINECODE9：沙哑青年，深情

不要默认选择未确认授权的 VIP / SVIP 音色。若接口返回 403 no access to the specified voice，优先回退到 child_0001_b，而不是重复尝试未授权音色。

CODEBLOCK0

多角色文案处理规则：

1. 1. 识别 角色名:、旁白:、主持人: 等显式说话人标记。
2. 为每个角色建立一次性 role -> voice_id 映射，后续所有分段复用同一映射。
3. 若当前 key 可使用的音色有限，允许多个角色共用同一音色，优先保证生成成功，不强行制造音色差异。
4. SenseAudio 单次请求只能使用一个 voice_id，所以多角色脚本不能整段一次性提交。
5. 多角色脚本必须先按角色台词切分为多个子片段，每个子片段只允许一个说话人。
6. 每个角色子片段分别调用一次 TTS，生成多个小段音频后再按原始顺序拼接。
7. 如果没有按角色逐段请求，而是把混合台词整段提交，那么最终听感会接近“全员同一音色”，这不算多角色配音成功。

输入整理

在执行前整理以下信息：

1. 1. 文案全文。
2. 目标风格，例如温柔、新闻感、励志、悬疑、剧情口播、带货。
3. 角色数量与角色关系。
4. 语速 speed。未指定时按风格估算，但必须限制在 0.5 到 2.0。
5. 音高 pitch。未指定时使用 0。
6. 输出文件名和输出文件路径。未指定时使用 voicemaster-output.mp3。

默认参数：

CODEBLOCK1

对话草稿流程

如果用户给的是完整、可直接配音的剧本，按现有流程直接整理角色、分段和音色即可。

如果用户提供的是以下任一输入形态，不要直接开始 TTS，先生成一版可编辑的对话草稿：

1. 1. 只有主题、场景、人物关系或情绪方向。
2. 只有零散设定，没有明确的角色台词格式。
3. 用户明确表示“你先帮我写一版”“先出个对话”“先整理成剧本”。
4. 输入里角色边界、说话人、段落结构不清楚，无法直接安全切分成 TTS 片段。

执行顺序：

1. 1. 先根据用户主题生成一版短视频可用的对话草稿，默认补齐角色名、台词顺序、必要旁白和基础节奏。
2. 输出草稿后，明确询问用户是否需要修改；不要在用户确认前直接生成音频。
3. 如果用户提出修改意见，就继续按意见改草稿，并再次等待确认。
4. 只有当用户明确表示“不需要修改”“就这样”“开始生成”“生成吧”等确认含义时，才进入配音阶段。
5. 进入配音阶段后，把最终确认版草稿视为正式剧本，再执行角色映射、分段、TTS 和拼接。

草稿要求：

1. 1. 优先写成清晰的逐行对话格式，例如 旁白：...、角色A：...、角色B：...。
2. 单轮草稿先求结构清楚、节奏自然、便于后续分段，不追求一次写到最长。
3. 如果用户没有指定时长，默认按短视频口播场景控制在精简可配音的长度。
4. 如果用户没有指定角色数量，默认生成 2 到 3 个角色或“旁白 + 角色”结构，并在草稿里写清楚。
5. 草稿阶段可以顺带给出一句简短说明，例如“确认后我再开始生成配音”。

短视频对话草稿模板

以下模板用于“先写草稿、再确认、后配音”的阶段。优先根据用户主题、平台风格和情绪目标，从中选择最贴近的一套，再按用户需求改写。

模板 1：旁白 + 人物冲突

适用场景：

1. 1. 情绪故事。
2. 反转剧情。
3. 成长、遗憾、和解类短视频。

推荐结构：

1. 1. 开场一句钩子。
2. 角色 A 抛出矛盾。
3. 角色 B 回应并升级情绪。
4. 旁白收束或反转。

草稿骨架：

CODEBLOCK2

模板 2：双人轻松聊天

适用场景：

1. 1. 日常段子。
2. 朋友互怼。
3. 轻松种草。
4. 情侣、小剧场。

推荐结构：

1. 1. 用一句生活化问题开场。
2. 两人来回两到三轮。
3. 结尾留包袱或结论。

草稿骨架：

CODEBLOCK3

模板 3：带货口播对话

适用场景：

1. 1. 商品种草。
2. 直播切片。
3. 促销转化。
4. 用户痛点引导。

推荐结构：

1. 1. 先抛用户痛点。
2. 角色提出质疑。
3. 另一角色给出解决方案。
4. 用结果感和行动指令收尾。

草稿骨架：

CODEBLOCK4

模板 4：知识解说对话

适用场景：

1. 1. 冷知识。
2. 科普。
3. 职场技巧。
4. 学习方法。

推荐结构：

1. 1. 用一个误区或问题开头。
2. 提问角色代表普通用户。
3. 解说角色给出拆解。
4. 结尾给出一句可执行建议。

草稿骨架：

CODEBLOCK5

模板 5：悬念反转

适用场景：

1. 1. 剧情号。
2. 反转短剧。
3. 都市情绪。
4. 高停留口播。

推荐结构：

1. 1. 开头直接抛异常信息。
2. 两个角色围绕真相推进。
3. 中段制造误导。
4. 结尾用一句话反转。

草稿骨架：

CODEBLOCK6

模板 6：旁白 + 单角色自述

适用场景：

1. 1. 情感独白。
2. 成长感悟。
3. 女性向/男性向口播。
4. 治愈系表达。

推荐结构：

1. 1. 旁白给情绪背景。
2. 主角色连续两到三段自述。
3. 结尾落到态度变化或金句。

草稿骨架：

CODEBLOCK7

模板使用规则

1. 1. 先选结构最接近用户目标的一套，再替换人物、场景、行业词和情绪词。
2. 如果用户只给一个主题，先用模板快速产出草稿，再问用户是否要往“更搞笑”“更催泪”“更带货”“更强反转”等方向修改。
3. 如果用户要求更短，优先删减旁白和重复解释，不先删核心冲突句。
4. 如果用户要求更像短视频爆款，优先强化第一句钩子和最后一句落点。
5. 草稿模板只是起点，不要机械照抄；生成时必须结合用户主题做定制化改写。

建议语速：

• - 温柔叙事、治愈、情感类：0.88 到 INLINECODE27
• 新闻播报、知识解说：0.98 到 INLINECODE29
• 励志混剪、节奏短视频：1.05 到 INLINECODE31
• 直播带货、促销叫卖：1.12 到 INLINECODE33

若可用音色受限，默认采取以下补偿策略：

• - 资讯、纪录片、旁白：优先 male_0004_a，语速 0.92 到 INLINECODE36
• 情绪故事、深情文案、悬疑口播：优先 male_0018_a，语速 0.88 到 INLINECODE39
• 带货、轻松内容、儿童感场景：优先 child_0001_b，语速 0.96 到 INLINECODE42
• 通用兜底：INLINECODE43
• 不对用户隐瞒音色降级：在结果里明确说明“当前 key 仅可使用已授权音色”

分段策略

当文本超过 500 字时，必须自动进行逻辑分段请求，避免超时。

执行规则：

1. 1. 按段落、场景切换、说话人切换、完整句号优先切分。
2. 将每段控制在 180 到 450 字之间，避免把一句话拆开。
3. 为每段保留原始顺序编号，从 01 开始。
4. 多角色场景中，不要把同一轮对话拆到不同片段。
5. 全部片段生成完成后，优先使用 helper.py concat 合并为一个 mp3。
6. 如果一个片段内部仍然包含多个角色行，继续细分到“单片段单角色”再调用 TTS。

API 请求模板

API 地址固定为：

CODEBLOCK8

优先使用 jq 构造 JSON，避免转义错误。默认走非流式模式，便于直接拿到 hex 音频并落盘。

重要：先按最小请求体调用官方接口，不要一开始就附带全部可选字段。若接口返回 400 input content type is not supported，优先怀疑请求体结构与官方当前协议不一致，而不是继续切换音色。

请求模板：

CODEBLOCK9

最小请求体跑通后，再逐步增加以下可选字段，每次只增加一类：

1. 1. INLINECODE53
2. INLINECODE54
3. INLINECODE55
4. INLINECODE56
5. INLINECODE57
6. INLINECODE58

多片段请求时，额外在本地维护上下文元数据即可，不要求额外提交给官方接口。保持每段 model、voice_setting、audio_setting 一致。

SenseAudio 响应处理

SenseAudio 非流式 TTS 的成功响应为 JSON，其中 data.audio 是 hex 编码的音频数据。处理规则如下：

1. 1. 先检查 base_resp.status_code 是否为 0。
2. 若成功，读取 data.audio 并按十六进制解码为二进制音频文件。
3. 使用 extra_info.audio_length、extra_info.audio_sample_rate 作为结果回执。
4. 若 data.audio 为空或 status_code 非 0，直接返回 base_resp.status_msg。

响应结构参考：

CODEBLOCK10

返回结果处理

1. 1. 调用 helper.py synthesize 发送请求并把 hex 音频保存到本地。
2. 长文案分段时，将每段保存为 segment-01.mp3、segment-02.mp3。
3. 多角色场景中，进一步保存为更细粒度的角色片段，例如 segment-01-narrator.mp3、segment-02-youngman.mp3。
4. 全部片段完成后，调用 helper.py concat 生成最终文件。
5. 如果 ffmpeg 不可用，则保留分段文件并把路径按顺序返回给用户。
6. 如果返回里没有 data.audio，把完整原始 JSON 一并带回，便于后续比对协议变更。

示例：

CODEBLOCK11

CODEBLOCK12

helper.py 用法

仅在以下情况调用本地脚本：

• - 需要把 SenseAudio 的 hex 音频响应落盘。
• 长文案需要本地合并多个片段。
• 需要统一输出文件名和目录结构。

命令概要：

CODEBLOCK13

输出要求

完成配音后，始终给出：

1. 1. 使用的 voice_id，以及为何匹配该风格。
2. 实际 speed 与 pitch。
3. 最终音频文件路径。
4. 如果做了分段，说明分段数量与是否已成功合并。
5. 若请求失败，返回 SenseAudio 的 status_code 与 status_msg。
6. 如果因为套餐权限限制降级到授权音色，明确写出降级原因与最终使用的 voice_id。

背景音乐建议

配音完成后，必须根据文案情感推荐 2 到 3 种背景音乐方向，避免只给宽泛标签。按以下映射优先推荐：

• - 悲伤、遗憾、追忆：钢琴氛围、弦乐极简、低速 lo-fi
• 励志、成长、逆袭：电影感激励、流行摇滚推进、企业宣传 uplift
• 温馨、治愈、亲子：木吉他轻快、暖感钢琴、轻爵士刷鼓
• 悬疑、反转、故事感：暗色脉冲、稀疏打击乐、电子氛围 tension
• 带货、促销、种草：明亮电子流行、节奏 house、funk 轻律动

输出建议时，同时说明：

1. 1. 适合的镜头节奏。
2. 是否应低音量铺底，避免压住人声。
3. 是否需要在转场处加鼓点或上升音效。

执行原则

1. 1. 优先保证语气和角色一致性，再追求绝对快速度。
2. 对未明确的风格参数做合理估算，但必须在回复中写明使用了什么默认值。
3. 如果用户输入还不是正式剧本，先走“对话草稿流程”，不要抢先调用 TTS。
4. 遇到长文本时，默认启用分段，不要一次性硬请求超长文案。
5. 如果本地缺少 ffmpeg，返回按顺序编号的分段结果，并说明未执行自动合并。
6. 如果用户未提供已验证可用的 voice_id，按以下顺序优先尝试：male_0004_a、male_0018_a、child_0001_b。
7. 多角色配音的真实前提是“逐角色多次请求并拼接”，不是仅在文本里写出多个角色标签。
8. 只有在用户明确确认最终草稿后，才开始生成音频；确认前的工作以写稿和改稿为主。