API 文档

标准 REST 接口，稳定转发 TTS 合成能力，轻松接入你的应用

🤖 让 AI 助手帮你接入

复制下面整段说明，粘贴给你的 AI 助手（ChatGPT / Claude / 扣子 / Dify 等），它就能直接帮你调用全部接口。也可下载完整文件： API_FOR_AI.md（详细说明）· openapi.json（扣子 / Dify / n8n 直接导入）

# OnePesr 语音 API 接入说明（4 个核心功能）

## 通用规则
- BASE: https://tts.yirenbang.cc
- 鉴权: 每个请求携带 api_key + api_secret（向用户索取，op- 开头的是 key）
- 统一返回: {"code":0或非0,"msg":"...","data":{...}}，先判 code，code=0 才取 data
- 合成类接口同步阻塞，HTTP 超时设 ≥ 60 秒
- 错误处理: 401 密钥问题停止调用；402 额度不足提示充值；400 按 msg 修正重试；500 可原样重试一次

## 功能0·查询可用声音模型（先查再合成）
GET {BASE}/api/v1/models?api_key=xxx&api_secret=xxx
返回 data:
- system_voices: 系统音色列表（33 个，AI 音色库），含 model_code/name/category/gender/language/description
- my_voices: 当前用户自己创建的音色列表（用功能3创建）
- total: 总数
音色编码规则：系统音色 sys_ 开头（女声 sys_f_*/男声 sys_m_*/童声 sys_c_*/方言 sys_d_*），用户音色 usr_ 开头

## 功能1·声音克隆（指定音色合成）
POST {BASE}/api/v1/tts  (JSON)
- text (必填): 1-5000 字符，按字符扣费
- model_code (必填): 音色编码，从功能0获取。示例 sys_f_xiaotian（系统女声）或 usr_xxx（用户自建）
- speed (可选): 0.5-2.0 默认 1.0
- emotion_ext (可选): 语气向量 {"happy":0.8}，8 维 happy/sad/angry/surprised/calm/melancholic/afraid/disgusted，各 0-1，最多 3 项；方言音色自动忽略
返回 data: {task_no, audio_url, chars_used}，audio_url 直接 GET 得 WAV/MP3，保留 1 天需转存

## 功能2·声音设计（描述词生成声音并合成）
POST {BASE}/api/v1/dubbing  (JSON)
- text (必填): 按字符扣费，引擎限制约 330 汉字（1000 字节）
- design_prompt (必填): 声音描述词，≤200 字，如"温柔知性的年轻女声，语速平缓"
返回 data 同功能1

## 功能3·创建声音模型（上传录音克隆音色）
POST {BASE}/api/v1/model/create  (multipart/form-data)
- name (必填): 音色名称 ≤32 字
- category (必填): 男声/女声/童声/其他
- language (可选): 默认 中文
- description (可选): ≤100 字
- sample (必填): 录音文件，MP3/WAV/M4A，3-60 秒清晰人声，≤20MB
返回 data: {model_code, name, id}，model_code 立即可用于功能1。创建不扣费。

## Python 示例（先查音色再合成）
import requests
# 1. 查询可用音色
r = requests.get("https://tts.yirenbang.cc/api/v1/models",
    params={"api_key": "...", "api_secret": "..."}, timeout=10).json()
assert r["code"] == 0, r["msg"]
voice = r["data"]["system_voices"][0]["model_code"]  # 取第一个系统音色
# 2. 发起合成
r = requests.post("https://tts.yirenbang.cc/api/v1/tts", json={
    "api_key": "...", "api_secret": "...",
    "model_code": voice,
    "text": "你好，欢迎使用 OnePesr。",
    "emotion_ext": {"happy": 0.8},
}, timeout=90).json()
assert r["code"] == 0, r["msg"]
audio = requests.get(r["data"]["audio_url"], timeout=30).content
open("output.wav", "wb").write(audio)

1. 接入准备

基础地址：https://tts.yirenbang.cc

在密钥管理创建 API Key + Secret，每个请求携带这两个凭证。所有接口统一返回 {"code":0,"msg":"...","data":{...}}， code=0 表示成功，非 0 表示失败，msg 为可读错误信息。

{
  "api_key": "op-xxxxxxxxxxxxxxxxxxxxxxxx",
  "api_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

2. 查询可用声音模型

GET /api/v1/models?api_key=xx&api_secret=xx 免费 · 不扣费

查询当前 API 密钥用户可用的全部声音模型，包括系统音色（AI 音色库）和用户自己创建的音色。合成前建议先调用此接口获取音色编码，再传入 model_code 发起合成。

curl "https://tts.yirenbang.cc/api/v1/models?api_key=op-xxxxxxxx&api_secret=xxxxxxxx"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "system_voices": [
      {
        "model_code": "sys_f_xiaolin",
        "name": "晓琳",
        "category": "女声",
        "gender": "女",
        "language": "中文",
        "description": "温柔知性的年轻女声",
        "type": "system"
      }
    ],
    "my_voices": [
      {
        "model_code": "usr_3_1792007397",
        "name": "我的声音",
        "category": "男声",
        "gender": "未知",
        "language": "中文",
        "description": "日常说话的声音",
        "type": "custom"
      }
    ],
    "total": 34
  }
}

字段	说明
`system_voices`	系统音色列表（33 个，AI 音色库，所有用户共享）
`my_voices`	当前用户自己创建的音色列表（通过「创建声音模型」接口）
`model_code`	音色编码，合成时传入此值。系统音色 `sys_` 开头，用户音色 `usr_` 开头

