feat: 新增音频格式与采样率配置，完善OpenAI兼容格式映射

1.  新增BYTEDANCE_TTS_FORMAT和BYTEDANCE_TTS_SAMPLE_RATE环境变量配置
2.  实现OpenAI TTS格式到火山API格式的映射转换
3.  自动处理wav格式：内部用pcm请求后封装标准WAV头
4.  动态设置响应Content-Type，适配不同输出格式
5.  更新文档与配置示例，完善日志与错误处理

.env.example

@@ -21,6 +21,13 @@ BYTEDANCE_TTS_SPEAKER=your_speaker_id_here
 # 请求超时时间，默认30秒
 BYTEDANCE_TTS_TIMEOUT=30s
 
+# 音频格式：mp3/ogg_opus/pcm/wav（默认mp3）
+# 注意：流式场景下wav会多次返回header，内部自动用pcm请求再封装header
+BYTEDANCE_TTS_FORMAT=mp3
+
+# 音频采样率：8000/16000/22050/24000/32000/44100/48000（默认24000）
+BYTEDANCE_TTS_SAMPLE_RATE=24000
+
 # OpenAI兼容接口的API密钥（可选）
 OPENAI_TTS_API_KEY=your_openai_compatible_key_here
 

README.md

@@ -6,20 +6,15 @@
 
 ### 主要特性
 
-- ✅ 完全兼容OpenAI `/v1/audio/speech` API接口
-- ✅ 支持火山引擎TTS v3 API（单向流式）
-- ✅ 支持API Key鉴权方式
-- ✅ 支持多种发音人和模型版本
-- ✅ 内置速率限制和统计功能
-- ✅ 支持配置API密钥验证
-- ✅ 并发限制：最多同时处理10个请求（保护上游API）
-- ✅ 跨平台支持（Windows/Linux/macOS）
-
-## 文件说明
-
-- `tts_server.go` - 主程序源码
-- `.env.example` - 环境变量配置示例
-- `go.mod` / `go.sum` - Go模块依赖
+- 完全兼容OpenAI `/v1/audio/speech` API接口
+- 支持火山引擎TTS v3 API（HTTP Chunked单向流式）
+- 支持多种音频格式：mp3、ogg_opus、pcm、wav
+- 支持API Key鉴权方式
+- 支持多种发音人和模型版本
+- 内置速率限制和统计功能
+- 支持配置API密钥验证
+- 并发限制：最多同时处理10个请求（保护上游API）
+- 跨平台支持（Windows/Linux/macOS）
 
 ## 快速开始
 
@@ -31,7 +26,7 @@
 ### 1. 编译程序
 
 ```bash
-go build -o tts_server tts_server.go
+go build -o tts-api .
 ```
 
 ### 2. 配置环境变量
@@ -48,10 +43,10 @@ cp .env.example .env
 
 ```bash
 # Windows
-tts_server.exe
+tts-api.exe
 
 # Linux/macOS
-./tts_server
+./tts-api
 ```
 
 服务默认监听 `8080` 端口。
@@ -65,13 +60,15 @@ tts_server.exe
 | `BYTEDANCE_TTS_API_KEY` | 火山引擎新版控制台 API Key | `your_api_key_here` |
 | `BYTEDANCE_TTS_RESOURCE_ID` | 资源ID，决定模型版本 | `seed-tts-1.0` |
 | `BYTEDANCE_TTS_SPEAKER` | 发音人（音色）ID | `zh_female_qingxin` |
-| `BYTEDANCE_TTS_MODEL` | 模型子版本（复刻音色必填，不设默认 `seed-tts-2.0-standard`） | `seed-tts-2.0-standard` |
 
 ### 可选参数
 
 | 变量名 | 说明 | 默认值 |
 |--------|------|--------|
+| `BYTEDANCE_TTS_MODEL` | 模型子版本（复刻音色必填） | `seed-tts-2.0-standard` |
 | `BYTEDANCE_TTS_TIMEOUT` | 请求超时时间 | `30s` |
