音频、转写与 Realtime API

小白：先按传输方式选端点

文本转语音走 POST /v1/audio/speech，响应通常是 MP3、WAV 等音频字节；文件转写和翻译分别走 POST /v1/audio/transcriptions 与 /v1/audio/translations，请求为 multipart；实时双向音频走 GET /v1/realtime 的 WebSocket。它们分别是二进制 HTTP、表单 HTTP 和双向长连接，不能复用同一个 JSON/SSE 解析器。

调用前先在令牌管理创建本站 API Key，再从模型广场确认模型支持对应的音频端点。下面只选两个代表型号，不表示列出全部音频模型：

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="你的本站 API Key"
export TTS_MODEL_NAME="gpt-4o-mini-tts"
export TRANSCRIBE_MODEL_NAME="gpt-4o-mini-transcribe"

BASE_URL 不包含末尾的 /v1。如果当前 Key 的分组看不到上述型号，请从登录后的模型广场复制同端点的其他精确模型 ID。

TTS 与文件转写最小请求

Copycurl --fail --show-error "$BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- \
  --output speech.mp3 <<JSON
{"model":"$TTS_MODEL_NAME","voice":"alloy","input":"欢迎使用语音接口","response_format":"mp3"}
JSON

curl "$BASE_URL/v1/audio/transcriptions" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=$TRANSCRIBE_MODEL_NAME" \
  -F "file=@meeting.wav" \
  -F "response_format=json"

--fail 会让 HTTP 错误直接返回失败，避免把常见 JSON 错误体当成正常 MP3 使用。生产代码还应检查状态码和 Content-Type。转写上传前校验格式、字节数、时长和声道；长音频若需切片，保留时间偏移并在合并时处理重叠段。

Realtime WebSocket 生命周期

服务端 WebSocket 客户端连接 wss://api.tu-zi.com/v1/realtime?model=精确模型ID 时，可在握手中发送 Authorization: Bearer <本站 API Key>。本站也兼容 Sec-WebSocket-Protocol: realtime, openai-insecure-api-key.<本站 API Key> 的形式。连接后按所选模型协议发送会话配置、音频缓冲区和响应创建事件，并消费服务端事件；事件名和字段会随模型与渠道变化，必须做实际契约测试。

浏览器不能安全保存长期 API Key。本站当前没有公开的 Realtime 短期凭据签发接口，因此浏览器场景应优先连接自己的受控后端代理，不要把长期密钥写入前端代码或直接发给用户设备。

Copyconnect → session configured → audio append → response create
        ← transcript/audio deltas ← response done or error

每条连接设置最大会话时长、空闲超时、消息大小、发送队列上限和心跳。消费速度落后时要丢弃可重建的可视化帧或中止会话，不能让无界队列耗尽内存。

错误、断线与重复处理

文件端点的 400 常见于格式、时长或字段错误，413 是上传过大；Realtime 握手的 401/403 是凭据或权限问题，连接后的错误通常以事件出现。保存会话 ID、响应 ID、事件序号和 Request-ID。断线后默认建立新会话，不要盲目重放所有音频；若协议支持恢复，也要按服务端确认点重放，避免重复转写、重复播报或重复工具调用。

语音输出一旦开始播放，业务层应记录已播放游标；用户打断时同时停止本地播放、清空待播队列并发送协议支持的取消事件。音频输入须得到合法授权并明确告知录音与处理范围。

生产质量、隐私与成本

评测覆盖口音、噪声、多人重叠、专有名词、数字、语言切换、首包延迟和中断响应。日志默认不存原始音频，只记录经过最小化的元数据、时长、模型、状态和追踪 ID；确需留存时加密、分权、设置保留期和删除机制。TTS 按输入、音频或模型规则计费，转写通常与音频时长相关，Realtime 还可能包含输入输出音频 token；必须以模型广场与使用日志对账。

专家：延迟预算与容量保护

将端到端延迟拆为采集、网络、VAD、上游首包、合成、抖动缓冲和播放，分别设 SLO。使用有界缓冲区、流式读写和连接级限流；慢消费者触发背压或断开。部署时压测并发连接、每秒音频帧、编码 CPU、出站带宽和断线风暴，确保代理不会缓冲 WebSocket，也不会因单连接积压拖垮整个实例。