# 语音工作台与接口

文件转写、语音合成与翻译的真实引擎接入约定。

## 先选择项目 [#先选择项目]

在控制台左侧选择项目，然后进入语音识别、语音合成或文本翻译。工作台采用当前登录会话，不需要将 API Key 粘贴到浏览器。

只有项目所在组织的所有者、开发者能够发起调用；只读成员可查看入口。项目需要通过云端服务申请，取得未过期的有效授权。引擎未配置时返回 503，页面明确显示“尚未接入”。

## 文件转写 [#文件转写]

`POST /api/platform/v1/audio/transcriptions`

请求头：`Authorization: Bearer YOUR_API_KEY`、`Content-Type: application/json`。

```json
{
  "audioBase64": "<不含 data: 前缀的 Base64 音频>",
  "mimeType": "audio/wav",
  "language": "zh"
}
```

`language` 可省略。支持 WAV、MP3、OGG、WebM、MP4/M4A，文件最大 5 MiB。服务端检查 Base64、文件大小以及音频文件头与 MIME 的一致性；这不是完整的媒体解码验证，上游仍需安全解码与时长约束。

响应示意只说明结构，实际结果由已接入引擎返回：

```json
{
  "text": "实际转写文本",
  "language": "zh",
  "segments": [{ "start": 0, "end": 1.2, "text": "实际转写文本", "speaker": "speaker_1" }]
}
```

`segments`、`language`、`speaker` 可选。界面不会在上游未提供时伪造时间戳或说话人。

## 语音合成 [#语音合成]

`POST /api/platform/v1/audio/speech`

```json
{ "text": "你好，欢迎使用小象智能。", "language": "zh" }
```

`text` 为 1–5000 个字符；`language` 可选；`voice` 为上游支持的音色 ID，可省略使用引擎默认值。当前没有虚构的音色列表。

响应为 `{ "audioBase64": "...", "mimeType": "audio/wav" }`。工作台将实际音频转换为当前浏览器内的 Blob，支持播放与下载，离开页面后释放 Blob URL。合成音频同样限制为 5 MiB，不直接加载上游返回的任意音频 URL。

## 文本翻译 [#文本翻译]

`POST /api/platform/v1/translate`

```json
{ "text": "Hello, world.", "source": "en", "target": "zh" }
```

响应为 `{ "translation": "实际翻译结果" }`。输入最长 5000 字符，语言代码支持 `zh`、`en` 或 `en-US` 等格式。

## 服务端适配 [#服务端适配]

服务端分别读取 `AI_UPSTREAM_URL`、`STT_UPSTREAM_URL`、`TTS_UPSTREAM_URL` 以及对应的 `_TOKEN`。上游必须使用 HTTPS，不接受浏览器提交任意上游地址。请求、响应采用本页的 JSON 协议；供应商协议不同则需部署转换层。

可选模型配置为 `TRANSLATION_MODEL`、`STT_MODEL`、`TTS_MODEL`。配置后平台向上游增加 `model` 字段。所有凭据只在服务端使用，不出现在能力状态与项目卡中。

统一上游超时为 30 秒；响应受大小、结构、状态及音频格式约束。异常响应返回 502，超时返回 504。不自动重试收费调用，避免重复执行。

## 用量与额度 [#用量与额度]

请求先在事务中预留组织与项目的额度。成功后写入一条用量；失败释放月字符额度，仍占用滚动 60 秒请求次数。翻译和合成按输入字符记录；文件转写只记调用次数，字符数为 0，尚不按音频时长计费。

平台不在数据库保存原始输入文本、音频或推理结果。内容会发送至管理员配置的上游，具体留存策略需由部署方与上游约定。

## 当前边界 [#当前边界]

当前是 HTTP 文件转写和合成接口。实时 WebSocket 转写、流式合成、长音频任务队列和音色目录未实现。提供云端网关不代表已经交付或部署语音模型。

API 的机器可读契约见 [OpenAPI](/openapi.json)，额度和安全设置见 [控制台管理](/docs/console)。
