声音克隆

最后更新：2026-11-06

POSThttps://www.sagelib.com/v1/files

上传一段干净人声作为参考音频，得到克隆音色 ID；合成时把这个 ID 填到 voice 即可用该音色朗读任意文本（Zero-shot 音色克隆）。

接口鉴权方式请参考：API接入与鉴权

请求参数

请求头

参数名称	描述
*Authorization `string`	鉴权令牌，格式为 Bearer ${AIGATEWAY_TOKEN}
*Content-Type `string`	仅支持 `multipart/form-data`

Body 参数

参数名称	描述
*file `file`	参考音频文件。建议 5~30 秒、单人、无背景音乐与噪音；支持 wav / mp3 等常见格式，单文件不超过 25MB
*purpose `string`	固定填 `voiceClone`
description `string`	备注，便于自己区分多个音色，最长 200 字符

请求示例

curl -X POST 'https://www.sagelib.com/v1/files' \
  -H "Authorization: Bearer ***" \
  -F "file=@sample.wav" \
  -F "purpose=voiceClone" \
  -F "description=我的音色"

import requests

url = "https://www.sagelib.com/v1/files"
headers = {"Authorization": "Bearer ***"}
with open("sample.wav", "rb") as f:
    resp = requests.post(url, headers=headers,
                         files={"file": ("sample.wav", f, "audio/wav")},
                         data={"purpose": "voiceClone", "description": "我的音色"})
print(resp.status_code, resp.json())

响应参数

参数名称	描述
id `string`	文件 ID，即合成时要填的 `voice`
name `string`	文件名
purpose `string`	固定为 `voiceClone`
bytes `number`	文件大小（字节）
created_at `number`	创建时间（Unix 秒）

用克隆音色合成

把上一步返回的 id 填到语音合成的 voice 字段，其余参数与语音合成完全一致；计费仍按输入字符数计算，与音色无关。

curl -X POST 'https://www.sagelib.com/audio/speech' \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "index-tts-1.5",
    "input": "要合成的文本",
    "voice": "2118679383225405440",
    "response_format": "mp3"
  }' \
  -o output.mp3

其它接口

方法	路径	说明
GET	`/v1/files?purpose=voiceClone`	列出本人已上传的参考音频（默认 20 条，`limit` 上限 100）
GET	`/v1/files/{id}`	查询单个文件
DELETE	`/v1/files/{id}`	删除文件；已用该音色生成过的音频不受影响

注意事项

purpose 只接受 voiceClone，其它用途会被拒绝。
文件按账号隔离：同一账号下的多把 Key 共用同一批音色，看不到也删不了别人的文件。
上传不产生费用，也不计入用量报表；扣费只发生在合成时（按输入字符数）。
同一段文本 + 同一个音色 ID 的输出是确定性的，便于对账与回归。
参考音频质量决定克隆效果：优先单人、少混响、无 BGM 的干声。

错误码

状态码	说明
401	缺少或无效的 API Key
400	缺少 `file`，或 `purpose` 不是 `voiceClone`
413	文件超过 25MB 上限
404	文件不存在，或不属于当前账号