语音合成

Agent 主路径

通过 Universal Skill 使用 MCP 工具 beatra.speech.synthesize。该工具计费，返回异步任务。

先选音色：beatra.voices.list 返回预置与克隆音色的 voice_id 和试听链接。
当模型、语言、格式或价格有影响时，用 capability: "text_to_speech" 调用 beatra.models.list；否则使用 model: "auto" 或省略 model。
创建一个不透明的 client_request_id，把最终参数提交一次。
用 beatra.tasks.get 轮询返回的任务直到终态。

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

工具参数

{
  "voice": "voice_01JX...",
  "input": "Welcome to Beatra — make your first call in three minutes.",
  "language": "en-US",
  "format": "mp3",
  "speed": 1.0,
  "client_request_id": "tts-opaque-1"
}

voice 接受音色管理返回的任何 voice_id；预置与克隆音色行为一致。本能力不含流式与实时对话。

模型、控制项与成本

通用控制项：input（必填，≤50,000 字符）、voice（必填）、 language、format（默认 mp3，另有 wav/flac/opus/pcm）、 speed（0.5–2.0）、volume（>0–10）、pitch（−12–12）、emotion、 sample_rate。每个控制项只按所选模型的元数据使用。

beatra.models.list 是可选模型、支持语言、格式、采样率与客户价格的当前事实来源。不要把模型目录或价格表复制进 agent 提示词。

语音按请求估价预扣，按加权字符线性计费（报价以每 1,000 加权字符为单位）：每个汉字计 2，其他字符计 1。

语言

language 是可选的供应商中立 BCP-47 标签，如 zh-CN、yue-HK、en-US。 Beatra 用主语言子标签与所选模型匹配；省略该字段则由音色或模型自动检测。不支持的语言会被拒绝，而不是被悄悄替换。

当前语音模型覆盖下列 40 种语言；beatra.models.list 的 constraints.supported_languages 是实时的、按模型的事实来源。

代码	语言	代码	语言
`zh`	中文	`tr`	土耳其语
`yue`	粤语	`nl`	荷兰语
`en`	英语	`uk`	乌克兰语
`es`	西班牙语	`th`	泰语
`fr`	法语	`pl`	波兰语
`ru`	俄语	`ro`	罗马尼亚语
`de`	德语	`el`	希腊语
`pt`	葡萄牙语	`cs`	捷克语
`ar`	阿拉伯语	`fi`	芬兰语
`it`	意大利语	`hi`	印地语
`ja`	日语	`bg`	保加利亚语
`ko`	韩语	`da`	丹麦语
`id`	印尼语	`he`	希伯来语
`vi`	越南语	`ms`	马来语
`fa`	波斯语	`sk`	斯洛伐克语
`sv`	瑞典语	`hr`	克罗地亚语
`fil`	菲律宾语	`hu`	匈牙利语
`no`	挪威语	`sl`	斯洛文尼亚语
`ca`	加泰罗尼亚语	`nn`	新挪威语
`ta`	泰米尔语	`af`	南非荷兰语

任务状态与恢复

queued 与 running 不是失败。持续轮询同一个 task_id；不要因为任务还在运行就提交替代请求。创建响应丢失时，用同一个 client_request_id 原样重试；任何输入变化都要换新 ID。失败任务自动退款。只从终态任务响应返回音频产物、实际模型与扣费；产物 URL 是 CDN 地址——请尽快转存到自己的存储。

通过 REST 调用

直连协议集成可使用 POST /v1/audio/speech 与共享任务端点，参数见生成的接口定义。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。