TTS API 异步生成文档

基本信息

Base URL: https://tts-api.dubbingx.com/
请求方法: 本文档所有请求均为 POST
异步结果获取方式:
- 轮询查询：调用获取合成状态
- Webhook 回调：先调用设置 Webhook 回调地址
公共请求头:
参数值
Authorization Bearer apiKey
Content-Type application/json
apiKey 为用户的 API Key，可在客户端中生成。
api_secret 为当前 API Key 对应的签名密钥，Webhook 回调会使用该密钥进行 HMAC-SHA256 签名。

参数	值
Authorization	Bearer apiKey
Content-Type	application/json

音色相关

1-1. 获取音色列表

接口地址: /v2/getTTSTimbreList
请求说明: 获取官方或自训练音色列表，可筛选、分页、搜索。

请求参数:

字段	备注
pageIndex	页码
pageSize	每页数量
isMyModel	是否为自训练模型，不传返回官方音色
keyword	关键字搜索（名称/介绍均可）
grade	`premium` 全情绪；`ordinary` 单情绪； `custom` 多情绪；不传全部
gender	0 女；1 男；不传全选
ageGroup	孩童、少年、青年、中年、老年；不传全部

请求示例:

json

{
  "pageIndex": 1,
  "pageSize": 100,
  "grade": "premium",
  "gender": 1,
  "ageGroup": "老年",
  "keyword": "李"
}

返回字段说明:

字段	备注
id	音色ID
grade	premium/ordinary/custom
gender	0女；1男
voiceUrl	试听音频
...	其它字段见返回示例

返回示例:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": {
    "total": 1,
    "list": [
      {
        "id": "30002",
        "grade": "premium",
        "isOfficial": true,
        "version": "V3", 
        "name": "智吾褚",
        "description": "中青年  稳重   温暖",
        "gender": 1,
        "avatar": "https://public.dubbingx.com/avatar/10092/20240329-143217.png",
        "voiceUrl": "https://public.dubbingx.com/audition/10092/mujin.wav",
        "status": true,
        "createTime": "2023-11-03 18:24:12"
      }
    ]
  }
}

1-2. 获取情绪列表

接口地址: /v1/getEmotionList/{timbre_id}
请求说明: 根据音色ID获取该音色支持的情绪列表

请求参数:

字段	备注
timbre_id	音色ID，通过URL路径传递

返回字段说明:

字段	备注
type	情绪类型（如常规、开心、恐惧等）
aura	该类型下的具体情绪风格列表

情绪格式说明:

全情绪音色: 需进行档位拼接，格式为 类型-风格-档位，如 常规-日常说话-3
多情绪音色: 不支持档位拼接，直接使用风格名称，如 自定义情绪-常规默认
单情绪音色: 不支持档位拼接，直接使用 单情绪

返回示例（全情绪音色）:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": [
    {
      "type": {
        "zh": "常规"
      },
      "aura": [
        {
          "zh": "日常说话"
        }
      ]
    }
  ],
  "time": "2025-08-26 18:11:32",
  "traceId": "1960283964965720065"
}

返回示例（多情绪音色）:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": [
    {
      "type": {
        "zh": "自定义情绪"
      },
      "aura": [
        {
          "zh": "常规默认"
        }
      ]
    }
  ],
  "time": "2025-08-26 18:14:37",
  "traceId": "1960284740412837889"
}

返回示例（单情绪音色）:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": [
    {
      "type": {
        "zh": "普通"
      },
      "aura": [
        {
          "zh": "单情绪"
        }
      ]
    }
  ],
  "time": "2025-08-26 18:14:49",
  "traceId": "1960284792715808770"
}

文本处理（可选）

2-1. 根据文本分析情绪并返回（可选）

接口地址: /v2/analyzeEmotion
功能: 分析指定文本的情绪，返回全情绪格式的情绪类型与档位。

请求参数:

字段	备注
text	待分析文本

请求示例:

json

{
  "text": "今天天气真好！！"
}

