使用原生 SDK 将 Sambert 模型的实时文本转语音功能集成到 Android 应用中。

Sambert Android SDK 为 Android 应用提供原生实时语音合成能力。它通过 WebSocket 连接在合成过程中流式传输音频数据。

快速开始

获取 API Key

获取 API Key 并将其配置为环境变量以确保安全。为第三方应用或用户提供临时访问权限，或需要对敏感操作进行严格控制时，使用临时 API Key。临时 API Key 默认 60 秒后过期。

下载 SDK 并运行示例

下载最新 SDK 包。解压后，在 app/libs 目录下找到 AAR 格式的 SDK 并添加到项目依赖中。如需在 Android C++ 工程中集成，可使用压缩包中的 android_libs 和 android_include 获取动态库和头文件。在 Android Studio 中打开项目，示例代码位于 DashSambertTtsActivity.java。替换 API Key 后运行示例即可体验功能。

初始化 SDK

调用 tts_initialize，在 ticket JSON 字符串中传入连接参数。

设置合成参数

通过 tts_initialize 的 ticket 参数设置连接与控制参数，通过 setparamTts 设置语音合成效果参数。

开始合成

调用 startTts 开始语音合成，结果通过回调返回。

接收音频数据

在 onTtsDataCallback 回调中接收音频数据。建议流式播放，如需本地保存，将音频数据追加到同一文件中直至合成结束。

释放资源

任务结束后调用 tts_release 释放 SDK 资源。

请求参数

连接与控制参数

将这些参数以 JSON 字符串形式传入 tts_initialize 的 ticket 参数。

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "mode_type": "2",
    "device_id": "my_device_id"
}

参数	类型	是否必填	描述
`url`	String	是	服务地址，固定为 `wss://dashscope.aliyuncs.com/api-ws/v1/inference`。
`apikey`	String	是	API Key。建议使用短效临时 API Key以降低长期密钥泄露风险。
`mode_type`	String	是	模式类型，语音合成在线模式固定为字符串 `"2"`。
`device_id`	String	是	唯一标识终端用户的字符串，如应用内用户 ID 或客户端生成的设备标识。用于日志追踪和问题排查。
`debug_path`	String	否	日志文件存储路径。仅在 `tts_initialize` 中 `save_log` 设置为 `true` 时生效。开启时必须设置该路径否则会报错。本地最多保留两个日志文件。
`max_log_file_size`	int	否	单个日志文件最大大小（字节）。仅在 `save_log` 为 `true` 时生效。默认值 `104857600`（100 MiB）。
`log_track_level`	int	否	过滤通过 `onTtsLogTrackCallback` 回调发送的日志内容。默认值 `2`。取值：`0` = VERBOSE，`1` = DEBUG，`2` = INFO，`3` = WARNING，`4` = ERROR，`5` = NONE（关闭回调）。日志条目仅在级别同时大于等于 `log_track_level` 和 `tts_initialize` 中设置的 `level` 时才会发送。

语音合成效果参数

在调用 startTts 之前通过 setparamTts 设置这些参数。

参数	类型	是否必填	描述
`model`	String	是	语音合成模型，参见下方模型列表。
`format`	String	否	音频编码格式，支持 `pcm`、`wav`、`mp3`。默认值 `pcm`。
`volume`	String	否	音量大小。默认值 `50`，取值范围 `[0, 100]`。音量与该值呈线性关系，`0` 为静音，`100` 为最大音量。
`sample_rate`	String	否	采样率（Hz）。默认值为模型默认采样率。建议使用模型默认值，若不匹配服务端会进行重采样。
`rate`	String	否	语速。默认值 `1.0`，取值范围 `[0.5, 2.0]`。小于 `1.0` 减慢，大于 `1.0` 加快。
`pitch`	String	否	音调倍数。默认值 `1.0`，取值范围 `[0.5, 2.0]`。大于 `1.0` 升高音调，小于 `1.0` 降低音调。与感知音调的关系并非严格线性，建议测试找到合适的值。
`word_timestamp_enabled`	String	否	是否开启词级别时间戳。默认值 `0`。取值：`1` = 开启，`0` = 关闭。
`phoneme_timestamp_enabled`	String	否	是否开启音素级别时间戳。仅在 `word_timestamp_enabled` 为 `1` 时生效。默认值 `0`。取值：`1` = 开启，`0` = 关闭。
`enable_audio_decoder`	String	否	是否开启内置音频解码器。默认值 `0`。当 `format` 为 `mp3` 时，设置为 `"1"` 可启用 SDK 内置解码器，`onTtsDataCallback` 将返回解码后的 PCM 数据。

