Doubao Seed Audio（豆包音频生成模型）

强制自动升级：每次新任务先执行。 使用本 Skill 的安装副本前，必须自动从 SkillHub 强制重装最新已发布版本；即使只优化 Prompt，或本地版本号相同，也要执行，不以检查更新代替重装。

先定位当前 SKILL.md 的绝对路径，将 <skills-root> 替换为当前 Skill 目录的父目录，确认最终覆盖目标为当前 doubao-seedaudio 目录；不要固定使用 ~/.claude/skills/，也不要把 Skill 自身目录传给 --dir。

skillhub install doubao-seedaudio \
  --namespace indiv-volcengine-speech \
  --dir "<skills-root>" \
  --force

升级成功后重新读取当前目录的 SKILL.md 和本任务需要的参考文档，按新版本继续；同一任务只升级一次，重新读取不再次触发升级。缺少 SkillHub CLI、下载失败或覆盖失败时，停止 Skill 执行并报告原因，不静默沿用旧版。此步骤仅更新安装副本，不覆盖正在开发或审查的仓库源码；凭据、输入和生成产物保留在 Skill 目录外。

此目录自包含，可单独复制安装；日常调用使用包内 Python 程序；先在本目录执行 python3 -m pip install -r requirements.txt 安装 Requests，Web Demo 使用单文件 HTML 和本目录独立的 Python Server。

优化音频提示词，生成多角色对话、音乐、音效和声音场景。通过 scripts/audio.py 调用 API，需要 Python 3.9+。

选择任务

用户要求生成时，完成预检后直接执行。只优化时输出一条可直接使用的 Prompt 正文，不附分析或 Markdown 围栏；素材暂不可读时依据文字继续优化，生成前补齐引用并检查规格。

按需阅读

• references/prompt-guide.md：PE 流程、素材职责、生成/替换/延长模板及自检。
• references/api-guide.md：字段、素材限制、非流式响应与字幕单位。
• references/execution-guide.md：配置、预检、输出和故障处理。
• references/demos.md：纯文本场景、多角色对话和参考音频的 Python Demo。
• references/web-demo.md：浏览器生成、API Key 输入、参考素材、播放下载及本地安装。
• references/faq.md：模型、时长、素材组合、字幕与输出常见问题。
• scripts/audio.py：音频生成、凭据检查和离线预览。

<skill-dir> 表示本文件所在目录的绝对路径。生成文件与凭据不写入 skill 安装目录。

PE 的核心约束

1. 先锁定角色、数量、台词归属、事件因果和结局。台词/旁白逐字保留，没有创作授权就不扩写、纠错或翻译；表演指令与朗读正文分开。
2. 先写目标录音和声音层次，再写每份素材职责、正文事件、最后收束。背景声交代听到什么、何时进入、如何与人声共存、何时结束。
3. 保留用户已有引用的形式和编号。实际使用的每份素材逐条分配职责；可获得完整清单时，把未采用的素材逐个写入 【未采用素材】。不强迫所有素材出场。
4. 素材只补充可实际听见的属性，不能据文件名推断人物身份/年龄/剧情。无法听取时依据文字继续，不声称听过。
5. 模型、采样率、鉴权等执行参数与 Prompt 分离。保留用户原有的事件时间要求，不凭空补时间轴，不把精确控制写成保证。

完整模板和优先级以 PE 指南为准。仅会改变角色归属、编辑对象、延长方向等核心结果的歧义需要合并澄清；不为普通语气偏好反复询问。

配置

python3 --version
python3 <skill-dir>/scripts/audio.py --help
python3 <skill-dir>/scripts/audio.py --check-auth

优先使用 VOLCENGINE_SPEECH_API_KEY。旧应用支持 VOLCENGINE_SPEECH_APP_ID 和 VOLCENGINE_SPEECH_ACCESS_TOKEN，使用 --auth legacy 可显式选用。它们来自豆包语音服务，不是方舟 Key 或火山云 AK/SK。

缺少凭据时，让用户在本机配置；不要求把密钥发到对话。可复制 配置模板 并通过 --env-file /absolute/path/volc-speech.env 显式读取。环境变量优先，不自动扫描 .env 或执行配置文件。--check-auth 只报告本地是否配置，不代表远端权限和额度已经验证。