3. 声音克隆（指定音色合成）

POST /api/v1/tts 按字符扣费 · 失败自动全额返还

参数	类型	必填	说明
`api_key`	string	是	API Key
`api_secret`	string	是	API Secret
`text`	string	是	待合成文本，最长 5000 字符（1 汉字/字母/标点 = 1 额度）
`model_code`	string	是	音色编码。系统音色在「AI音色库」卡片上查看（🔑 开头）；我的模型编码在「声音克隆」弹窗中查看
`speed`	number	否	语速 0.5–2.0，默认 1.0
`emotion_ext`	object	否	语气向量，见下方「语气控制」。仅普通话/多语言音色生效，方言音色自动忽略

curl -X POST https://tts.yirenbang.cc/api/v1/tts \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "op-xxxxxxxx",
    "api_secret": "xxxxxxxx",
    "model_code": "sys_f_xiaotian",
    "text": "你好，欢迎使用 OnePesr 语音合成。",
    "speed": 1.0,
    "emotion_ext": { "happy": 0.8 }
  }'

{
  "code": 0,
  "msg": "合成成功",
  "data": {
    "task_no": "T20261015103012345",
    "audio_url": "https://tts.yirenbang.cc/api/v1/audio?task_no=T20261015103012345&api_key=op-xxxx&api_secret=xxxx",
    "chars_used": 17
  }
}

4. 声音设计（描述词生成声音）

POST /api/v1/dubbing 按字符扣费 · 失败自动全额返还

无需录音与音色编码：用一句描述词告诉 AI 想要的声音（性别/年龄/质感/语速/情绪/场景），同时给出朗读文本即可直接合成。

参数	类型	必填	说明
`api_key`	string	是	API Key
`api_secret`	string	是	API Secret
`text`	string	是	朗读文本，按字符扣费；引擎限制 1000 字节（约 330 汉字），超长请切分
`design_prompt`	string	是	声音描述词，最长 200 字，越具体效果越好

curl -X POST https://tts.yirenbang.cc/api/v1/dubbing \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "op-xxxxxxxx",
    "api_secret": "xxxxxxxx",
    "design_prompt": "温柔知性的年轻女声，语速平缓，像深夜电台主播",
    "text": "夜深了，愿你有个好梦。"
  }'

{
  "code": 0,
  "msg": "合成成功",
  "data": {
    "task_no": "T20261015104206789",
    "audio_url": "https://tts.yirenbang.cc/api/v1/audio?task_no=T20261015104206789&api_key=op-xxxx&api_secret=xxxx",
    "chars_used": 12
  }
}

5. 创建声音模型（上传录音克隆音色）

POST /api/v1/model/create multipart/form-data · 创建不扣费

上传 3–60 秒清晰人声样本（推荐 3–10 秒干声），即可注册专属音色，返回的 model_code 立即可用于「声音克隆」接口。

参数	类型	必填	说明
`api_key`	string	是	API Key（form 字段）
`api_secret`	string	是	API Secret（form 字段）
`name`	string	是	音色名称，最长 32 字
`category`	string	是	分类：男声 / 女声 / 童声 / 其他
`language`	string	否	语言，默认「中文」
`description`	string	否	音色描述，最长 100 字
`sample`	file	是	录音文件，MP3 / WAV / M4A，3–60 秒，≤ 20MB；需本人或已获授权的声音

curl -X POST https://tts.yirenbang.cc/api/v1/model/create \
  -F "api_key=op-xxxxxxxx" \
  -F "api_secret=xxxxxxxx" \
  -F "name=我的声音" \
  -F "category=女声" \
  -F "language=中文" \
  -F "description=日常说话的声音" \
  -F "sample=@/path/to/recording.wav"

{
  "code": 0,
  "msg": "音色创建成功，已可立即用于合成",
  "data": {
    "model_code": "usr_3_1792007397",
    "name": "我的声音",
    "id": 35
  }
}

6. 语气控制（emotion_ext）

8 维情绪向量，各维度取值 0–1，可多维叠加，最多同时生效 3 项（超出时保留数值最高的 3 项）。不传或全 0 时，语气跟随参考音频本身。

维度	含义	维度	含义
`happy`	开心	`calm`	平静
`sad`	悲伤	`melancholic`	忧郁
`angry`	愤怒	`afraid`	恐惧
`surprised`	惊讶	`disgusted`	厌恶

"emotion_ext": { "happy": 0.7, "surprised": 0.5, "calm": 0.2 }

7. 音频获取

GET/api/v1/audio?task_no=xx&api_key=xx&api_secret=xx 直接返回音频二进制流（WAV/MP3）

合成响应中的 audio_url 即此接口的完整地址。仅可获取本密钥所属账号的任务音频；音频保留 1 天，请及时转存。每次调用都会记录到「密钥管理 - 消耗记录」中（含耗时与扣费）。

8. 错误码说明

HTTP 状态码	含义	处理建议
200	成功（code=0）	—
400	参数错误或音色不可用	检查必填参数、model_code 与文本长度
401	密钥无效 / 已停用 / 账号不可用	核对 api_key 与 api_secret，检查密钥状态
402	额度不足	前往「VIP 与额度」充值或兑换 CDKEY
500	合成失败	额度已自动全额返还，可稍后重试

⚠️ 合成为同步阻塞返回，耗时约 5–30 秒，请将 HTTP 客户端超时设置为 60 秒以上。失败不扣费（已扣额度自动返还）。