语音播报

接口说明

将指定消息的文本内容转换为语音 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 时，canonicalBody 字典序：messageId、processedText、voiceTimbreId）：

signatureBase = "POST\n/v1/chat/tts\n{X-Timestamp}\n{X-User-ID}\n\nmessageId=msg-uuid&processedText=Hello, welcome.&voiceTimbreId=English_radiant_girl"
X-Signature   = HMAC-SHA256(signatureBase, apiSecret)

不传 voiceTimbreId 时 canonicalBody 仅含两个字段：

signatureBase = "POST\n/v1/chat/tts\n{X-Timestamp}\n{X-User-ID}\n\nmessageId=msg-uuid&processedText=Hello, welcome."
X-Signature   = HMAC-SHA256(signatureBase, apiSecret)

响应格式

成功响应

json

{
  "code": 10200,
  "success": true,
  "message": "OK",
  "data": {
    "audioUrl": "https://cdn.example.com/voice/msg-uuid.mp3"
  },
  "traceId": "9fU0kfWy3E8YFGjS5S8bLPlAXG8xhdTH",
  "timestamp": "1773298769366"
}

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

错误响应

HTTP 状态码	说明
`401`	鉴权失败（缺少请求头、时间戳过期、API Key 无效或签名错误）
`200`	业务错误：`success=false`，常见 `code` 为 `10400` / `10404` / `10500`，错误原因见 `message`

业务错误（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`	服务端未配置 MiniMax TTS
`MiniMax TTS error <status>: <body>`	上游 MiniMax 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, {
    url: '/v1/chat/tts',
  })
  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                     AI-DOL Open API
  │                               │
  │  SSE: [DONE]                  │
  │<──────────────────────────────│
  │  SSE: {"type":"message_saved","messageId":"xxx"}
  │<──────────────────────────────│
  │  POST /v1/chat/tts            │
  │──────────────────────────────>│  合成语音 + 上传音频
  │  {"data":{"audioUrl":"..."}}  │
  │<──────────────────────────────│

语音播报 ​

接口说明 ​

基本信息 ​

请求体 ​

响应格式 ​

成功响应 ​

错误响应 ​

可用音色列表 ​

客户端示例 ​

配合 SSE 流的完整用法 ​

使用时序 ​