音频、转写与 Realtime API

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

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

TTS 与文件转写最小请求

Copycurl "$BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini-tts","voice":"alloy","input":"欢迎使用语音接口","response_format":"mp3"}' \
  --output speech.mp3

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

下载音频时检查 HTTP 状态和 Content-Type 后再写文件，避免把 JSON 错误体保存成 .mp3。转写上传前校验格式、字节数、时长和声道；长音频若需切片，保留时间偏移并在合并时处理重叠段。

Realtime WebSocket 生命周期

客户端连接 wss://<host>/v1/realtime?model=...，使用本站令牌完成握手；连接后按所选模型协议发送会话配置、音频缓冲区和响应创建事件，并消费服务端事件。事件名和字段会随实时模型协议变化，必须以模型和渠道的合约测试为准。浏览器不要嵌入长期 API Key，应由服务端签发短期会话权限或建立受控代理。

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，也不会因单连接积压拖垮整个实例。