返回字段说明:

字段	备注
data	全情绪格式：情绪类型-风格-档位;默认三挡

返回示例:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": "开心-正常-3"
}

2-2. 给文本自动添加停顿（可选）

接口地址: /v2/autoPause
功能: 让文本停顿更自然，自动插入 <break /> 标签。

请求参数:

字段	备注
text	待处理文本

请求示例:

json

{
  "text": "在遥远的东方，有一座被云雾环绕的古老山脉，山脉中隐匿着一个神秘的修仙门派。这里的修士们以“天命”为引导，修炼各种奇妙的法术，旨在突破人类的极限，踏入仙界。！！"
}

返回字段说明:

字段	备注
data	包含停顿的文本字符串

返回示例:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": "在遥远的东方<break time=\"0.3\"/>，有一座被云雾环绕的古老山脉<break time=\"0.4\"/>，山脉中隐匿着一个神秘的修仙门派<break time=\"0.5\"/>。这里的修士们以“天命”为引导<break time=\"0.3\"/>，修炼各种奇妙的法术<break time=\"0.4\"/>，旨在突破人类的极限<break time=\"0.4\"/>，踏入仙界<break time=\"0.5\"/>。"
}

Webhook 配置与回调

3-1. 设置 Webhook 回调地址

接口地址: /v1/setWebhookUrl
功能: 为当前 Authorization 里的 API Key 设置或清空异步回调地址。

请求参数:

字段	备注
callbackUrl	Webhook 回调地址，必须是公网可访问的 `http/https` 地址；传空字符串表示清空

请求示例（设置）:

json

{
  "callbackUrl": "https://api.example.com/tts/webhook"
}

请求示例（清空）:

json

{
  "callbackUrl": ""
}

返回示例:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": {
    "callbackUrl": "https://api.example.com/tts/webhook"
  }
}

使用说明:

同一个 API Key 只保存一条 callbackUrl
不支持 localhost、127.0.0.1、内网 IP 等不可公网访问地址
若未设置 callbackUrl，请继续使用轮询接口查询任务结果

3-2. Webhook 回调说明

触发时机: 任务进入终态时触发，即 Completed、Failed、Canceled
回调方法: POST
请求头:
请求头说明
Content-Type application/json
X-DubbingX-Signature 签名结果，格式为 sha256=<hex>

请求头	说明
Content-Type	`application/json`
X-DubbingX-Signature	签名结果，格式为 `sha256=<hex>`

签名规则:

签名算法：HMAC-SHA256
签名密钥：当前 API Key 对应的 api_secret
签名原文使用固定字段、固定顺序拼接，格式如下：

text

taskId={taskId}
status={status}
fileUrl={fileUrl}
timestamp={timestamp}

规则说明：
- 字段顺序固定为 taskId、status、fileUrl、timestamp
- 每一行格式固定为 字段名=字段值
- 行与行之间使用换行符 \n 连接
- 若字段值为空或为 null，按空字符串参与签名，不省略该行

签名示例（成功）:

text

taskId=2044301252740694017
status=Completed
fileUrl=https://example.com/file.wav
timestamp=1776234376922

签名示例（空值）:

text

taskId=2044301252740694017
status=Failed
fileUrl=
timestamp=1776234376922

回调接收方建议按 taskId 做幂等处理
若未收到回调或需要兜底，请调用查询接口获取任务状态

回调字段说明:

字段	说明
event	事件名：`task.completed` / `task.failed` / `task.canceled`
taskId	任务 ID
status	任务状态
taskType	固定为 `tts`
fileName	输出文件名
fileUrl	文件下载地址；若文件尚不可签名或无产物，可能为 `null`
errorMessage	失败原因；成功时为 `null`
timestamp	回调发送时间戳（毫秒）
updateTime	任务最终更新时间

回调示例:

json

