语音合成 API
POST /v1/tts 单笔合成 · 长文本异步任务
将文本合成为语音。短文本（≤ 3000 UTF-8 字节，约 1000 汉字）使用单笔接口同步返回音频；长文本使用异步任务接口异步处理。TTS 为纯文本输入（JSON body），无文件直传环节。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reqParams.text | string | 是 | 待合成文本，≤ 3000 UTF-8 字节（约 1000 汉字）；超出请使用异步任务接口 |
| reqParams.speaker | string | 是 | 音色 code，完整清单调 GET /v1/tts/voices 获取（见下方"当前可用音色"表），缺省体验可先传 default |
| audioParams.speechRate | integer | 否 | 语速百分比偏移（-50–100）；当前引擎暂不支持语速控制，传值静默忽略，缺省为原速 |
| audioParams.format | string | 否 | 输出音频格式：wav（缺省）/ mp3（体积约 wav 的 1/5）；服务端转换，url 扩展名即格式 |
当前可用音色
清单随平台音色库动态更新，程序化获取请调 GET /v1/tts/voices（Bearer API Key）。下表为登录态实时渲染，加载失败时仅显示缺省音色。
| 音色 code | 名称 | 性别 | 风格 |
|---|---|---|---|
| default | 默认音色 | female | — |
模型无需指定：平台自动使用 product 为 tts 的当前唯一在线模型。
curl https://www.suanlinfang.cn/v1/tts \ -H "Authorization: Bearer nk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "reqParams": { "text": "欢迎使用算邻坊语音合成。", "speaker": "default" }, "audioParams": { "speechRate": 0 } }'
import requests resp = requests.post( "https://www.suanlinfang.cn/v1/tts", headers={"Authorization": "Bearer nk-your-api-key"}, json={ "reqParams": {"text": "欢迎使用算邻坊语音合成。", "speaker": "default"}, "audioParams": {"speechRate": 0}, }, ).json() audio = requests.get(resp["url"]) # url 为现签产物下载链接（1 小时有效） with open("tts.wav", "wb") as f: f.write(audio.content) print("durationMs:", resp["durationMs"])
inferenceId 是本笔推理流水号（报障时提供可反查），durationMs 是合成时长（毫秒），url 是现签产物下载链接（1 小时有效，过期重新调用即换新链），音频不随响应内嵌、请 GET 该链接下载（格式即 url 扩展名，wav 缺省 / mp3 可选）。计费按 reqParams.text 字符数计算，详见计费说明。时长估算
输入待合成文本，返回字符数与预计成品音频时长（估算系数由平台统一维护，接口单一来源）；鉴权同产品端点（Bearer API Key），文本上限校验与单笔一致（超限返回同款引导错误）。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reqParams.text | string | 是 | 待估算文本；仅此一个入参，speaker / audioParams 与时长估算无关 |
响应示例
{
"chars": 42,
"estimateSeconds": 11
}
长文本使用异步任务接口异步处理：提交全文后平台按 500 字自动切块合成，拼接为完整音频；任务状态机与轮询约定见通用说明 · 异步任务。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reqParams.text | string | 是 | 长文本，≤ 20 万字，按 500 字自动切块 |
| reqParams.speaker | string | 是 | 音色 code，完整清单调 GET /v1/tts/voices 获取（见下方"当前可用音色"表），缺省体验可先传 default |
| audioParams.speechRate | integer | 否 | 语速百分比偏移（-50–100）；当前引擎暂不支持语速控制，传值静默忽略 |
| audioParams.format | string | 否 | 输出音频格式：wav（缺省）/ mp3；作用于聚合后的完整音频，url 扩展名即格式 |
模型无需指定：平台自动使用 product 为 tts 的当前唯一在线模型。
查询接口
查询响应示例（success 时）
{
"status": "success",
"totalUnits": 12,
"doneUnits": 12,
"resultUrl": "https://oss.../output.wav?Expires=...&Signature=...",
"expireAt": "2026-09-27T12:00:00Z",
"durationSec": 356
}
resultUrl 为拼接后完整音频（格式即 url 扩展名，wav 缺省 / mp3 可选）的短时效下载链接（1 小时，expireAt 为绝对过期时间）；链接过期后在任务保留期内重新查询即可获取新链接。任务为二值终态：全部单元成功才返回 resultUrl，失败任务无音频产物（见异步任务通用说明）。
查询本 API Key 所属账户的语音合成调用历史；鉴权同产品端点（Bearer API Key），响应为分页 JSON（无信封）。
单笔历史
分页查询语音合成单笔形态的历史。
Query 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 否 | 页码，默认 1 |
| pageSize | integer | 否 | 每页条数，默认 10 |
任务历史
分页查询语音合成异步任务形态的历史。
Query 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 否 | 页码，默认 1 |
| pageSize | integer | 否 | 每页条数，默认 10 |
响应字段（items[] 内，null 字段不下发）
| 字段 | 类型 | 说明 |
|---|---|---|
| form | string | single / task（单笔 / 异步任务） |
| status | string | processing / success / failed |
| taskNo | string | 任务形态的任务号（单笔为 null 不下发） |
| inputCount | integer | 计费输入计数（TTS=合成字符数，含标点与空格） |
| consumerCost | number | 本笔消费金额（元） |
| elapsedMs | integer | 推理耗时（毫秒） |
| errorMsg | string | 失败原因（成功为 null 不下发） |
| createdAt / completedAt | string | 受理 / 完成时间；两者之差即处理耗时 |
| resultUrl | string | success 且有产物时现签的下载链接（1 小时有效，重查换新链） |
| voice / voiceDisplayName | string | 音色 code 与中文名快照 |
| format / outputSize | — | 实际交付格式（wav/mp3）与产物字节数 |
| durationSec | integer | 合成音频时长秒 |
响应示例
{
"total": 42, "page": 1, "pageSize": 10,
"items": [{
"form": "single", "status": "success",
"voiceDisplayName": "君航", "format": "mp3",
"inputCount": 52, "consumerCost": 0.0104,
"createdAt": "2026-10-29T10:00:00", "completedAt": "2026-10-29T10:00:08",
"resultUrl": "https://…（现签 1h）"
}]
}
按笔后付费：每次成功调用按实际用量从账户余额扣费，失败调用不扣费。费用明细与账户余额可在「语音合成工具」页的「历史记录」与「账户信息」页查看。
按 input 文本字符数计费（含标点与空格），元 / 万字符。牌价以平台实时牌价为准。异步任务按单元逐笔计费（每块文本各计一笔）。