执行流程与接口

模型固定为 seed-audio-1.0，默认输出 WAV、40000 Hz。

生成任务按“整理 Prompt → 确定素材顺序 → 校验输入 → 提交一次请求 → 验证音频”的顺序执行。只优化提示词时完成 Prompt 即交付。

audio.py 向 POST /api/v3/tts/create 发送 JSON，包含 model、text_prompt、audio_config 和可选的 references。脚本负责鉴权、请求 ID 和本地素材的 Base64 编码。命令行参数覆盖扁平 JSON 中的同名配置，未指定项采用默认值；字段定义见 API 指南。

接口一次返回非流式 JSON，audio 为完整音频文件的 Base64；WAV 已含文件头，直接保存。响应可省略 code；返回时只接受整数 0 或 20000000，success=false、空音频或非法 Base64 均视为失败。每次命令只提交一次请求。

生成示例

纯文本生成：

python3 <skill-dir>/scripts/audio.py \
  --prompt '雨夜车内，雨点持续敲击车顶，声音贴近；车外偶尔传来远处驶过的车辆声。最后雨声渐弱，场景自然结束。' \
  --output ./outputs/audio/rain_1.wav

带参考的多角色生成：将优化后的正文保存到 ./work/audio-prompt.txt，清单保存到 ./work/references.json。例如用户已指定两名角色对应以下文件：

[{ "audioFile": "./voices/role-a.wav" }, { "audioFile": "./voices/role-b.wav" }]

路径相对于清单文件所在目录，上例对应 ./work/voices/。数组第 1、2 项分别对应 @音频1、@音频2。不要排序、去重或压缩编号；Prompt 逐条说明角色归属、采用的声音特征和不继承的内容。其他来源可用 speaker、audioUrl、imageFile、imageUrl，每项恰好一个字段。

python3 <skill-dir>/scripts/audio.py \
  --prompt-file ./work/audio-prompt.txt --references-file ./work/references.json \
  --subtitle --dry-run --output ./outputs/audio/dialogue_1.wav

生成任务校验通过后去掉 --dry-run 提交。预览不联网、不读取凭据、不改写 Prompt；Base64 显示为字节数，URL 查询参数隐藏。它不能验证远程素材、音质或账号模型权限。

最多 3 个音频/音色参考，或单独 1 张图片，不混用。音频每个不超过 30 秒和 10 MiB，图片不超过 10 MiB。素材超限或引用缺失时保留 Prompt，说明提交前需要解决的映射或规格问题，不默默删素材或改编号。

图片用于场景参考，不能提供人物音色。已有复刻音色可作为 speaker，本 skill 不训练新音色；不要用正式生成代替免费试听，首次使用后付费复刻音色可能涉及转正费用。

默认输出到当前目录 outputs/audio/，自动生成唯一文件名。格式由 --format 决定，不由扩展名推断。已有文件默认拒绝覆盖；用户明确要求覆盖才使用 --force。

输入与结果校验

提交前检查 Prompt 为 1–3000 个字符，台词与角色归属明确，引用编号与素材清单顺序一致，素材数量、格式、大小和时长符合上述要求。用 --dry-run 检查请求；若 warnings 提示某项规格未校验，实际生成前补充检查该项。

有字幕时检查同名 JSON 的 subtitle.sentences 和 words。start_time/end_time 单位为毫秒，核对开始时间不晚于结束时间，并在换算后落在音频时长内；含对白的任务再核对文本和说话顺序。未返回字幕时如实说明。

试听检查人声、角色差异、背景层次和结尾。文件及字幕检查无法代替听感评估；交付时说明实际完成的检查。

交付

交付本地音频预览/链接，附格式和时长。需要字幕或排查时附同名 JSON，其中包含字幕、请求/日志 ID、实际模型和警告。

provider_audio_url 是服务可能返回的临时链接，约 2 小时有效；需要持久分享时再使用可用的托管工具。duration 是处理后时长，original_duration 是原始生成时长统计。

故障处理

先查看 status、error、warnings、request_id 和 log_id，按失败阶段处理。

WAV、TLS 和其他故障见 execution-guide.md。