语音播报

接口说明

将指定消息的文本内容转换为语音 MP3 文件，并返回可公开访问的音频 URL。

缓存机制：同一 messageId 第一次调用会生成并上传音频文件，后续重复调用直接返回已缓存的 URL，不会重复计费。

基本信息

项目	说明
接口路径	`POST /v1/chat/tts`
响应类型	`application/json`
认证方式	API Key + 请求签名（认证说明）

请求体

json

{
  "messageId": "msg-uuid",
  "processedText": "Hello, welcome to our platform.",
  "voiceTimbreId": "English_radiant_girl"
}

字段	类型	必填	说明
`messageId`	string	✅	消息 ID，来自流式聊天 SSE 流的 `message_saved` 事件
`processedText`	string	✅	待转语音的文本（需客户端预处理，去除 Markdown 等格式符号）
`voiceTimbreId`	string	❌	音色 ID，默认 `English_radiant_girl`，见可用音色列表

签名示例（传 voiceTimbreId 时，字典序：messageId、processedText、voiceTimbreId）：

待签名字符串 = "messageId=msg-uuid&processedText=Hello, welcome.&voiceTimbreId=English_radiant_girl" + apiSecret

不传 voiceTimbreId 时：

待签名字符串 = "messageId=msg-uuid&processedText=Hello, welcome." + apiSecret

响应格式

成功响应

json

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "audioUrl": "https://dev.open.ai-dol.xyz/saas/voice-broadcast/msg-uuid.mp3"
  },
  "traceId": "9fU0kfWy3E8YFGjS5S8bLPlAXG8xhdTH",
  "timestamp": "1773298769366"
}

字段	类型	说明
`data.audioUrl`	string	MP3 音频文件的公开访问 URL，可直接用于 `<audio src>` 或下载

错误响应

HTTP 状态码	说明
`401`	认证失败
`400`	请求参数缺失或格式错误
`404`	`messageId` 对应的消息不存在
`500`	TTS 服务内部错误

业务错误（HTTP 200）：

message	说明
`Invalid API key`	API Key 无效或已禁用
`Too many requests, please try again later`	触发频率限制
`API key usage limit reached`	达到总调用次数上限
`Message not found: <id>`	消息 ID 不存在
`MiniMax TTS is not configured`	服务端 TTS 未配置
`MiniMax TTS error <code>: <body>`	上游 TTS 服务返回错误

可用音色列表

`voiceTimbreId`	语言	风格
`English_radiant_girl`	英语	活泼女声（默认）
`English_mature_man`	英语	成熟男声
`Chinese_Zhiyu`	中文	知性女声
`Japanese_Kyoko`	日语	温柔女声

客户端示例

javascript

async function generateTts(apiKey, apiSecret, userId, messageId, processedText, voiceTimbreId) {
  const body = { messageId, processedText }
  if (voiceTimbreId) body.voiceTimbreId = voiceTimbreId

  const headers = await buildAuthHeaders(apiKey, apiSecret, userId, body)
  const response = await fetch('/v1/chat/tts', {
    method: 'POST',
    headers,
    body: JSON.stringify(body),
  })

  const result = await response.json()
  if (!result.success) { console.error('TTS 生成失败：', result.message); return null }
  return result.data.audioUrl
}

配合 SSE 流的完整用法

javascript

// 在 SSE 流中监听 message_saved 事件后触发 TTS
if (parsed.type === 'message_saved') {
  const plainText = fullBotMessage
    .replace(/[#*_~`>]/g, '')
    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
    .trim()

  const audioUrl = await generateTts(API_KEY, API_SECRET, USER_ID, parsed.messageId, plainText)
  if (audioUrl) new Audio(audioUrl).play()
}

使用时序

Client                     Sonaops Open API              MiniMax TTS          Cloudflare R2
  │                               │                            │                     │
  │  SSE: [DONE]                  │                            │                     │
  │<──────────────────────────────│                            │                     │
  │  SSE: {"type":"message_saved","messageId":"xxx"}           │                     │
  │<──────────────────────────────│                            │                     │
  │  POST /v1/chat/tts            │                            │                     │
  │──────────────────────────────>│  POST /v1/t2a_v2          │                     │
  │                               │───────────────────────────>│                     │
  │                               │<───────────────────────────│                     │
  │                               │  PUT saas/voice-broadcast/xxx.mp3               │
  │                               │────────────────────────────────────────────────>│
  │  {"data":{"audioUrl":"..."}}  │<────────────────────────────────────────────────│
  │<──────────────────────────────│                            │                     │

语音播报 ​

接口说明 ​

基本信息 ​

请求体 ​

响应格式 ​

成功响应 ​

错误响应 ​

可用音色列表 ​

客户端示例 ​

配合 SSE 流的完整用法 ​

使用时序 ​