{
  "event": "task.completed",
  "taskId": "2044301252740694017",
  "status": "Completed",
  "taskType": "tts",
  "fileName": "2044301252740694017.wav",
  "fileUrl": "https://example.com/file.wav",
  "errorMessage": null,
  "timestamp": 1776234376922,
  "updateTime": "2026-04-15 14:26:16"
}

验签示例（Node.js）:

import crypto from "crypto";

function buildSignatureContent(payload) {
  return [
    `taskId=${payload?.taskId ?? ""}`,
    `status=${payload?.status ?? ""}`,
    `fileUrl=${payload?.fileUrl ?? ""}`,
    `timestamp=${payload?.timestamp ?? ""}`,
  ].join("\n");
}

function verifySignature(payload, apiSecret, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", apiSecret)
    .update(buildSignatureContent(payload), "utf8")
    .digest("hex");
  const actual = signatureHeader || "";
  if (expected.length !== actual.length) {
    return false;
  }
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(actual));
}

验签示例（Python）:

python

import hashlib
import hmac


def build_signature_content(payload: dict) -> str:
    return "\n".join([
        f"taskId={payload.get('taskId') or ''}",
        f"status={payload.get('status') or ''}",
        f"fileUrl={payload.get('fileUrl') or ''}",
        f"timestamp={payload.get('timestamp') or ''}",
    ])


def verify_signature(payload: dict, api_secret: str, signature_header: str | None) -> bool:
    expected = "sha256=" + hmac.new(
        api_secret.encode("utf-8"),
        build_signature_content(payload).encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
    actual = signature_header or ""
    return hmac.compare_digest(expected, actual)

验签示例（Java）:

java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Map;

public class DubbingxWebhookVerifier {

    public static String buildSignatureContent(Map<String, Object> payload) {
        return String.join("\n",
                "taskId=" + valueOf(payload.get("taskId")),
                "status=" + valueOf(payload.get("status")),
                "fileUrl=" + valueOf(payload.get("fileUrl")),
                "timestamp=" + valueOf(payload.get("timestamp"))
        );
    }

    public static boolean verifySignature(Map<String, Object> payload, String apiSecret, String signatureHeader) throws Exception {
        String expected = "sha256=" + hmacSha256(buildSignatureContent(payload), apiSecret);
        String actual = signatureHeader == null ? "" : signatureHeader;
        return MessageDigest.isEqual(
                expected.getBytes(StandardCharsets.UTF_8),
                actual.getBytes(StandardCharsets.UTF_8)
        );
    }

    private static String hmacSha256(String content, String secret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] digest = mac.doFinal(content.getBytes(StandardCharsets.UTF_8));
        return HexFormat.of().formatHex(digest);
    }

    private static String valueOf(Object value) {
        return value == null ? "" : String.valueOf(value);
    }
}

TTS 任务操作

4-1. 发送TTS合成指令（异步返回结果）

V1 版本

接口地址: /v1/addTtsTask
结果获取:
- 已设置 callbackUrl 时，任务终态会通过 Webhook 回调
- 未设置 callbackUrl 或需要兜底时，请使用 4-2 获取合成状态查询任务结果

请求参数:

字段	备注
voiceId	音色ID，见"获取音色列表"
text	需要合成的文字，支持 `<phoneme>`、`<break>`
emotion	1-2 获取情绪列表获取的情绪进行拼接,比如: 常规-日常说话-3 ; 自定义情绪-时政新闻;（全情绪下可传空自动识别，单情绪可不传,自定义多情绪传空会无法生成）
emotionCustom	仅适用于 V4 版本模型。支持传入自然语言描述情绪，例如: "开心的"、"悲伤的"、"生气的" 等。使用此参数时可不传 emotion 参数
language	zh/jp/en/yue/sc/ko 中文/日语/英文/粤语/四川话/韩语（V4 版本模型目前仅支持 zh 和 en）
audioPitch	语调，1.0为原音高
audioSpeed	语速，1.0为原语速
audioVolume	音量增益，单位为 dB，范围: -12 到 +12
fileFormat	wav/mp3，默认wav

控制字段说明:

<phoneme>：音素标注，只支持中文，格式<phoneme ph="duan2">段</phoneme>
<break>：停顿标签，格式<break time='0.15'/>，最长20秒

请求示例:

json

{
  "voiceId": "30065",
  "emotion": "常规-日常说话-3",
  "language": "zh",
  "text": "你好，<break time=\"0.8\"'/>这是一<phoneme ph=\"duan2\">段</phoneme>测试音频！",
  "fileFormat": "mp3"
}

4-2. 获取合成状态

接口地址: /v1/getTtsTaskInfo/{taskId}
方法: POST
说明: 查询指定任务ID的合成进度及结果；未启用 Webhook 时建议使用该接口轮询

返回字段说明:

字段	说明
status	Ready（待合成）、Generating（合成中）、Completed（已完成）、Failed（失败）
fileUrl	合成完成后音频下载地址（status=Completed时）

返回示例:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": {
    "id": "1778319033905385473",
    "status": "Completed",
    "language": "zh",
    "fileName": "dce642383ca447b3ac4ed57cd3e5b2b4.wav",
    "fileUrl": "https://tts-bucket.dubbingx.com/10092/30002/dce642383ca447b3ac4ed57cd3e5b2b4.wav?Expires=1712849799&OSSAccessKeyId=LTAI5t8FMBqtNy467wQoCC3t&Signature=x7wCkhlQlCI8DPNdP8kLoPkvk0w%3D",
    "updateTime": "2024-04-11 15:07:59",
    "createTime": "2024-04-11 15:07:52"
  }
}

4-3. 批量获取合成状态

接口地址: /v1/getTtsTaskListInfo
请求参数: 传递 taskId 数组

请求示例:

json

["1778328789218971650","1778328790586314754","1778328790703755265","1778328790888304642"]

返回示例:

json

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": [
    {
      "id": "1778328789218971650",
      "status": "Completed",
      "language": "zh",
      "fileName": "61a74e1801ef4984ac0c911e815efaa1.wav",
      "fileUrl": "",
      "updateTime": "2024-04-11 15:46:43",
      "createTime": "2024-04-11 15:46:38"
    },
    ...
  ]
}

商务合作

如需商务洽谈、优惠领取，请联系：

📧 business@dubbingx.com

API文档

TTS API 异步生成文档

基本信息

目录

音色相关

1-1. 获取音色列表

1-2. 获取情绪列表

文本处理（可选）

2-1. 根据文本分析情绪并返回（可选）

2-2. 给文本自动添加停顿（可选）

Webhook 配置与回调

3-1. 设置 Webhook 回调地址

3-2. Webhook 回调说明

TTS 任务操作

4-1. 发送TTS合成指令（异步返回结果）

V1 版本

4-2. 获取合成状态

4-3. 批量获取合成状态

商务合作

TTS API 异步生成文档 ​

基本信息 ​

目录 ​

音色相关 ​

1-1. 获取音色列表 ​

1-2. 获取情绪列表 ​

文本处理（可选） ​

2-1. 根据文本分析情绪并返回（可选） ​

2-2. 给文本自动添加停顿（可选） ​

Webhook 配置与回调 ​

3-1. 设置 Webhook 回调地址 ​

3-2. Webhook 回调说明 ​

TTS 任务操作 ​

4-1. 发送TTS合成指令（异步返回结果） ​

V1 版本 ​

4-2. 获取合成状态 ​

4-3. 批量获取合成状态 ​

商务合作 ​

TTS API 异步生成文档

基本信息

目录

音色相关

1-1. 获取音色列表

1-2. 获取情绪列表

文本处理（可选）

2-1. 根据文本分析情绪并返回（可选）

2-2. 给文本自动添加停顿（可选）

Webhook 配置与回调

3-1. 设置 Webhook 回调地址

3-2. Webhook 回调说明

TTS 任务操作

4-1. 发送TTS合成指令（异步返回结果）

V1 版本

4-2. 获取合成状态

4-3. 批量获取合成状态

商务合作