核心接口

NativeNui

tts_initialize

初始化语音合成 SDK 实例。SDK 为单例模式，在调用 tts_release 之前不要重复调用 tts_initialize。

该方法会阻塞调用线程，请在非 UI 线程中调用。

方法签名

public synchronized int tts_initialize(INativeTtsCallback callback,
                                       String ticket,
                                       final Constants.LogLevel level,
                                       boolean save_log)

参数

参数	类型	描述
`callback`	INativeTtsCallback	事件和数据回调接口的实现。
`ticket`	String	JSON 字符串，包含认证、连接和调试参数。参见连接与控制参数。
`level`	Constants.LogLevel	控制 SDK 内部日志级别。
`save_log`	boolean	是否保存本地日志。若为 `true`，需在连接参数中设置 `debug_path`，可选设置 `max_log_file_size`。

返回值 返回错误码，参见错误码参考。

setparamTts

以键值对形式设置语音合成效果参数。在 startTts 之前调用。 方法签名

public synchronized int setparamTts(String param, String value)

参数

参数	类型	描述
`param`	String	语音合成效果参数名称。
`value`	String	语音合成效果参数值。

返回值 返回错误码，参见错误码参考。

getparamTts

获取参数值。主要用于问题排查。 方法签名

public String getparamTts(String param);

参数

参数	类型	描述
`param`	String	参数名称，当前仅支持 `"error_msg"`。

返回值 返回参数值。

startTts

启动语音合成任务，结果通过回调返回。 方法签名

获取输入项列表POST
Anthropic 兼容
POST
DashScope

OpenAI Responses

创建响应

兼容 Responses API

POST

/compatible-mode/v1/responses

import os
from openai import OpenAI

client = OpenAI(
  # 若未设置环境变量，请替换为：api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
  model="qwen3.7-plus",
  input="What can you do?"
)

# 获取模型回复
print(response.output_text)

{
  "created_at": 1771165900,
  "id": "f75c28fb-4064-48ed-90da-4d2cc4362xxx",
  "model": "qwen3.7-plus",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "text": "Hello! I am Qwen3.5, a large language model developed by Alibaba Cloud with knowledge up to 2026, designed to assist you with complex reasoning, creative tasks, and multilingual conversations.",
          "type": "output_text"
        }
      ],
      "id": "msg_89ad23e6-f128-4d4c-b7a1-a786e7880xxx",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": false,
  "status": "completed",
  "tool_choice": "auto",
  "tools": [],
  "usage"public synchronized int startTts(String priority, String taskid, String text)


参数
参数 类型 描述
priority String 任务优先级，固定为 1。
taskid String 任务 ID，传 null 由 SDK 自动生成。
text String 待合成的文本。
返回值
返回错误码，参见错误码参考。

pauseTts
暂停当前语音合成任务。暂停后可通过 resumeTts 恢复或通过 cancelTts 取消。暂停状态下无法启动新的合成任务。
该操作仅暂停从服务端获取数据，播放器已缓冲的音频数据会继续播放。
方法签名
复制
public synchronized int pauseTts()

返回值
返回错误码，参见错误码参考。

resumeTts
恢复已暂停的语音合成任务。
方法签名
复制
public synchronized int resumeTts()

返回值
返回错误码，参见错误码参考。

cancelTts
取消合成任务。
该操作仅取消从服务端获取数据，播放器已缓冲的音频数据会继续播放。
方法签名
复制
public synchronized int cancelTts(String taskid)

参数
参数 类型 描述
taskid String 要取消的任务 ID，传 null 取消所有暂停或进行中的任务。
返回值
返回错误码，参见错误码参考。

tts_release
释放 SDK 内部所有资源并强制终止所有进行中的合成任务。调用后 SDK 实例不可再用，如需继续使用需重新调用 tts_initialize。
方法签名
复制
public synchronized int tts_release()

