文档 · 语音合成
免费的语音合成接口怎么用?一个音色,不会中途换人
语音合成只有一个别名 auto/tts,走 POST /v1/audio/speech。它背后有两个模型,切换条件只有一个:当前模型在上游被下线了。响应慢不换,被限流也不换。下面先讲它返回什么——和你想的可能不一样。
一句话定义
auto/tts 是一种 tokenexchage 提供的语音合成能力别名:输入一段文本,返回一个临时音频地址。请求字段是 3 个(model、input、voice),与 OpenAI 的语音接口一致;背后有 2 个候选模型,切换条件只有 1 种——当前模型在上游被下线。唯一与 OpenAI 不同的是返回:JSON 里带地址,而不是音频流。
关键数字
| 接口 | POST /v1/audio/speech |
| 请求字段 | model、input、voice |
| 返回 | JSON 里的临时地址 |
| 别名背后的候选模型数 | 2 |
三步接入
国际区账号请把 base_url 换成 https://alli.website/v1,请求形状与下面完全一致。用国际区 key 打 tokenexchage.com 会返回 401 invalid customer key。
- 在控制台创建 API 密钥。
- 向 https://tokenexchage.com/v1/audio/speech 发 POST,带 model、input、voice。
- 从返回的 JSON 里读 url。
怎么调
curl https://tokenexchage.com/v1/audio/speech \
-H "Authorization: Bearer sk-你的key" \
-H "Content-Type: application/json" \
-d '{"model":"auto/tts","input":"把这句话读出来。","voice":"Cherry"}'
返回的是 JSON,不是音频:
{
"object": "audio.speech",
"url": "https://dashscope-result-….oss-cn-beijing.aliyuncs.com/…",
"expires_at": "2026-09-28T12:40:00Z",
"format": "wav"
}
趁 url 还没过期把它拉下来,或者转存到你自己控制的地方。那是对象存储的临时链接,不是永久 CDN 地址。
import requests
r = requests.post(
"https://tokenexchage.com/v1/audio/speech",
headers={"Authorization": "Bearer sk-你的key"},
json={"model": "auto/tts",
"input": "把这句话读出来。",
"voice": "Cherry"},
).json()
audio = requests.get(r["url"]).content
open("out." + (r["format"] or "wav"), "wb").write(audio)
为什么不套 OpenAI 的形状
OpenAI 的 /v1/audio/speech 是在同一个连接上把音频字节流吐回来。我们不这么做,原因值得说清楚。
别名背后的模型返回的是一个临时地址。真要给你字节流,网关就得自己把音频拉下来再吐出去——意味着每一秒生成的音频都要在本机过两遍。对一个免费开放的功能,这笔带宽花得毫无意义。
所以形状是混合的:保持 JSON,把地址提到顶层,把格式标出来。这是整套接口里唯一一处我们明知偏离 OpenAI 契约的地方,写成文档而不是糊过去。
如果你现在的代码就是在调 OpenAI 的语音接口,需要改的只有一处:从返回值里读 url,而不是消费流。请求路径、鉴权头、model / input / voice 三个字段,全都不变。
别名会做什么、不会做什么
| 上游发生什么 | 你会得到 |
|---|---|
| 模型被下线(404 / 410) | 列表里的下一个模型接手 |
| 超时 | 报错。还是同一个模型 |
| 被限流 | 报错。还是同一个模型 |
| 上游 5xx | 报错。还是同一个模型 |
换 TTS 模型不会让输出「变差一点」——它会变成另一样东西。音色不同,节奏不同。如果你在做一套四十集的音频,中途静默换人不是次品,是一整套得重做。
模型退役是唯一一种「换掉比失败好」的情况,因为不换就什么都没有。所以只有这一种情况会往下走。
这条规则适用于这里所有非对话别名。它和池化路由的做法正好相反,也是向量那个别名只有一个候选的原因。
参数
| 字段 | 必填 | 说明 |
|---|---|---|
model | 是 | 写 auto/tts;也可以直接写具体模型名 |
input | 是 | 要读出来的文字 |
voice | 否 | 默认 Cherry,另有 Ethan、Serena |
请求体上限 25 MB,超了在任何上游调用之前就返 413。Content-Type: multipart/form-data 也收,和 JSON 走同一个处理函数。
什么时候用语音合成
常见的是三类:把长文读出来(新闻、说明书、课程稿),给视频配音,以及给有障碍的用户提供语音输出。这三类对音色的要求不一样——朗读要稳定耐听,配音要跟画面情绪匹配,辅助功能要清晰准确,花哨反而是负担。
不适合的场景也值得说:需要即时反馈的交互(比如每输入一个字就念出来),走语音合成的延迟和网络往返都不划算;需要精确控制停顿、重音、口音的,通用合成模型给不了那么细的粒度。
返回地址之后怎么处理
拿到的是一个临时地址,不是字节流。这意味着两件事:一是要尽快取用,临时地址有有效期,不要把它长期存进数据库当作永久资源;二是取回后自己存一份,后续播放、分发、归档都用自己的存储,不要每次播都去请求那个地址。
长文本要分句处理。一次合成几千字,生成的音频中间很难定位,出错时也只能整段重来。按句或按段切开分别合成,再把音频拼起来,既方便重试单句,也方便后续替换某一段而不影响整体。
音色与一致性
同一个音色在不同长度的文本上表现可能不一样,短句和长段的语速、停顿习惯会有差异。批量生成时建议先用一批有代表性的样本文本试听,确认这个音色在你的内容类型上稳定,再大规模跑。
如果产品里有多处语音输出,把音色固定成一个。用户对声音的识别度很高,同一个产品里换个音色,体验上等同于换了个产品。
延伸阅读
- OpenAI API Reference —— 本页接口沿用的请求形状
- schema.org —— 本页结构化数据所用的类型定义
- Sitemap 协议 —— 站点页面的收录约定
常见问题
返回的是音频文件吗?
不是。返回的是 JSON,里面有一个临时地址;请求路径、鉴权头、model / input / voice 三个字段都和 OpenAI 的语音接口一样。
为什么不直接返回字节流?
真要给字节流,网关就得自己把音频拉下来再吐出去,每一秒生成的音频都要在本机过两遍。对一个免费开放的功能,这笔带宽花得毫无意义。
从 OpenAI 语音接口迁过来要改什么?
只改一处:从返回值里读 url,而不是消费流。
什么时候会换模型?
只有一个条件:当前模型在上游被下线。响应慢不换,被限流也不换。
其他能力
同一套命名,一个能力一个别名,都在 /v1/models 里: