功能描述
文字转语音和音色克隆是即时通信 IM SDK 提供的 AI 能力,主要包含以下功能:
完整文本转语音:将文本内容转换为语音音频文件,支持指定音色和音频格式。
流式文本实时转语音:对 IM 流式消息边生成文本、边合成语音,应用接收音频包后解码播放。
音色克隆:基于一段参考音频,克隆出自定义音色,后续可在 TTS 中使用。
自定义音色列表拉取:获取当前用户已克隆的所有自定义音色。
自定义音色删除:删除不再需要的克隆音色。
说明:
文字转语音及音色克隆是增值付费功能,目前正在内测阶段。试用需通过 工单开通申请。
音色克隆、自定义音色列表拉取和自定义音色删除功能在 8.9 及以上版本支持。
完整文本转换及音色管理通过
callExperimentalAPI 调用,参数格式见各平台示例;流式文本实时转语音 使用 startTTS / stopTTS,不经过该实验接口。完整文本转语音功能在 8.9 及以上版本支持;流式文本实时转语音 在 9.0.7667 及以上版本支持。
效果展示
文字转语音 | 音色克隆 |
![]() | ![]() |
接口说明
文字转语音(convertTextToVoice)
将文本内容转换为语音音频,返回音频文件的下载 URL。
请求参数:
参数 | 类型 | 必填 | 说明 |
text | String | 是 | 需要转语音的文字内容(长度 1-255)。 |
voiceId | String | 否 | TTS 音色 ID,可使用系统预置音色或克隆的自定义音色 ID。 |
audioFormat | String | 否 | 音频格式,支持 pcm、wav。 |
language | String | 否 | 语言代码(参考 ISO 639-1),如 zh、en 等。 |
返回参数:
参数 | 类型 | 说明 |
audioUrl | String | 生成的音频文件下载地址。 |
requestId | String | 唯一请求 ID。 |
示例代码:
public void convertTextToVoice(String text, String voiceId, String audioFormat) {try {JSONObject params = new JSONObject();params.put("text", text);// 选填参数if (voiceId != null && !voiceId.isEmpty()) {params.put("voiceId", voiceId);}if (audioFormat != null && !audioFormat.isEmpty()) {params.put("audioFormat", audioFormat);}String jsonString = params.toString();V2TIMManager.getInstance().callExperimentalAPI("convertTextToVoice",jsonString,new V2TIMValueCallback<Object>() {@Overridepublic void onSuccess(Object result) {if (result instanceof HashMap) {HashMap<String, Object> map = (HashMap<String, Object>) result;String audioUrl = (String) map.get("audioUrl");String requestId = (String) map.get("requestId");Log.i("TTS", "Success - audio_url: " + audioUrl + ", request_id: " + requestId);}}@Overridepublic void onError(int code, String desc) {Log.e("TTS", "Failed - code: " + code + ", message: " + desc);}});} catch (Exception e) {Log.e("TTS", "Failed to serialize parameters: " + e.getMessage());}}
func convertTextToVoice(text: String, voiceId: String? = nil, audioFormat: String? = nil) {var params: [String: Any] = ["text": text]// 选填参数if let voiceId = voiceId, !voiceId.isEmpty {params["voiceId"] = voiceId}if let audioFormat = audioFormat, !audioFormat.isEmpty {params["audioFormat"] = audioFormat}guard let jsonData = try? JSONSerialization.data(withJSONObject: params),let jsonString = String(data: jsonData, encoding: .utf8) else {print("Failed to serialize parameters")return}V2TIMManager.sharedInstance().callExperimentalAPI(api: "convertTextToVoice",param: jsonString as NSObject,succ: { result inif let dict = result as? [String: Any] {let audioUrl = dict["audioUrl"] as? String ?? ""let requestId = dict["requestId"] as? String ?? ""print("Success - audio_url: \\(audioUrl), request_id: \\(requestId)")}},fail: { code, message inprint("Failed - code: \\(code), message: \\(message ?? "")")})}
void ConvertTextToVoice() {json::Object json_param;json_param[kTIMRequestInternalOperation] = kTIMInternalOperationConvertTextToVoice;// 需要转语音的文字内容(必填,长度 1-255)json_param[kTIMRequestConvertTextToVoiceText] = "你好,这是一段测试文字转语音的内容";// TTS 声音 ID(选填)// json_param[kTIMRequestConvertTextToVoiceVoiceId] = "";// 音频格式: pcm wav(选填)json_param[kTIMRequestConvertTextToVoiceAudioFormat] = "wav";// 语言代码(选填)json_param[kTIMRequestConvertTextToVoiceLanguage] = "";std::string json_parameter = json::Serialize(json_param);int ret = callExperimentalAPI(json_parameter.c_str(),[](int32_t code, const char* desc, const char* json_params, const void* user_data) {printf("\\nConvertTextToVoice|code:%d|desc:%s\\n", code, desc);if (code == 0 && json_params) {json::Value json = json::Deserialize(json_params);if (json.HasKey(kTIMResponseConvertTextToVoiceAudioUrl)) {std::string audio_url = json[kTIMResponseConvertTextToVoiceAudioUrl];Printf("audio_url: %s\\n", audio_url.c_str());}if (json.HasKey(kTIMResponseConvertTextToVoiceRequestId)) {std::string request_id = json[kTIMResponseConvertTextToVoiceRequestId];Printf("request_id: %s\\n", request_id.c_str());}}}, nullptr);Printf("ConvertTextToVoice|ret:%d\\n", ret);}
Future<Map<String, dynamic>> convertTextToVoice({required String text,String? voiceId,String audioFormat = 'wav',String language = '',}) async {Map<String, dynamic> param = {'request_convert_text_to_voice_text': text,'request_convert_text_to_voice_audio_format': audioFormat,'request_convert_text_to_voice_language': language,};if (voiceId != null && voiceId.isNotEmpty) {param['request_convert_text_to_voice_voice_id'] = voiceId;}final result = await TencentImSDKPlugin.v2TIMManager.callExperimentalAPI(api: 'internal_operation_convert_text_to_voice',param: param,);if (result.code == 0 && result.data != null) {final dataMap = result.data as Map<String, dynamic>;final audioUrl = dataMap['response_convert_text_to_voice_audio_url'] as String?;final requestId = dataMap['response_convert_text_to_voice_request_id'] as String?;if (audioUrl != null && audioUrl.isNotEmpty) {return {'success': true,'audioUrl': audioUrl,'requestId': requestId,};}}return {'success': false,'code': result.code ?? -1,'message': result.desc ?? 'Convert text to voice failed',};}
流式文本实时转语音(流式消息 TTS)
对 IM 流式消息边生成文本、边合成语音,适用于 AI 回复实时播报。与
convertTextToVoice 返回完整音频文件不同,本功能持续返回音频包,由应用解码播放。接口说明
以下接口是流式消息的成员函数:通过消息的
streamElem(V2TIMStreamElem)调用,作用于该条消息:接口 | 用途 | 请求参数 | 成功结果 |
对该流式消息开始语音合成。 | voiceFormat:声音参数,可选,见下表。 | 启动成功确认,不返回音频。 | |
停止语音合成。 | 无。 | 停止成功确认。 |
声音参数
V2TIMTTSVoiceFormat:参数 | 类型 | 说明 |
voiceID | String | 音色 ID,可使用系统预置音色或克隆的自定义音色 ID,空值使用默认音色。 |
speed | Float | 语速,范围 [0.5, 2.0],默认 1.0 |
回调字段 | 类型 | 说明 |
msgID | String | 所属消息 ID;只处理当前消息的音频,过滤停止后的在途回调。 |
audioDataList | Array | 本次下发的 Opus 音频包,按列表顺序解码播放;不是累计音频。 |
isFinished | Boolean | 音频流是否结束;先处理本次音频包,再处理结束标记。 |
注意:
回调返回的音频为 16 kHz、单声道的裸 Opus 音频包,Android 和 iOS 均为二进制数据,无需 Base64 解码;应用需自行解码并播放。
只能对 SDK 收到的流式消息调用,SDK 自动跟随文本流合成,无需逐段提交文本。
streamID 尚未就绪时启动会返回参数错误,可在 onRecvMessageModified 中重试。SDK 内置限制:从调用
startTTS 起,单次合成最长 5 分钟;超过约 30 秒没有收到新的音频数据会自动结束。结束时均会收到 isFinished = true。speed 超出范围会返回错误。调用流程
1. 注册高级消息监听,对目标流式消息调用
startTTS,并记录其 msgID。2. 只处理当前
msgID 的回调,按顺序解码播放 audioDataList。3. 收到
isFinished = true 后,播放完队列中剩余的音频即播报结束。4. 打断时先解除
msgID 绑定并停止播放,再调用 stopTTS。示例代码
以下代码直接调用 IM SDK,按顺序使用,变量和监听器由应用持有。
player 为应用实现的 Opus 解码播放器:enqueue 按顺序解码播放,finish 表示音频输入结束,stop 立即停播并清空队列。1. 注册监听并处理音频
import com.tencent.imsdk.v2.*;// 以下字段放在会话对象中,回调在主线程执行。private String activeMsgID;private V2TIMStreamElem activeElem;private final V2TIMAdvancedMsgListener ttsListener = new V2TIMAdvancedMsgListener() {@Overridepublic void onRecvTTSResponse(V2TIMTTSResponse response) {if (activeMsgID == null || !activeMsgID.equals(response.getMsgID())) {return;}if (response.getAudioDataList() != null) {for (byte[] packet : response.getAudioDataList()) {player.enqueue(packet);}}if (response.isFinished()) {player.finish();activeMsgID = null;activeElem = null;}}};// 开始前注册,页面退出时调用 removeAdvancedMsgListener(ttsListener)。V2TIMManager.getMessageManager().addAdvancedMsgListener(ttsListener);
import ImSDK_Plus// 以下成员放在应用持有的 NSObject 子类中,并遵循 V2TIMAdvancedMsgListener。private var activeMsgID: String?private var activeElem: V2TIMStreamElem?func onRecvTTSResponse(response: V2TIMTTSResponse) {guard let id = activeMsgID, response.msgID == id else { return }for packet in response.audioDataList ?? [] {player.enqueue(packet)}if response.isFinished {player.finish()activeMsgID = nilactiveElem = nil}}// 开始前注册,页面退出时调用 removeAdvancedMsgListener(listener:)。V2TIMManager.sharedInstance().addAdvancedMsgListener(listener: self)
2. 开始语音合成
V2TIMStreamElem elem = message.getStreamElem();if (elem != null) {activeMsgID = message.getMsgID();activeElem = elem;V2TIMTTSVoiceFormat format = new V2TIMTTSVoiceFormat();format.setVoiceID(""); // 空值使用默认音色format.setSpeed(1.0f); // 范围 [0.5, 2.0]elem.startTTS(format, new V2TIMCallback() {@Overridepublic void onSuccess() {}@Overridepublic void onError(int code, String desc) {// streamID 未就绪时可在 onRecvMessageModified 中重试activeMsgID = null;activeElem = null;System.err.println("startTTS failed: " + code + ", " + desc);}});}
if let elem = message.streamElem {activeMsgID = message.msgIDactiveElem = elemlet format = V2TIMTTSVoiceFormat()format.voiceID = "" // 空值使用默认音色format.speed = 1.0 // 范围 [0.5, 2.0]elem.startTTS(voiceFormat: format, succ: nil, fail: { [weak self] code, desc in// streamID 未就绪时可在 onRecvMessageModified 中重试self?.activeMsgID = nilself?.activeElem = nilprint("startTTS failed: \\(code), \\(desc ?? "")")})}
3. 停止语音合成
V2TIMStreamElem elem = activeElem;activeMsgID = null; // 先解除绑定,丢弃在途音频activeElem = null;player.stop();if (elem != null) {elem.stopTTS(new V2TIMCallback() {@Overridepublic void onSuccess() {}@Overridepublic void onError(int code, String desc) {System.err.println("stopTTS failed: " + code + ", " + desc);}});}
let elem = activeElemactiveMsgID = nil // 先解除绑定,丢弃在途音频activeElem = nilplayer.stop()elem?.stopTTS(succ: nil, fail: { code, desc inprint("stopTTS failed: \\(code), \\(desc ?? "")")})
结果处理与异常收尾
isFinished = true 只表示音频流结束,不代表播放完成,也不代表合成成功;超时、断连时同样会收到。停止后仍可能收到在途音频,按
msgID 过滤丢弃。失败或退出时停止播放并移除监听。
音色克隆(voiceClone)
基于参考音频克隆出自定义音色,克隆成功后返回音色 ID,可用于后续 TTS 调用。
请求参数:
参数 | 类型 | 必填 | 说明 |
audioUrl | String | 是 | 参考音频 URL(要求 16k 单声道 wav 格式,时长 10-18 秒)。 |
voiceName | String | 是 | 声音克隆的名称。 |
promptText | String | 否 | 参考音频对应的文本内容。 |
language | String | 否 | 语言代码(参考 ISO 639-1)。 |
返回参数:
参数 | 类型 | 说明 |
voiceId | String | 克隆出的音色 ID,可用于 TTS 接口的 voiceId 参数。 |
requestId | String | 唯一请求 ID。 |
说明:
参考音频要求为 16k 采样率、单声道的 wav 格式文件,时长建议在 10-18 秒之间。
音频需要先上传获取 URL(可通过 SDK 的文件上传接口获取),再传入 audioUrl。
示例代码:
JSONObject params = new JSONObject();params.put("audioUrl", "https://example.com/voice.wav");params.put("voiceName", "MyVoice");params.put("promptText", ""); // 选填V2TIMManager.getInstance().callExperimentalAPI("voiceClone", params.toString(),new V2TIMValueCallback<Object>() {@Overridepublic void onSuccess(Object result) {try {JSONObject resultJson = new JSONObject((String) result);String voiceId = resultJson.optString("voiceId");Log.d("TAG", "voiceId: " + voiceId);} catch (JSONException e) {Log.e("TAG", "parse error");}}@Overridepublic void onError(int code, String desc) {Log.e("TAG", "error: " + code + ", " + desc);}});
let params: [String: Any] = ["audioUrl": "https://example.com/voice.wav","voiceName": "MyVoice","promptText": "" // 选填]guard let jsonData = try? JSONSerialization.data(withJSONObject: params) else { print("Failed to serialize parameters"); return }guard let jsonString = String(data: jsonData, encoding: .utf8) else { print("Failed to convert to string"); return }V2TIMManager.sharedInstance().callExperimentalAPI(api: "voiceClone",param: jsonString as NSObject,succ: { result inguard let resultString = result as? String,let resultData = resultString.data(using: .utf8),let resultDict = try? JSONSerialization.jsonObject(with: resultData) as? [String: Any],let voiceId = resultDict["voiceId"] as? String else {print("parse error")return}print("voiceId: \\(voiceId)")},fail: { code, desc inprint("error: \\(code), \\(desc ?? "")")})
void VoiceClone() {json::Object json_param;json_param[kTIMRequestInternalOperation] = kTIMInternalOperationVoiceClone;json_param[kTIMRequestVoiceCloneVoiceName] = "MyVoice"; // 必填json_param[kTIMRequestVoiceCloneAudioUrl] = "https://example.com/voice.wav"; // 必填json_param[kTIMRequestVoiceClonePromptText] = ""; // 选填json_param[kTIMRequestVoiceCloneLanguage] = ""; // 选填std::string param_str = json::Serialize(json_param);int ret = callExperimentalAPI(param_str.c_str(),[](int32_t code, const char* desc, const char* json_params, const void* user_data) {if (code != TIM_SUCC) {printf("voiceClone failed: %d, %s\\n", code, desc);return;}json::Value json_value = json::Deserialize(json_params);std::string voice_id = Json2String(json_value, kTIMResponseVoiceCloneVoiceId, "");std::string request_id = Json2String(json_value, kTIMResponseVoiceCloneRequestId, "");printf("voiceClone success: voiceId=%s, requestId=%s\\n", voice_id.c_str(), request_id.c_str());}, nullptr);}
Future<Map<String, dynamic>> voiceClone({required String audioUrl,required String voiceName,String promptText = '',String language = '',}) async {Map<String, dynamic> param = {'request_voice_clone_audio_url': audioUrl,'request_voice_clone_voice_name': voiceName,'request_voice_clone_prompt_text': promptText,'request_voice_clone_language': language,};final result = await TencentImSDKPlugin.v2TIMManager.callExperimentalAPI(api: 'internal_operation_voice_clone',param: param,);if (result.code == 0 && result.data != null) {final dataMap = result.data as Map<String, dynamic>;final voiceId = dataMap['response_voice_clone_voice_id'] as String?;final requestId = dataMap['response_voice_clone_request_id'] as String?;if (voiceId != null && voiceId.isNotEmpty) {return {'success': true,'voiceId': voiceId,'requestId': requestId,};}}return {'success': false,'code': result.code ?? -1,'message': result.desc ?? 'Voice clone failed',};}
获取自定义音色列表(getCustomVoiceList)
获取当前用户已克隆的所有自定义音色。
请求参数:无需额外参数。
返回参数:
参数 | 类型 | 说明 |
voiceList | Array | 自定义音色列表,每个元素包含 voice_id(音色 ID)和 name(音色名称)。 |
示例代码:
V2TIMManager.getInstance().callExperimentalAPI("getCustomVoiceList",null,new V2TIMValueCallback<Object>() {@Overridepublic void onSuccess(Object result) {List<Map<String, String>> voiceList = (List<Map<String, String>>) result;for (Map<String, String> item : voiceList) {String voiceId = item.get("voice_id");String name = item.get("name");Log.d(TAG, "Voice ID: " + voiceId + ", Name: " + name);}}@Overridepublic void onError(int code, String desc) {Log.e(TAG, "getCustomVoiceList failed: " + code + ", " + desc);}});
V2TIMManager.sharedInstance().callExperimentalAPI(api: "getCustomVoiceList",param: nil,succ: { result in// 解析返回的音色列表print("getCustomVoiceList success: \\(result ?? "")")},fail: { code, desc inprint("error: \\(code), \\(desc ?? "")")})
void GetCustomVoiceList() {json::Object json_param;json_param[kTIMRequestInternalOperation] = kTIMInternalOperationGetCustomVoiceList;std::string json_parameters = json::Serialize(json_param);int ret = callExperimentalAPI(json_parameters.c_str(),[](int32_t code, const char* desc, const char* json_params, const void* user_data) {printf("GetCustomVoiceList: code=%d desc=%s\\n", code, desc);if (code == 0 && json_params) {json::Object result = json::Deserialize(json_params);if (result.HasKey(kTIMResponseGetCustomVoiceListVoiceList)) {json::Array voice_list = result[kTIMResponseGetCustomVoiceListVoiceList];printf(" voice_list count = %zu\\n", voice_list.size());for (auto& item : voice_list) {json::Object voice_item = item;std::string voice_id = voice_item[kTIMCustomVoiceItemVoiceId];std::string name = voice_item[kTIMCustomVoiceItemName];Printf(" voice_id = %s, name = %s\\n", voice_id.c_str(), name.c_str());}}}}, nullptr);}
Future<Map<String, dynamic>> getCustomVoiceList() async {final result = await TencentImSDKPlugin.v2TIMManager.callExperimentalAPI(api: 'internal_operation_get_custom_voice_list',param: {},);if (result.code == 0 && result.data != null) {final dataMap = result.data as Map<String, dynamic>;final voiceList = dataMap['response_get_custom_voice_list_voice_list'] as List?;if (voiceList != null) {// Parse voice listfinal voices = voiceList.map((item) {final voiceMap = item as Map<String, dynamic>;return {'voiceId': voiceMap['custom_voice_item_voice_id'] as String?,'name': voiceMap['custom_voice_item_name'] as String?,};}).toList();return {'success': true,'voiceList': voices,};}}return {'success': false,'code': result.code ?? -1,'message': result.desc ?? 'Get custom voice list failed',};}
删除自定义音色(deleteCustomVoice)
删除指定的克隆音色。
请求参数:
参数 | 类型 | 必填 | 说明 |
voiceId | String | 是 | 要删除的音色 ID。 |
示例代码:
JSONObject params = new JSONObject();params.put("voiceId", "voice_xxx");V2TIMManager.getInstance().callExperimentalAPI("deleteCustomVoice", params.toString(),new V2TIMValueCallback<Object>() {@Overridepublic void onSuccess(Object result) {Log.d("TAG", "delete success");}@Overridepublic void onError(int code, String desc) {Log.e("TAG", "error: " + code + ", " + desc);}});
let params: [String: Any] = ["voiceId": "voice_xxx"]guard let jsonData = try? JSONSerialization.data(withJSONObject: params) else { print("Failed to serialize parameters"); return }guard let jsonString = String(data: jsonData, encoding: .utf8) else { print("Failed to convert to string"); return }V2TIMManager.sharedInstance().callExperimentalAPI(api: "deleteCustomVoice",param: jsonString as NSObject,succ: { _ inprint("delete success")},fail: { code, desc inprint("error: \\(code), \\(desc ?? "")")})
void CallDeleteCustomVoice() {json::Object json_param;json_param[kTIMRequestInternalOperation] = kTIMInternalOperationDeleteCustomVoice;json_param[kTIMRequestDeleteCustomVoiceVoiceId] = "voice_xxx"; // 必填std::string param_str = json::Serialize(json_param);callExperimentalAPI(param_str.c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {if (code != TIM_SUCC) {printf("deleteCustomVoice failed: %d, %s\\n", code, desc);return;}printf("deleteCustomVoice success\\n");}, nullptr);}
Future<Map<String, dynamic>> deleteCustomVoice({required String voiceId,}) async {try {Map<String, dynamic> param = {'request_delete_custom_voice_voice_id': voiceId,};final result = await TencentImSDKPlugin.v2TIMManager.callExperimentalAPI(api: 'internal_operation_delete_custom_voice',param: param,);if (result.code == 0) {return {'success': true,};}return {'success': false,'code': result.code ?? -1,'message': result.desc ?? 'Delete custom voice failed',};} catch (e) {return {'success': false,'code': -1,'message': e.toString(),};}}