返回值
返回错误码，参见错误码参考。

INativeTtsCallback
onTtsEventCallback
合成生命周期事件回调。
方法签名
复制
void onTtsEventCallback(TtsEvent event, String task_id, int ret_code);

参数
参数 类型 描述
event TtsEvent 回调事件，参见下方TtsEvent。
task_id String 语音合成任务 ID。
ret_code int 错误码，仅当事件为 TTS_EVENT_ERROR 时有效。参见错误码参考。

onTtsDataCallback
音频数据和时间戳信息回调。
方法签名
复制
void onTtsDataCallback(String info, int info_len, byte[] data);

参数
参数 类型 描述
info String JSON 格式的时间戳结果。仅在 word_timestamp_enabled 设置为 "1" 时有值。
info_len int info 字段长度，可忽略。
data byte[] 当前片段的音频数据。

onTtsLogTrackCallback
SDK 内部追踪日志回调，用于问题排查和调试。
方法签名
复制
default void onTtsLogTrackCallback(Constants.LogLevel level, String log)


TtsEvent
事件 描述
TTS_EVENT_START 合成任务已开始，即将返回音频数据。
TTS_EVENT_END 合成任务正常完成，所有音频数据已通过回调发送。
TTS_EVENT_CANCEL 合成任务已取消。
TTS_EVENT_PAUSE 合成任务已暂停。
TTS_EVENT_RESUME 合成任务已恢复。
TTS_EVENT_ERROR 合成过程中发生错误。可通过 getparamTts("error_msg") 获取详情。错误响应结构如下：
复制
{
  "header": {
    "task_id": "xxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "Please ensure input text is valid.",
    "attributes": {}
  },
  "payload": {}
}

模型列表
默认采样率代表各模型的最优采样率，输出默认为该采样率。支持降采样，但升采样不会提升音质。以知妙为例，默认 16 kHz，可降至 8 kHz，但升至 48 kHz 不会带来额外收益。
音色 模型 时间戳 适用场景 角色 支持语言 默认采样率（Hz）
知楠 sambert-zhinan-v1 支持 通用 阳光男 中文+英文 48k
知琪 sambert-zhiqi-v1 支持 通用 温柔女 中文+英文 48k
知厨 sambert-zhichu-v1 支持 新闻播报 厨艺男 中文+英文 48k
知德 sambert-zhide-v1 支持 新闻播报 新闻男 中文+英文 48k
知佳 sambert-zhijia-v1 支持 新闻播报 标准女 中文+英文 48k
知茹 sambert-zhiru-v1 支持 新闻播报 新闻女 中文+英文 48k
知倩 sambert-zhiqian-v1 支持 资讯播报、新闻 资讯女 中文+英文 48k
知祥 sambert-zhixiang-v1 支持 有声阅读 磁性男 中文+英文 48k
知薇 sambert-zhiwei-v1 支持 商品讲解 萝莉女 中文+英文 48k
知浩 sambert-zhihao-v1 支持 通用 资讯男 中文+英文 16k
知婧 sambert-zhijing-v1 支持 通用 严厉女 中文+英文 16k
知茗 sambert-zhiming-v1 支持 通用 幽默男 中文+英文 16k
知墨 sambert-zhimo-v1 支持 通用 情感男 中文+英文 16k
知娜 sambert-zhina-v1 支持 通用 浙江口音女 中文+英文 16k
知树 sambert-zhishu-v1 支持 通用 资讯男 中文+英文 16k
知莎 sambert-zhistella-v1 支持 通用 知性女 中文+英文 16k
知婷 sambert-zhiting-v1 支持 通用 电台女 中文+英文 16k
知笑 sambert-zhixiao-v1 支持 通用 资讯女 中文+英文 16k
知雅 sambert-zhiya-v1 支持 通用 严厉女 中文+英文 16k
知晔 sambert-zhiye-v1 支持 通用 青年男 中文+英文 16k
知颖 sambert-zhiying-v1 支持 通用 可爱童声 中文+英文 16k
知媛 sambert-zhiyuan-v1 支持 通用 关怀女 中文+英文 16k
知悦 sambert-zhiyue-v1 支持 客服 温柔女 中文+英文 16k
知柜 sambert-zhigui-v1 支持 商品讲解 直播女 中文+英文 16k
知硕 sambert-zhishuo-v1 支持 数字人 自然男 中文+英文 16k
知妙（多情感） sambert-zhimiao-emo-v1 支持 商品讲解、数字人、直播 多情感女 中文+英文 16k
知猫 sambert-zhimao-v1 支持 商品讲解、有声阅读、数字人、直播 直播女 中文+英文 16k
知伦 sambert-zhilun-v1 支持 有声阅读 悬疑解说 中文+英文 16k
知飞 sambert-zhifei-v1 支持 有声阅读 激情解说 中文+英文 16k
知达 sambert-zhida-v1 支持 新闻播报 标准男 中文+英文 16k
Camila sambert-camila-v1 不支持 通用 西班牙语女 西班牙语 16k
Perla sambert-perla-v1 不支持 通用 意大利语女 意大利语 16k
Indah sambert-indah-v1 不支持 通用 印尼语女 印尼语 16k
Clara sambert-clara-v1 不支持 通用 法语女 法语 16k
Hanna sambert-hanna-v1 不支持 通用 德语女 德语 16k
Beth sambert-beth-v1 支持 通用 资讯女 美式英语 16k
Betty sambert-betty-v1 支持 通用 客服女 美式英语 16k
Cally sambert-cally-v1 支持 通用 自然女 美式英语 16k
Cindy sambert-cindy-v1 支持 通用 对话女 美式英语 16k
Eva sambert-eva-v1 支持 通用 陪伴女 美式英语 16k
Donna sambert-donna-v1 支持 通用 教育女 美式英语 16k
Brian sambert-brian-v1 支持 通用 客服男 美式英语 16k
Waan sambert-waan-v1 不支持 通用 泰语女 泰语 16k