+| `BYTEDANCE_TTS_FORMAT` | 音频格式：`mp3` / `ogg_opus` / `pcm` / `wav` | `mp3` |
+| `BYTEDANCE_TTS_SAMPLE_RATE` | 采样率：8000/16000/22050/24000/32000/44100/48000 | `24000` |
 | `OPENAI_TTS_API_KEY` | OpenAI兼容接口的API密钥（逗号分隔支持多个） | 无 |
 | `PORT` | 服务监听端口 | `8080` |
 | `ALLOWED_ORIGINS` | 允许跨域请求的来源（多个用英文逗号分隔；调试可设为 `*`） | 无（不设则拒绝所有跨域） |
@@ -87,30 +84,46 @@ tts_server.exe
 | `seed-icl-1.0-concurr` | 声音复刻1.0并发版 |
 | `seed-icl-2.0` | 声音复刻2.0字符版 |
 
-> ⚠️ 上表为通用模型名。火山控制台实际显示的资源 ID 字符串格式通常是 `volc.megatts.default`、`volc.megatts.icl` 等（带版本号会形如 `volc.megatts.icl.2_0`），**以控制台资源管理页面显示的字符串为准**。资源 ID 与音色必须**同时在控制台开通**才能组合使用，否则 API 会返回 `code=55000000, message=resource ID is mismatched with speaker related resource`。
+> 上表为通用模型名。火山控制台实际显示的资源 ID 字符串格式通常是 `volc.megatts.default`、`volc.megatts.icl` 等（带版本号会形如 `volc.megatts.icl.2_0`），**以控制台资源管理页面显示的字符串为准**。资源 ID 与音色必须**同时在控制台开通**才能组合使用，否则 API 会返回 `code=55000000, message=resource ID is mismatched with speaker related resource`。
 
 **注意：** 1.0音色只能搭配 `seed-tts-1.0` Resource ID，2.0音色只能搭配 `seed-tts-2.0` Resource ID。
 
