www_site/docs/TTS_UPSTREAM_REQUEST.md

# TTS 上游资料请求清单

状态：旧工程代码契约和一次真实成功联调已完成；完整音色资料、计量规则和上游高级能力仍待确认。
日期：2026-09-08

## 已核查范围

- 当前仓库：未发现新的 TTS 客户端或适配器；目标业务边界仍在 `API_CONTRACT.md`。
- 已授权旧工程：`E:\RD\Kaotings\kts_site\KT26-0903_Big-TTS`，只读核查 `ReadMe.md`、`server.js`、`package.json`、Docker 配置和前端调用。
- 旧工程代码默认上游：`http://43.248.188.28:44480/v1/audio/speech`，这是默认配置，不是实际部署证明。
- 旧工程实际调用是同步 `POST`，JSON 字段为 `model`、`input`、`voice`、`response_format`、`speed`，返回 WAV/MP3 字节流。
- 测试服务器：当前仅有 PostgreSQL、API、Web、Caddy 和 SSH 监听；未发现 TTS 监听端口或 TTS 服务配置。
- `services/api`：仅实现认证、会话、权益和额度基础；没有 Phase 3 生成路由或上游调用。
- 旧工程没有真实音色语言元数据、异步任务查询、provider task ID 或幂等键实现。
- 代码默认地址首次无鉴权请求返回 `401 Unauthorized`；配置服务端凭据后最小文本请求返回 `200 audio/wav`，地址和凭据当前可用。
- `www_site` 不增加网页端上游地址/API Key 配置后台；Phase 3 只从服务端环境变量 `TTS_UPSTREAM_URL`、`TTS_API_KEY` 和 `TTS_TIMEOUT_SECONDS` 加载配置。
- 测试服务器的配置文件为 root-only `/etc/kaotings/api.env`；API Key 原文不进入响应、前端构建、Git 或普通日志。

## 需要内部服务负责人提供

请通过安全渠道提供以下信息，不要提交 Git、不要放入前端构建，也不要粘贴到普通日志：

1. 测试环境内部地址、端口、允许访问的来源机器和网络方式。
2. OpenAPI、接口文档或一组脱敏请求/响应示例。
3. 鉴权方式、凭据注入名称、凭据有效期和轮换方式。实际密钥只进入服务器秘密配置。
4. 音色 ID、语言、名称、启用状态和各 Plan 可用范围。
5. 参数范围，例如格式、语速、音调、采样率、声道和最大文本长度。
6. 音频返回方式：同步字节流、短期 URL、结果 URL 或 provider task ID 查询。
7. 同步/异步行为、任务状态、查询接口、取消能力、幂等支持和重试边界。
8. 连接/读取/任务超时、响应大小、计量口径和错误码映射。
9. 最小联调用例、失败用例和允许保存的测试音频/文本保留期。

## 当前仍缺少

当前最具体阻断是：

- 需要提供完整当前音色 ID/语言清单和计量规则；目前只确认代码默认 `default` 可用。
- 需要确认上游是否支持异步任务、查询、取消、provider task ID、幂等和重试；旧工程代码未实现这些能力。

资料补齐前，Phase 3 不固定生产音色和计量策略，不创建伪造音色，不使用 Mock 成功替代真实联调，不扫描或猜测其他服务地址。