参数	类型	描述
`priority`	String	任务优先级，固定为 `1`。
`taskid`	String	任务 ID，传 `null` 由 SDK 自动生成。
`text`	String	待合成的文本。

参数	类型	描述
`taskid`	String	要取消的任务 ID，传 `null` 取消所有暂停或进行中的任务。

参数	类型	描述
`event`	TtsEvent	回调事件，参见下方TtsEvent。
`task_id`	String	语音合成任务 ID。
`ret_code`	int	错误码，仅当事件为 `TTS_EVENT_ERROR` 时有效。参见错误码参考。

参数	类型	描述
`info`	String	JSON 格式的时间戳结果。仅在 `word_timestamp_enabled` 设置为 `"1"` 时有值。
`info_len`	int	`info` 字段长度，可忽略。
`data`	byte[]	当前片段的音频数据。

事件	描述
`TTS_EVENT_START`	合成任务已开始，即将返回音频数据。
`TTS_EVENT_END`	合成任务正常完成，所有音频数据已通过回调发送。
`TTS_EVENT_CANCEL`	合成任务已取消。
`TTS_EVENT_PAUSE`	合成任务已暂停。
`TTS_EVENT_RESUME`	合成任务已恢复。
`TTS_EVENT_ERROR`	合成过程中发生错误。可通过 `getparamTts("error_msg")` 获取详情。错误响应结构如下：

