注意:
此接口为实时同传接口,在参数风格、错误码等方面有区别于云 API 接口,请知悉。
1. 接口描述
本接口服务采用 WebSocket 协议,对实时音频流进行同声传译。同声传译大模型支持中英互译,能够听懂并准确把握原始语音内容,低延迟完成翻译,并保留说话人的音色、语气与情感,让表达更接近本人。
本接口具备以下特点:
无需指定源语言,服务端自动识别源语言,仅需指定目标语言 target。
除译文字幕外,同步下发目标语言的译音音频(binary message),支持克隆源说话人音色或使用内置音色。
支持在会话过程中动态变更目标语言与输出音色,无需重新建连。
支持对句级定稿译文进行内容安全审核。
在使用该接口前,需要 开通语音识别服务,并进入 API 密钥管理页面 新建密钥,生成 appid、secretid 和 secretkey,用于 API 调用时生成签名,签名将用来进行接口鉴权。
2. 接口要求
集成实时语音同传 API 时,需按照以下要求。
内容 | 说明 |
语言种类 | 源语言由服务端自动识别;目标语言支持中文、英语,可通过接口参数 target 设置。 |
音频属性 | 采样率:8000Hz、16000Hz、24000Hz、48000Hz,通过参数 input_sample_rate 指定 采样精度:16bits 声道:单声道(mono) 注:上行音频与下行译音共用同一采样率,即下行译音的采样率与 input_sample_rate 一致 |
音频格式 | PCM(16bit 有符号小端,s16le) |
输出音色 | clone:克隆源说话人音色 male:内置男声 female:内置女声 |
请求协议 | wss 协议 |
请求地址 | wss://asr.cloud.tencent.com/asr/si/?{请求参数} |
接口鉴权 | 签名鉴权机制,详情请参见 签名生成。 |
响应格式 | 文本结果(字幕、状态、错误):text message,统一采用 JSON 格式。 译音音频:binary message,PCM 二进制数据。 |
数据发送 | 建议每200ms 发送200ms 时长(即1:1实时率)的数据包,对应 PCM 大小为:8k 采样率3200字节,16k 采样率6400字节,24k 采样率9600字节,48k 采样率19200字节。 音频发送速率过快超过1:1实时率,后台将返回错误并主动断开连接;客户端超过15秒未发送音频数据,后台将返回错误并主动断开连接。 |
并发限制 |
3. 接口调用流程
接口调用流程分为两个阶段:握手阶段和同传阶段。后台返回两种类型的消息:
text message:内容为 JSON 序列化字符串,用于返回握手结果、译文字幕、状态通知与错误信息。
binary message:内容为译音 PCM 音频数据,仅在同传阶段返回。
text message 格式说明如下,不同 message_type 的消息仅携带与之相关的字段:
字段名 | 类型 | 描述 |
code | Integer | 状态码,0代表正常,非0值表示发生错误。 |
message | String | 错误说明,发生错误时显示这个错误发生的具体原因,随着业务发展或体验优化,此文本可能会经常保持变更或更新。 |
voice_id | String | 音频流全局唯一标识,一个 WebSocket 连接对应一个,用户自己生成(推荐使用 UUID),最长128位。 注意:每次建立 WebSocket 连接都必须重新生成 voice_id,任何情况下中断了同传或者 WebSocket 连接(如连接失败、正常结束、同传返回错误码等),voice_id 作废,重新发起同传必须使用新的 voice_id。 |
final | Integer | 会话终态标识: 0:会话进行中。 1:会话已结束,后台将断开连接。 code 为1时表示音频流全部同传结束。 |
message_type | String | 消息类型,取值见下方 消息类型说明。握手成功消息、会话结束消息与错误消息不携带该字段。 |
sentence_id | String | 当前句唯一 ID。同一句的译文字幕与译音共享同一 sentence_id,客户端可据此聚合对齐。 |
language | String | 当前译文的目标语言类型,如 "zh"、"en"。示例值:en |
text | String | 译文文本内容,编码为 UTF8。增量消息中为新增片段,定稿消息中为整句译文。示例值:Real time |
start_ts | Integer | 当前句在上行音频流时间轴上的起始时间,单位毫秒。示例值:1000 |
end_ts | Integer | 当前句在上行音频流时间轴上的结束时间,单位毫秒。示例值:3000 |
end_reason | String | 句级译文定稿的结束原因: stop:正常结束。 sensitive:译文命中内容安全审核,text 已替换为文明用语提示。 示例值:stop |
reason | String | 句子被跳过的原因。示例值:source_language_equals_target_language |
session | Session | 会话配置变更后实际生效的配置,Session 结构体格式为: target:String 类型,生效的目标语言。 voice:String 类型,生效的输出音色。 示例值:{"target":"zh","voice":"male"} |
其中消息类型 message_type 取值说明:
取值 | 携带字段 | 描述 |
TranslationSubtitleStart | sentence_id、language、text、start_ts | 译文新句开始,text 为该句译文的首个增量片段。 |
TranslationSubtitleResponse | sentence_id、text | 译文句内增量,text 为本次新增的片段,客户端需按顺序拼接到同 sentence_id 的已有译文之后。 |
TranslationSubtitleEnd | sentence_id、language、text、start_ts、end_ts、end_reason | 句级译文定稿,text 为整句完整译文,该句结果不再变化。客户端应以本条消息的 text 整体替换此前同 sentence_id 的增量拼接结果。 |
TTSSentenceStart | sentence_id、start_ts | 译音句开始标记,其后下发的 binary message 译音数据均属于该句,直至下一条 TTSSentenceStart。 |
TranslationSentenceSkipped | language、reason | 当前句被判定无需翻译而跳过(如源语言与目标语言相同),无字幕与译音产出。该消息仅为提醒,会话继续进行。 |
session_updated | session | 会话配置变更已生效,session 为实际生效的目标语言与输出音色。 |
握手阶段
请求格式
握手阶段,客户端主动发起 WebSocket 连接请求,请求 URL 格式为:
wss://asr.cloud.tencent.com/asr/si/<appid>?{请求参数}
key1=value2&key2=value2...
参数说明:
参数名称 | 必填 | 类型 | 描述 |
secretid | 是 | String | |
signature | 是 | String | 接口签名参数,生成方式见 签名生成。示例值:*g1JfeBi%2FYnTjyjekxfDA%3D |
timestamp | 是 | Integer | 当前 UNIX 时间戳,单位为秒。与服务器时间相差超过24小时将返回参数不合法错误,相差过大也会引起签名过期错误。示例值:1745932688 |
expired | 是 | Integer | 签名的有效期截止时间 UNIX 时间戳,单位为秒。expired 必须大于 timestamp 且 expired - timestamp 小于90天。示例值:1746019088 |
nonce | 是 | Integer | 随机正整数。用户需自行生成,最长10位。示例值:8743357 |
voice_id | 是 | String | 音频流全局唯一标识,一个 WebSocket 连接对应一个,用户自己生成(推荐使用 UUID),最长128位,仅允许包含字母、数字、下划线(_)和中划线(-)。 注意:每次建立 WebSocket 连接都必须重新生成 voice_id,任何情况下中断同传或者 WebSocket 连接(如连接失败、正常结束、同传返回错误码等),voice_id 作废,重新发起同传必须使用新的 voice_id示例值:c64385ee-3e5c-4fc5-bbfd-7c71addb35b0 |
target | 是 | String | 目标语言类型。支持的语言类型: zh:中文 en:英文 注意:源语言由服务端自动识别,若源语言与目标语言相同,该句将被跳过并返回 TranslationSentenceSkipped 消息,无字幕与译音产出。示例值:en |
input_sample_rate | 是 | Integer | 上行 PCM 音频采样率,单位 Hz。支持:8000、16000、24000、48000。 注意:下行译音音频与上行音频共用同一采样率。示例值:16000 |
voice | 否 | String | 译音输出音色,不传时使用服务端默认音色。支持的音色: clone:克隆源说话人音色 male:内置男声 female:内置女声 示例值:clone |
security_audit | 否 | Boolean | 译文内容安全审核开关,取值 true 或 false,默认为 true(开启)。开启后对每句定稿译文(TranslationSubtitleEnd)进行审核,命中时 end_reason 返回 sensitive,text 替换为文明用语提示。 注意:参数值需使用小写字符串 true/false 参与签名。示例值:true |
token | 否 | String | 使用临时密钥时需传入的安全令牌(SecurityToken),此时 secretid 与签名使用的 secretkey 均为临时密钥。使用永久密钥时无需传入。 |
region | 否 | String | 地域标识。示例值:ap-guangzhou |
signature 签名生成
1. 对除 signature 之外的所有参数按字典序进行排序,拼接请求 URL (不包含协议部分:wss://)作为签名原文,这里以 appid=125922***,secretid=*****Qq1zhZMN8dv0****** 为例拼接签名原文,则拼接的签名原文为:
asr.cloud.tencent.com/asr/si/125922***?expired=1673494772&input_sample_rate=16000&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******&target=en×tamp=1673408372&voice=clone&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0
2. 对签名原文使用 SecretKey 进行 HMAC-SHA1 加密,之后再进行 base64 编码。例如对上一步的签名原文, secretkey=*****SkqpeHgqmSz*****,使用 HMAC-SHA1 算法进行加密并做 base64 编码处理:
Base64Encode(HmacSha1("asr.cloud.tencent.com/asr/si/125922***?expired=1673494772&input_sample_rate=16000&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******&target=en×tamp=1673408372&voice=clone&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0", "*****SkqpeHgqmSz*****"))
得到 signature 签名值为:
*****Bi/YnTjyjekxfDA=
3. 将 signature 值进行 urlencode(必须进行 URL 编码,编码函数必须要支持对+、=等特殊字符的编码,否则将导致鉴权失败偶现)后拼接得到最终请求 URL 为:
wss://asr.cloud.tencent.com/asr/si/125922***?expired=1673494772&input_sample_rate=16000&nonce=1673408372&secretid=*****Qq1zhZMN8dv0******&target=en×tamp=1673408372&voice=clone&voice_id=c64385ee-3e5c-4fc5-bbfd-7c71addb35b0&signature=*****Bi%2FYnTjyjekxfDA%3D
注意:
appid 仅置于 URL 路径中,请勿在 query 参数中重复携带。
签名完成后切勿增删或改写 query 参数(包括参数值的大小写),否则将导致鉴权失败(6002)。
请求响应
客户端发起连接请求后,后台建立连接并依次进行参数校验、签名校验、并发校验与账号计费状态校验,全部校验通过则返回 code 值为0的确认消息表示握手成功,此时可开始上传音频;如果校验失败,后台返回 code 为非0值、final 为1的消息并断开连接。
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","final":0}
{"code":6002,"message":"鉴权失败","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","final":1}
同传阶段
握手成功之后,进入同传阶段,客户端上传语音数据并接收译文字幕与译音音频。
上传数据
在同传过程中,客户端持续上传 binary message 到后台,内容为 PCM 音频流二进制数据(16bit、单声道,采样率与 input_sample_rate 一致)。建议每 200ms 发送 200ms 时长(即1:1实时率)的数据包,对应 PCM 大小计算方式为:input_sample_rate / 1000 × 2 × 200 字节,如 16k 采样率为6400字节。音频发送速率过快超过1:1实时率、单个分片过大或客户端超过15秒未发送音频数据,后台将返回错误并主动断开连接。
音频流上传完成之后,客户端需发送以下内容的 text message,通知后台结束同传。后台收到结束消息后将不再处理该连接上的后续上行数据。
{"type": "end"}
变更会话配置
同传过程中,客户端可发送以下内容的 text message,动态变更目标语言与输出音色,无需重新建连:
{"type": "update", "target": "zh", "voice": "male"}
参数说明:
参数名称 | 必填 | 类型 | 描述 |
type | 是 | String | 固定为 update。 |
target | 是 | String | 变更后的目标语言类型,取值同握手参数 target。 |
voice | 否 | String | 变更后的输出音色,取值同握手参数 voice。不传表示沿用当前音色。 |
变更生效后,后台返回 message_type 为 session_updated 的消息,session 为实际生效的配置:
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","message_type":"session_updated","final":0,"session":{"target":"zh","voice":"male"}}
如果变更参数取值不合法,后台返回 code 为6001、final 为0的提示消息,会话不会中断并沿用原配置:
{"code":6001,"message":"unsupported target language \"ja\", supported: [zh en]","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","final":0}
注意:
上行 text message 仅支持 end 与 update 两种 type,上传无法解析或未知 type 的文本消息将返回错误码 6010 并断开连接。
发送 update 消息仅代表请求已发出,是否生效以 session_updated 消息为准。
接收消息
客户端上传数据的过程中,需要同步接收后台返回的 text message 与 binary message。一句话的典型消息序列为:
TranslationSubtitleStart -> TranslationSubtitleResponse(0次或多次) -> TranslationSubtitleEndTTSSentenceStart -> 译音 binary message(1次或多次)
字幕消息与译音消息相互独立、交错下发,通过 sentence_id 关联同一句的译文与译音,也可通过 start_ts 完成音文对齐。
译文字幕
译文新句开始,text 为首个增量片段:
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","message_type":"TranslationSubtitleStart","final":0,"sentence_id":"0669d099-ffdf-404e-ad91-5eaff18b20df","language":"en","text":"Real","start_ts":0}
译文句内增量,text 为本次新增片段:
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","message_type":"TranslationSubtitleResponse","final":0,"sentence_id":"0669d099-ffdf-404e-ad91-5eaff18b20df","text":" time"}
句级译文定稿,text 为整句完整译文:
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","message_type":"TranslationSubtitleEnd","final":0,"sentence_id":"0669d099-ffdf-404e-ad91-5eaff18b20df","language":"en","text":"Real time simultaneous interpretation.","start_ts":0,"end_ts":2840,"end_reason":"stop"}
译音音频
每句译音开始前,后台先下发 TTSSentenceStart 标记,随后以 binary message 下发该句的译音 PCM 数据(16bit、单声道,采样率与 input_sample_rate 一致):
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","message_type":"TTSSentenceStart","final":0,"sentence_id":"0669d099-ffdf-404e-ad91-5eaff18b20df","start_ts":0}
句子跳过提醒
当前句被判定无需翻译时(如源语言与目标语言相同),后台返回跳过提醒,会话继续进行:
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","message_type":"TranslationSentenceSkipped","final":0,"language":"en","reason":"source_language_equals_target_language"}
会话结束
客户端发送结束消息后,后台处理完所有上传的语音数据,最终返回 final 值为1的消息并断开连接。
{"code":0,"message":"success","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","final":1}
同传过程中如果出现错误,后台返回 code 为非0值、final 为1的消息并断开连接。
{"code":6008,"message":"客户端超过15秒未发送音频数据","voice_id":"c64385ee-3e5c-4fc5-bbfd-7c71addb35b0","final":1}
注意:
客户端应根据 code 与 final 组合判断消息性质:
code=0:正常结果,按 message_type 处理;final=1 表示会话正常结束。
code≠0 且 final=1:致命错误,会话已终止,客户端须立即停止推流。
code≠0 且 final=0:非致命提示(如变更会话配置参数不合法),会话继续进行。
4. 开发者资源
SDK
Tencent Cloud Speech SDK for Python:GitHub
SDK 调用示例
5. 错误码
数值 | 说明 |
6000 | 音频数据发送过多,请控制推送速率与真实时长一致。注意:实时同传的效果是"边说边出译文译音",1秒内发送的音频数据总时长应为1秒。 |
6001 | 参数不合法,具体详情参考 message。注意:会话中变更配置参数不合法时同样返回该错误码,但 final 为0,会话不中断。 |
6002 | 鉴权失败。 |
6003 | 账号未开通本服务,请在控制台开通服务。 |
6004 | 资源包耗尽,请开通后付费或者购买资源包。 |
6005 | 账户欠费停止服务,请及时充值。 |
6006 | 账号当前调用并发超限。 |
6008 | 客户端超过15秒未发送音频数据。 |
6009 | 客户端连接断开。 |
6010 | 客户端上传未知文本消息。 |
6011 | 分片音频数据太大,请按照文档指引调整分片大小。 |
6012 | 因机器负载过高、网络抖动等导致失败,请重新发起新请求。注意:该问题通常为偶发,少量出现可忽略,发起新请求即可。 |
7000 | 因机器负载过高、网络抖动等导致失败,请重新发起新请求。注意:该问题通常为偶发,少量出现可忽略,发起新请求即可。 |