+### 音频格式说明
+
+本项目使用火山 v3 **HTTP Chunked 单向流式** API（[官方文档](https://www.volcengine.com/docs/6561/1598757)），支持以下音频格式：
+
+| 格式 | Content-Type | 说明 |
+|------|-------------|------|
+| `mp3` | `audio/mpeg` | 默认格式，API原生支持，推荐使用 |
+| `ogg_opus` | `audio/ogg` | OGG Opus格式，API原生支持 |
+| `pcm` | `audio/pcm` | 原始PCM数据，API原生支持 |
+| `wav` | `audio/wav` | 本端用PCM请求API后封装WAV header（流式场景下API的wav会多次返回header，所以内部用pcm再拼装） |
+
+> 流式场景下直接请求 wav 格式，API每个chunk都会返回一个完整的 wav header，导致拼接后的音频损坏。因此当用户选择 wav 输出时，适配器自动用 pcm 格式请求 API，最后在客户端拼装标准 44 字节 WAV 文件头。
+
 ### v3 API 调用说明
 
-本项目按火山 v3 单向流式 TTS API 实现（[官方文档](https://www.volcengine.com/docs/6561/2528925)），相比 v1/v2 有以下关键差异：
+本项目按火山 v3 HTTP Chunked 单向流式 TTS API 实现（[官方文档](https://www.volcengine.com/docs/6561/1598757)），相比 v1/v2 有以下关键差异：
 
+- **协议**：HTTP Chunked 流式，请求路径 `https://openspeech.bytedance.com/api/v3/tts/unidirectional`
 - **不再使用业务集群**（`cluster` 字段在 v3 已废弃），改用 `X-Api-Resource-Id` HTTP header 路由模型
 - **鉴权 header 只有** `X-Api-Key` 一个，无 `Authorization`，无 app 对象
+- **用量返回**：携带 `X-Control-Require-Usage-Tokens-Return: *` header，合成结束时响应中包含 `usage` 字段
 - **`req_params.model` 字段**：v3 必须显式传子模型版本。可选值：
   - `seed-tts-2.0-standard`（默认，标准版，常规音色/复刻音色通用）
   - `seed-tts-2.0-expressive`（表现力增强版，部分复刻音色推荐）
   - 留空时会用 `seed-tts-2.0-standard` 作为兜底
 - **复刻音色（`S_` 开头的 speaker）必须显式传 model**，否则可能因默认模型与复刻音色不匹配返回 `55000000`
+- **响应 event 字段**：`TTSSentenceStart`/`TTSSentenceEnd` 标记句子边界，音频数据在默认 event 中返回
 
 ## CORS 跨域配置
 
 跨域请求由 `ALLOWED_ORIGINS` 环境变量控制，按**完整 origin**（含协议 + 域名 + 端口）精确匹配：
 
-- ✅ `https://app.example.com` — 精确匹配一个来源
-- ✅ `https://a.com,https://b.com` — 多个来源英文逗号分隔
-- ✅ `*` — 允许所有来源（**不可与凭据请求共存**，需同时去掉 `Authorization` 头）
-- ❌ `app.example.com` — 缺协议头，**永远不会匹配**（服务端强制校验 `http://` / `https://` 开头）
+- `https://app.example.com` — 精确匹配一个来源
+- `https://a.com,https://b.com` — 多个来源英文逗号分隔
+- `*` — 允许所有来源（**不可与凭据请求共存**，需同时去掉 `Authorization` 头）
+- `app.example.com` — 缺协议头，**永远不会匹配**（服务端强制校验 `http://` / `https://` 开头）
 
 **典型坑**：
 
@@ -118,14 +131,6 @@ tts_server.exe
 2. `ALLOWED_ORIGINS=*` + 客户端带 `Authorization`：浏览器按规范会**直接拒绝预检**（凭据 + 通配符冲突），POST 根本发不出去。
 3. 同源请求（前端和 TTS 服务同域名）不受 CORS 限制，`ALLOWED_ORIGINS` 怎么配都不影响。
 
-诊断时打开浏览器 DevTools → Network → 看 OPTIONS 预检的响应头：
-
-```
-access-control-allow-origin: https://your-frontend.com
-access-control-allow-credentials: true
-```
-
-如果 OPTIONS 返回 403 但响应头里**没有** `access-control-allow-origin`，说明 origin 不在白名单，Zeabur 实时日志会输出 `CORS拦截: 来源=...`。
 ## API 使用说明
 
 ### OpenAI 兼容接口
@@ -142,7 +147,7 @@ access-control-allow-credentials: true
   "model": "tts-1",
   "input": "你好，这是一个测试文本",
   "voice": "alloy",
-  "response_format": "wav",
+  "response_format": "mp3",
   "speed": 1.0
 }
 ```
@@ -150,16 +155,33 @@ access-control-allow-credentials: true
 **参数说明：**
 - `model` - 模型名称（OpenAI兼容，实际不影响）
 - `input` - 要合成的文本
-- `voice` - 发音人（OpenAI兼容，实际不影响）
-- `response_format` - 输出格式：仅支持 `wav`
+- `voice` - 发音人（OpenAI兼容，实际使用配置的BYTEDANCE_TTS_SPEAKER）
+- `response_format` - 输出格式：`mp3`（默认）、`opus`（映射到ogg_opus）、`wav`、`pcm`、`aac`/`flac`（降级到mp3）
 - `speed` - 语速：0.25 ~ 4.0
 
+**格式映射（OpenAI → 火山）：**
+
+| OpenAI response_format | 火山 API 格式 | Content-Type |
+|------------------------|--------------|--------------|
+| `mp3` | mp3 | audio/mpeg |
+| `opus` | ogg_opus | audio/ogg |
+| `wav` | pcm → 封装wav header | audio/wav |
+| `pcm` | pcm | audio/pcm |
+| `aac` / `flac` | mp3（降级） | audio/mpeg |
+
 **示例调用：**
 
 ```bash
+# MP3格式（默认）
 curl -X POST "http://localhost:8080/v1/audio/speech" \
   -H "Content-Type: application/json" \
   -d '{"model":"tts-1","input":"你好，世界","voice":"alloy","speed":1.0}' \
+  -o output.mp3
+
+# WAV格式
+curl -X POST "http://localhost:8080/v1/audio/speech" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"tts-1","input":"你好，世界","voice":"alloy","response_format":"wav","speed":1.0}' \
   -o output.wav
 ```
 
@@ -223,10 +245,10 @@ curl http://localhost:8080/health
 
 ```bash
 # Windows
-set PORT=8081 && tts_server.exe
+set PORT=8081 && tts-api.exe
 
 # Linux/macOS
-PORT=8081 ./tts_server
+PORT=8081 ./tts-api
 ```
 
 ### 3. 如何配置多个API密钥？
@@ -244,19 +266,24 @@ OPENAI_TTS_API_KEY=sk-key1,sk-key2,sk-key3
 1. 去**火山控制台** → 语音技术 → 你的应用 → 资源管理或音色库
 2. 用控制台的在线体验/调试试一下同一对 `BYTEDANCE_TTS_RESOURCE_ID` + 音色
 3. 控制台能合成的组合才是正确的
-4. 把控制台显示的**实际资源 ID 字符串**（通常是 `volc.megatts.*` 格式）填到 Zeabur 的 `BYTEDANCE_TTS_RESOURCE_ID`
+4. 把控制台显示的**实际资源 ID 字符串**（通常是 `volc.megatts.*` 格式）填到 `BYTEDANCE_TTS_RESOURCE_ID`
 5. 如果你用的是**声音复刻**音色（speaker 以 `S_` 开头），同时确认设置了 `BYTEDANCE_TTS_MODEL`（推荐 `seed-tts-2.0-standard` 或 `seed-tts-2.0-expressive`）。复刻音色不传 `model` 字段是 55000000 的常见原因之一
 
 ### 5. PowerShell 下 `curl` 命令被解释错
 
-PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名，参数完全不同（如 `-m` 会被当成歧义参数）。**必须写 `curl.exe`**：
+PowerShell 里 `curl` 是 `Invoke-WebRequest` 的别名，参数完全不同。**必须写 `curl.exe`**：
 
 ```powershell
-curl.exe -v -X POST "https://your-app.zeabur.app/v1/audio/speech" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_KEY" --data-binary "@body.json"
+curl.exe -v -X POST "http://localhost:8080/v1/audio/speech" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_KEY" --data-binary "@body.json"
 ```
 
-另外 PowerShell 里 `{"foo":"bar"}` 不加单引号会被当成脚本块解析，body 被吃掉所有引号。**要么用单引号包 JSON**，要么把 body 写到文件用 `--data-binary "@file.json"`。
-### 6. 查看日志
+另外 PowerShell 里 `{"foo":"bar"}` 不加单引号会被当成脚本块解析。**要么用单引号包 JSON**，要么把 body 写到文件用 `--data-binary "@file.json"`。
+
+### 6. WAV 格式音频播放异常？
+
+流式场景下火山 API 的 wav 格式会每个 chunk 都返回完整的 wav header，拼接后音频损坏。本项目已自动处理：选择 wav 输出时，内部用 pcm 格式请求 API，最后拼装标准 wav header。如仍有问题，建议改用 `mp3` 格式。
+
+### 7. 查看日志
 
 服务启动后输出到 stdout/stderr。常见日志关键字：
 
@@ -284,6 +311,14 @@ CORS拦截: 来源="https://..." 路径=/v1/audio/speech 方法=POST 客户端=.
 警告: TTS 合成失败 - 路径=... 文本长度=50 耗时=114ms 错误=...
 ```
 
+**适配器层日志**：
+
+```
+Sentence start: sequence=0, sentence=...
+Sentence end: sequence=0
+TTS synthesis completed, usage: &{TextWords:5}
+```
+
 **请求结束通用日志**（每个请求都有，由 Logger 中间件输出）：
 
 ```
@@ -291,17 +326,6 @@ POST /v1/audio/speech 1.2.3.4:56789 200 245ms
 POST /v1/audio/speech 1.2.3.4:56789 400 1ms
 ```
 
-**调试技巧**：
-
-- 排查请求被拒：在 Zeabur 实时日志里搜 `警告:` 或 `CORS拦截:`
-- 排查 CORS：搜 `CORS拦截:` 看具体被拒的 origin
-- 排查 4xx/5xx：找对应路径的 `POST /v1/audio/speech ... 4xx` 行，再往上翻看 `警告:` 行
-- 排查 55000000 等上游错误：搜 `TTS service error` 或 `TTS 合成失败`，看火山返回的 code/message
-
-**静默路径（不会产生日志）**：
-
-- CORS 预检成功的 `OPTIONS ... 204`：完全不打日志（设计如此，避免高频预检刷屏）。CORS 拒绝的 OPTIONS 仍会输出 `CORS拦截:` 日志
-
 ## 部署建议
 
 ### Linux Systemd 服务
@@ -318,7 +342,7 @@ Type=simple
 User=www-data
 WorkingDirectory=/www/wwwroot/tts-server
 EnvironmentFile=/www/wwwroot/tts-server/.env
-ExecStart=/www/wwwroot/tts-server/tts_server
+ExecStart=/www/wwwroot/tts-server/tts-api
 Restart=always
 RestartSec=10
 
@@ -334,6 +358,14 @@ sudo systemctl enable tts-server
 sudo systemctl start tts-server
 ```
 
+### Docker 部署
+
+```bash
+docker compose up -d
+```
+
+环境变量通过 `.env` 文件或 docker-compose.yml 传入。
+
 ## 许可证
 
 本项目采用非商业用途许可协议。您可以免费使用本软件用于非商业目的，但禁止用于任何商业活动。详细条款请参阅 [LICENSE](LICENSE) 文件。
@@ -349,3 +381,4 @@ sudo systemctl start tts-server
 6. 客户端请求 URL 是否以 https:// 开头
 7. 生产环境凭据是否定期轮换（API Key 明文出现在日志/对话中时立刻重置）
 8. 复刻音色（speaker 以 `S_` 开头）是否设置了 `BYTEDANCE_TTS_MODEL`（默认 `seed-tts-2.0-standard`）
+9. 音频格式是否匹配客户端解码能力（默认 mp3 兼容性最好）

adapter/volcano/volcano.go

@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/base64"
+	"encoding/binary"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -63,7 +64,80 @@ func convertSpeedToSpeechRate(speed float64) int {
 	return rate
 }
 
-func Synthesis(config *dto.ByteDanceTTSConfig, httpClient *HTTPClient, text string, speed float64, voice string) (*dto.SynthesisResult, error) {
+// resolveAPIFormat 根据用户期望的输出格式决定实际请求火山 API 的格式。
+// 文档明确指出：流式场景下传入 wav 会多次返回 wav header，建议使用 pcm。
+// 因此当用户要 wav 输出时，用 pcm 请求 API，最后由本端拼装完整 wav header。
+func resolveAPIFormat(desiredFormat string) (apiFormat string, needWavHeader bool) {
+	switch desiredFormat {
+	case "wav":
+		return "pcm", true
+	case "mp3", "ogg_opus", "pcm":
+		return desiredFormat, false
+	default:
+		return "mp3", false
+	}
+}
+
+// buildWavHeader 构造标准 44 字节 WAV 文件头（16-bit PCM, mono）。
+func buildWavHeader(dataLen int, sampleRate int) []byte {
+	header := make([]byte, 44)
+	byteRate := sampleRate * 2 // 16bit * 1channel / 8 * sampleRate
+	blockAlign := 2            // 16bit / 8 * 1channel
+
+	copy(header[0:4], "RIFF")
+	binary.LittleEndian.PutUint32(header[4:8], uint32(36+dataLen))
+	copy(header[8:12], "WAVE")
+	copy(header[12:16], "fmt ")
+	binary.LittleEndian.PutUint32(header[16:20], 16)       // SubChunk1Size
+	binary.LittleEndian.PutUint16(header[20:22], 1)        // PCM format
+	binary.LittleEndian.PutUint16(header[22:24], 1)        // NumChannels
+	binary.LittleEndian.PutUint32(header[24:28], uint32(sampleRate))
+	binary.LittleEndian.PutUint32(header[28:32], uint32(byteRate))
+	binary.LittleEndian.PutUint16(header[32:34], uint16(blockAlign))
+	binary.LittleEndian.PutUint16(header[34:36], 16)       // BitsPerSample
+	copy(header[36:40], "data")
+	binary.LittleEndian.PutUint32(header[40:44], uint32(dataLen))
+
+	return header
+}
+
+// FormatContentType 返回音频格式对应的 HTTP Content-Type。
+func FormatContentType(format string) string {
+	switch format {
+	case "mp3":
+		return "audio/mpeg"
+	case "wav":
+		return "audio/wav"
+	case "ogg_opus":
+		return "audio/ogg"
+	case "pcm":
+		return "audio/pcm"
+	default:
+		return "application/octet-stream"
+	}
+}
+
+// MapOpenAIFormat 将 OpenAI TTS response_format 映射为火山 API 支持的格式。
+// OpenAI 支持: mp3, opus, aac, flac, wav, pcm
+// 火山支持: mp3, ogg_opus, pcm, wav(流式不推荐)
+func MapOpenAIFormat(openaiFormat string) string {
+	switch openaiFormat {
+	case "mp3":
+		return "mp3"
+	case "opus":
+		return "ogg_opus"
+	case "wav":
+		return "wav"
+	case "pcm":
+		return "pcm"
+	case "aac", "flac":
+		return "mp3" // 火山不支持 aac/flac，降级到 mp3
+	default:
+		return "mp3"
+	}
+}
+
+func Synthesis(config *dto.ByteDanceTTSConfig, httpClient *HTTPClient, text string, speed float64, voice string, requestFormat string) (*dto.SynthesisResult, error) {
 	reqID := uuid.NewString()
 	speechRate := convertSpeedToSpeechRate(speed)
 
@@ -74,35 +148,54 @@ func Synthesis(config *dto.ByteDanceTTSConfig, httpClient *HTTPClient, text stri
 
 	model := config.Model
 	if model == "" {
-		model = "seed-tts-2.0-standard" // 文档默认值 复刻音色可设为 seed-tts-2.0-expressive
+		model = "seed-tts-2.0-standard"
 	}
 
-	// 请求体结构严格按火山 v3 单向流式 API 文档构造
-	// https://www.volcengine.com/docs/6561/2528925
-	// v3 鉴权只依赖 X-Api-Key 一个 header,不再需要业务集群参数
+	// 决定实际输出格式：优先用请求中指定的格式，否则用配置中的格式，最后默认 mp3
+	outputFormat := config.Format
+	if requestFormat != "" {
+		outputFormat = requestFormat
+	}
+	if outputFormat == "" {
+		outputFormat = "mp3"
+	}
+
+	// 根据输出格式确定 API 请求格式（wav → pcm + 封装 header）
+	apiFormat, needWavHeader := resolveAPIFormat(outputFormat)
+
+	sampleRate := config.SampleRate
+	if sampleRate == 0 {
+		sampleRate = 24000
+	}
+
+	// 按火山 v3 HTTP Chunked 单向流式 API 文档构造请求体
+	// https://www.volcengine.com/docs/6561/1598757
 	params := map[string]interface{}{
 		"user": map[string]interface{}{
-			"uid": reqID, // 文档要求随机字符串,这里复用请求级 UUID
+			"uid": reqID,
 		},
 		"namespace": "UnidirectionalTTS",
 		"req_params": map[string]interface{}{
 			"text":    text,
 			"speaker": speaker,
-			"model":   model, // 复刻音色必填
+			"model":   model,
 			"audio_params": map[string]interface{}{
-				"format":      "wav",
-				"sample_rate": 24000,
+				"format":      apiFormat,
+				"sample_rate": sampleRate,
 				"speech_rate": speechRate,
 			},
 		},
 	}
 
+	// 鉴权 header 按文档 v3 新版控制台方式
 	headers := map[string]string{
 		"Content-Type":      "application/json",
 		"Connection":        "keep-alive",
-		"X-Api-Resource-Id": config.ResourceId, // 模型路由（seed-tts-2.0 / seed-icl-2.0）
+		"X-Api-Resource-Id": config.ResourceId,
 		"X-Api-Request-Id":  reqID,
-		"X-Api-Key":         config.ApiKey, // v3 鉴权 key
+		"X-Api-Key":         config.ApiKey,
+		// 请求用量返回，使合成结束时携带 usage 字段
+		"X-Control-Require-Usage-Tokens-Return": "*",
 	}
 
 	bodyStr, err := json.Marshal(params)
@@ -144,29 +237,39 @@ func Synthesis(config *dto.ByteDanceTTSConfig, httpClient *HTTPClient, text stri
 			continue
 		}
 
+		// code=20000000 表示合成结束
 		if v3Resp.Code == 20000000 {
 			if v3Resp.Usage != nil {
 				log.Printf("TTS synthesis completed, usage: %+v", v3Resp.Usage)
 			}
+			// 跳过后续可能的空行
 			for scanner.Scan() {
 			}
 			break
 		}
 
+		// 非零 code 为错误
 		if v3Resp.Code != 0 {
-			log.Printf("TTS service error: code=%d, message=%s", v3Resp.Code, v3Resp.Message)
+			log.Printf("TTS service error: code=%d, message=%s, event=%s", v3Resp.Code, v3Resp.Message, v3Resp.Event)
 			return nil, fmt.Errorf("TTS service error: %s", v3Resp.Message)
 		}
 
-		if v3Resp.Data != "" {
-			chunk, err := base64.StdEncoding.DecodeString(v3Resp.Data)
-			if err != nil {
-				log.Printf("base64 decode fail: %v", err)
-				return nil, err
+		// 根据 event 字段分类处理
+		switch v3Resp.Event {
+		case "TTSSentenceStart":
+			log.Printf("Sentence start: sequence=%d, sentence=%s", v3Resp.Sequence, v3Resp.Sentence)
+		case "TTSSentenceEnd":
+			log.Printf("Sentence end: sequence=%d", v3Resp.Sequence)
+		default:
+			// 音频数据 chunk：data 字段为 base64 编码的音频片段
+			if v3Resp.Data != "" {
+				chunk, err := base64.StdEncoding.DecodeString(v3Resp.Data)
+				if err != nil {
+					log.Printf("base64 decode fail: %v", err)
+					return nil, err
+				}
+				audioData = append(audioData, chunk...)
 			}
-			audioData = append(audioData, chunk...)
-		} else if v3Resp.Sentence != "" {
-			log.Printf("Received sentence info (sequence %d): %s", v3Resp.Sequence, v3Resp.Sentence)
 		}
 	}
 
@@ -179,5 +282,14 @@ func Synthesis(config *dto.ByteDanceTTSConfig, httpClient *HTTPClient, text stri
 		return nil, fmt.Errorf("no audio data received")
 	}
 
-	return &dto.SynthesisResult{AudioData: audioData, ReqID: reqID}, nil
+	// 若输出格式为 wav，需要在 pcm 数据前拼装完整的 wav header
+	if needWavHeader {
+		wavHeader := buildWavHeader(len(audioData), sampleRate)
+		wavData := make([]byte, 0, len(wavHeader)+len(audioData))
+		wavData = append(wavData, wavHeader...)
+		wavData = append(wavData, audioData...)
+		audioData = wavData
+	}
+
+	return &dto.SynthesisResult{AudioData: audioData, ReqID: reqID, Format: outputFormat}, nil
 }

controller/tts.go

@@ -115,8 +115,14 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 		speed = common.MaxSpeed
 	}
 
+	// 将 OpenAI response_format 映射为火山 API 支持的格式
+	var requestFormat string
+	if req.ResponseFormat != "" {
+		requestFormat = volcano.MapOpenAIFormat(req.ResponseFormat)
+	}
+
 	ttsStart := time.Now()
-	result, err := volcano.Synthesis(&setting.TTSConfig, volcanoClient, req.Input, speed, req.Voice)
+	result, err := volcano.Synthesis(&setting.TTSConfig, volcanoClient, req.Input, speed, req.Voice, requestFormat)
 	duration := time.Since(ttsStart)
 
 	if err != nil {
@@ -129,7 +135,7 @@ func OpenaiTTSHandler(w http.ResponseWriter, r *http.Request) {
 
 	service.GlobalStats.AddRequest(true, duration, "")
 
-	w.Header().Set("Content-Type", "audio/wav")
+	w.Header().Set("Content-Type", volcano.FormatContentType(result.Format))
 	w.Header().Set("Content-Length", fmt.Sprintf("%d", len(result.AudioData)))
 	w.Header().Set("X-Request-Id", result.ReqID)
 	w.WriteHeader(http.StatusOK)

docker-compose.yml

@@ -9,6 +9,8 @@ services:
       - BYTEDANCE_TTS_RESOURCE_ID=${BYTEDANCE_TTS_RESOURCE_ID}
       - BYTEDANCE_TTS_SPEAKER=${BYTEDANCE_TTS_SPEAKER}
       - BYTEDANCE_TTS_TIMEOUT=${BYTEDANCE_TTS_TIMEOUT:-30s}
+      - BYTEDANCE_TTS_FORMAT=${BYTEDANCE_TTS_FORMAT:-mp3}
+      - BYTEDANCE_TTS_SAMPLE_RATE=${BYTEDANCE_TTS_SAMPLE_RATE:-24000}
       - OPENAI_TTS_API_KEY=${OPENAI_TTS_API_KEY:-}
       - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-}
       - PORT=8080

dto/tts.go

@@ -33,9 +33,12 @@ type ByteDanceTTSConfig struct {
 	Model      string // v3 声音复刻/语音大模型 子模型版本，复刻音色必填
 	URL        string
 	Timeout    time.Duration
+	Format     string // 音频编码格式: mp3/ogg_opus/pcm/wav（wav内部用pcm请求再封装header）
+	SampleRate int    // 采样率: 8000/16000/22050/24000/32000/44100/48000
 }
 
 type SynthesisResult struct {
 	AudioData []byte
 	ReqID     string
+	Format    string // 实际输出格式，用于设置 Content-Type
 }

setting/config.go

@@ -50,6 +50,26 @@ func InitTTSConfig() error {
 		}
 	}
 
+	// 音频格式，默认 mp3（文档默认值，流式场景下 wav 会多次返回 header，不推荐）
+	format := os.Getenv("BYTEDANCE_TTS_FORMAT")
+	if format == "" {
+		format = "mp3"
+	}
+
+	// 采样率，默认 24000
+	sampleRate := 24000
+	if srStr := os.Getenv("BYTEDANCE_TTS_SAMPLE_RATE"); srStr != "" {
+		if sr, err := fmt.Sscanf(srStr, "%d", &sampleRate); err != nil || sr != 1 {
+			log.Printf("无效的采样率设置 '%s'，使用默认值: 24000", srStr)
+			sampleRate = 24000
+		}
+		validRates := map[int]bool{8000: true, 16000: true, 22050: true, 24000: true, 32000: true, 44100: true, 48000: true}
+		if !validRates[sampleRate] {
+			log.Printf("不支持的采样率 %d，使用默认值: 24000", sampleRate)
+			sampleRate = 24000
+		}
+	}
+
 	TTSConfig = dto.ByteDanceTTSConfig{
 		ApiKey:     apiKey,
 		ResourceId: resourceId,
@@ -57,6 +77,8 @@ func InitTTSConfig() error {
 		Model:      model,
 		URL:        url,
 		Timeout:    timeout,
+		Format:     format,
+		SampleRate: sampleRate,
 	}
 	return nil
 }
@@ -76,11 +98,13 @@ func CheckEnvironmentVariables() map[string]interface{} {
 	}
 
 	optionalVars := map[string]bool{
-		"BYTEDANCE_TTS_TIMEOUT": os.Getenv("BYTEDANCE_TTS_TIMEOUT") != "",
-		"BYTEDANCE_TTS_MODEL":   os.Getenv("BYTEDANCE_TTS_MODEL") != "",
-		"OPENAI_TTS_API_KEY":    os.Getenv("OPENAI_TTS_API_KEY") != "",
-		"ALLOWED_ORIGINS":       os.Getenv("ALLOWED_ORIGINS") != "",
-		"PORT":                  os.Getenv("PORT") != "",
+		"BYTEDANCE_TTS_TIMEOUT":     os.Getenv("BYTEDANCE_TTS_TIMEOUT") != "",
+		"BYTEDANCE_TTS_MODEL":       os.Getenv("BYTEDANCE_TTS_MODEL") != "",
+		"BYTEDANCE_TTS_FORMAT":      os.Getenv("BYTEDANCE_TTS_FORMAT") != "",
+		"BYTEDANCE_TTS_SAMPLE_RATE": os.Getenv("BYTEDANCE_TTS_SAMPLE_RATE") != "",
+		"OPENAI_TTS_API_KEY":        os.Getenv("OPENAI_TTS_API_KEY") != "",
+		"ALLOWED_ORIGINS":           os.Getenv("ALLOWED_ORIGINS") != "",
+		"PORT":                      os.Getenv("PORT") != "",
 	}
 
 	return map[string]interface{}{