音色	模型	时间戳	适用场景	角色	支持语言	默认采样率（Hz）
知楠	sambert-zhinan-v1	支持	通用	阳光男	中文+英文	48k
知琪	sambert-zhiqi-v1	支持	通用	温柔女	中文+英文	48k
知厨	sambert-zhichu-v1	支持	新闻播报	厨艺男	中文+英文	48k
知德	sambert-zhide-v1	支持	新闻播报	新闻男	中文+英文	48k
知佳	sambert-zhijia-v1	支持	新闻播报	标准女	中文+英文	48k
知茹	sambert-zhiru-v1	支持	新闻播报	新闻女	中文+英文	48k
知倩	sambert-zhiqian-v1	支持	资讯播报、新闻	资讯女	中文+英文	48k
知祥	sambert-zhixiang-v1	支持	有声阅读	磁性男	中文+英文	48k
知薇	sambert-zhiwei-v1	支持	商品讲解	萝莉女	中文+英文	48k
知浩	sambert-zhihao-v1	支持	通用	资讯男	中文+英文	16k
知婧	sambert-zhijing-v1	支持	通用	严厉女	中文+英文	16k
知茗	sambert-zhiming-v1	支持	通用	幽默男	中文+英文	16k
知墨	sambert-zhimo-v1	支持	通用	情感男	中文+英文	16k
知娜	sambert-zhina-v1	支持	通用	浙江口音女	中文+英文	16k
知树	sambert-zhishu-v1	支持	通用	资讯男	中文+英文	16k
知莎	sambert-zhistella-v1	支持	通用	知性女	中文+英文	16k
知婷	sambert-zhiting-v1	支持	通用	电台女	中文+英文	16k
知笑	sambert-zhixiao-v1	支持	通用	资讯女	中文+英文	16k
知雅	sambert-zhiya-v1	支持	通用	严厉女	中文+英文	16k
知晔	sambert-zhiye-v1	支持	通用	青年男	中文+英文	16k
知颖	sambert-zhiying-v1	支持	通用	可爱童声	中文+英文	16k
知媛	sambert-zhiyuan-v1	支持	通用	关怀女	中文+英文	16k
知悦	sambert-zhiyue-v1	支持	客服	温柔女	中文+英文	16k
知柜	sambert-zhigui-v1	支持	商品讲解	直播女	中文+英文	16k
知硕	sambert-zhishuo-v1	支持	数字人	自然男	中文+英文	16k
知妙（多情感）	sambert-zhimiao-emo-v1	支持	商品讲解、数字人、直播	多情感女	中文+英文	16k
知猫	sambert-zhimao-v1	支持	商品讲解、有声阅读、数字人、直播	直播女	中文+英文	16k
知伦	sambert-zhilun-v1	支持	有声阅读	悬疑解说	中文+英文	16k
知飞	sambert-zhifei-v1	支持	有声阅读	激情解说	中文+英文	16k
知达	sambert-zhida-v1	支持	新闻播报	标准男	中文+英文	16k
Camila	sambert-camila-v1	不支持	通用	西班牙语女	西班牙语	16k
Perla	sambert-perla-v1	不支持	通用	意大利语女	意大利语	16k
Indah	sambert-indah-v1	不支持	通用	印尼语女	印尼语	16k
Clara	sambert-clara-v1	不支持	通用	法语女	法语	16k
Hanna	sambert-hanna-v1	不支持	通用	德语女	德语	16k
Beth	sambert-beth-v1	支持	通用	资讯女	美式英语	16k
Betty	sambert-betty-v1	支持	通用	客服女	美式英语	16k
Cally	sambert-cally-v1	支持	通用	自然女	美式英语	16k
Cindy	sambert-cindy-v1	支持	通用	对话女	美式英语	16k
Eva	sambert-eva-v1	支持	通用	陪伴女	美式英语	16k
Donna	sambert-donna-v1	支持	通用	教育女	美式英语	16k
Brian	sambert-brian-v1	支持	通用	客服男	美式英语	16k
Waan	sambert-waan-v1	不支持	通用	泰语女	泰语	16k

上一页语音合成 Sambert iOS SDK
使用 Sambert iOS SDK 将文本实时合成为高质量语音，支持流式音频输出与字/音素级时间戳
下一页

本页目录

快速开始
请求参数
连接与控制参数
语音合成效果参数
核心接口
NativeNui
INativeTtsCallback
TtsEvent
模型列表

​快速开始

​请求参数

​连接与控制参数

​语音合成效果参数

​核心接口

​NativeNui

​tts_initialize

​setparamTts

​getparamTts

​startTts

​pauseTts

​resumeTts

​cancelTts

​tts_release

​INativeTtsCallback

​onTtsEventCallback

​onTtsDataCallback

​onTtsLogTrackCallback

​TtsEvent

​模型列表

快速开始

请求参数

连接与控制参数

语音合成效果参数

核心接口

NativeNui

tts_initialize

setparamTts

getparamTts

startTts

pauseTts

resumeTts

cancelTts

tts_release

INativeTtsCallback

onTtsEventCallback

onTtsDataCallback

onTtsLogTrackCallback

TtsEvent

模型列表