TRTC-ASR Python SDK

本文档是旧版协议（在线 v2、离线 v1）的完整说明。

本 SDK 同时提供新版 v3 协议客户端：只需 SDKAppID + SecretKey（无需腾讯云 AppID）， auth/params 分块、全 snake_case、扁平响应 + 数字错误码。v3 的快速开始与完整参数见 README。v2/v1 客户端继续维护，存量用户无需任何改动。

基于 TRTC 鉴权体系的语音识别（ASR）Python SDK，支持实时语音识别（WebSocket）、一句话识别（HTTP）和录音文件识别（异步 HTTP）三种模式。

其他语言 SDK：Go | Node.js | Java | Rust | C++

安装

集成到你的项目中（推荐）：

pip install git+https://github.com/Tencent-RTC/trtc-asr-sdk-python.git

clone 后运行示例：

git clone https://github.com/Tencent-RTC/trtc-asr-sdk-python.git
cd trtc-asr-sdk-python
pip install -r requirements.txt

要求：Python >= 3.8

快速开始

import asyncio
from trtc_asr import Credential, SITE_INTL, SpeechRecognizer, SpeechRecognitionListener, SpeechRecognitionResponse

# 只需实现关心的回调；其余事件沿用基类空实现即可。
class MyListener(SpeechRecognitionListener):
    def on_sentence_end(self, response: SpeechRecognitionResponse) -> None:
        print(f"Sentence end: {response.result.voice_text_str}")

    def on_fail(self, response, error: Exception) -> None:
        print(f"Failed: {error}")

async def main():
    # 1. 创建凭证
    credential = Credential(
        app_id=1300403317,         # 腾讯云 APPID
        sdk_app_id=1400188366,     # TRTC SDKAppID
        secret_key="your-sdk-secret-key",  # SDK密钥
    )
    # credential.set_site(SITE_INTL)  # 国际站；不调用则走国内站

    # 2. 创建识别器
    listener = MyListener()
    recognizer = SpeechRecognizer(credential, "16k_zh", listener)

    # 3. 可选配置
    # recognizer.set_hotword_id("hotword-id")     # 设置热词
    # recognizer.set_vad_silence_time(500)         # VAD 静音时间

    # 4. 启动识别
    await recognizer.start()

    # 5. 发送音频数据
    with open("audio.pcm", "rb") as f:
        while True:
            chunk = f.read(6400)  # 200ms of 16kHz 16bit mono PCM
            if not chunk:
                break
            await recognizer.write(chunk)
            await asyncio.sleep(0.2)  # 模拟实时

    # 6. 停止识别
    await recognizer.stop()

asyncio.run(main())

一句话识别

from trtc_asr import Credential
from trtc_asr.sentence_recognizer import SentenceRecognizer, SentenceRecognitionRequest

# 1. 创建凭证
credential = Credential(
    app_id=0,                      # 腾讯云 APPID
    sdk_app_id=0,                  # TRTC SDKAppID
    secret_key="your-sdk-secret-key",  # SDK密钥
)

# 2. 创建一句话识别器
recognizer = SentenceRecognizer(credential)

# 3. 从本地文件识别（自动 base64 编码）
with open("audio.pcm", "rb") as f:
    data = f.read()
result = recognizer.recognize_data_with_options(
    data,
    SentenceRecognitionRequest(
        eng_service_type="bigmodel",
        voice_format="pcm",
        language="zh",
    ),
)

print(f"识别结果: {result.result}")
print(f"音频时长: {result.audio_duration} ms")

    # 或者从 URL 识别
    # result = recognizer.recognize_url("https://example.com/audio.wav", "wav", "bigmodel")

录音文件识别

from trtc_asr import Credential
from trtc_asr.file_recognizer import CreateRecTaskRequest, FileRecognizer

# 1. 创建凭证
credential = Credential(
    app_id=0,                      # 腾讯云 APPID
    sdk_app_id=0,                  # TRTC SDKAppID
    secret_key="your-sdk-secret-key",  # SDK密钥
)

# 2. 创建录音文件识别器
recognizer = FileRecognizer(credential)

# 3. 提交识别任务（本地文件）
with open("audio.wav", "rb") as f:
    data = f.read()
task_id = recognizer.create_task_from_data_with_options(
    data,
    CreateRecTaskRequest(
        engine_model_type="bigmodel",
        channel_num=1,
        res_text_format=1,
        language="zh",
    ),
)
print(f"任务已提交: {task_id}")

# 4. 轮询等待结果（默认 1 秒间隔，10 分钟超时）
status = recognizer.wait_for_result(task_id)

print(f"识别结果: {status.result}")
print(f"音频时长: {status.audio_duration:.2f} s")

# 或者从 URL 提交（支持更大文件，≤1GB / ≤12h）
# task_id = recognizer.create_task_from_url("https://example.com/audio.wav", "bigmodel")

# 或者自定义轮询间隔（秒）
# status = recognizer.wait_for_result_with_interval(task_id, 2.0, 1800.0)

前提条件

使用本 SDK 前，您需要准备三个凭证：AppID、SDKAppID、SecretKey。国内站与国际站的账号体系不同，请按您的站点参照官方快速接入指南完成注册、创建应用与服务开通：

国内站：快速接入指南 — 注册腾讯云账号并完成实名认证 → 在 TRTC 控制台创建应用 → 开通「AI 智能识别」（体验版可免费试用）
国际站：Quick Start — 在 trtc.io 注册（自动开通 Tencentcloud 账号，无需实名认证）→ 在 console.trtc.io 创建应用 → 开通「AI Speech Recognition」（仅 RTC Engine Lite 及以上包月套餐，Free Trial 不支持）

注意：国际站的 AppID 不在 trtc.io 控制台显示，需在 Tencentcloud 控制台「账号信息」页查看（头像 → Account Information）；SDKAppID 与 SecretKey 均在应用详情页获取。

协议说明

WebSocket 连接

连接地址：
- 国内站：wss://asr.cloud-rtc.com/asr/v2/<appid>?{请求参数}
- 国际站：wss://asr-intl.cloud-rtc.com/asr/v2/<appid>?{请求参数}（credential.set_site(SITE_INTL)）

其中 <appid> 为腾讯云账号的 APPID，国内站可通过 API 密钥管理页面获取，国际站见 Tencentcloud 控制台「账号信息」。

鉴权方式

鉴权信息携带在 URL query 参数中（浏览器原生 WebSocket 无法自定义 header，因此走 query 传递）：

参数	说明
`sdkappid`	TRTC 应用 ID，从 TRTC 控制台获取（国内站 / 国际站）
`usersig`	TRTC 签名，计算文档，UserID 等于 `voice_id`

两者均由 SDK 自动填充，用户无需关心。

请求参数

参数	必填	类型	说明
`secretid`	是	String	SDK 内部自动用 APPID 填充
`sdkappid`	是	Integer	TRTC 应用 ID，SDK 内部自动填充
`usersig`	是	String	TRTC 签名，SDK 内部自动生成（值与 `signature` 一致）
`timestamp`	是	Integer	当前 UNIX 时间戳（秒）
`expired`	是	Integer	签名有效期截止时间戳，必须大于 timestamp
`nonce`	是	Integer	随机正整数，最长10位
`engine_model_type`	是	String	引擎类型：`bigmodel`(大模型，推荐，配 `language`)、`8k_zh`(中文电话)、`16k_zh`(中文通用)、`16k_zh_en`(中英文)
`voice_id`	是	String	音频流全局唯一标识（推荐 UUID），最长128位
`voice_format`	否	Integer	语音编码：`1` PCM（默认）
`needvad`	否	Integer	`0` 关闭 VAD，`1` 开启（默认）
`hotword_id`	否	String	热词表 ID
`hotword_list`	否	String	临时热词列表：`词1
`customization_id`	否	String	自学习模型 ID
`replace_text_id`	否	String	替换词表 ID
`filter_dirty`	否	Integer	过滤脏词：`0` 不过滤，`1` 过滤，`2` 替换为 *
`filter_modal`	否	Integer	过滤语气词：`0` 不过滤，`1` 部分，`2` 严格
`filter_punc`	否	Integer	过滤句末句号：`0` 不过滤，`1` 过滤
`filter_empty_result`	否	Integer	空结果回调：`0` 回调，`1` 不回调（服务端默认）
`convert_num_mode`	否	Integer	数字转换：`0` 不转，`1` 智能转换（默认），`3` 数学转换
`word_info`	否	Int	显示词级时间：`0` 不显示，`1` 显示，`2` 含标点
`vad_silence_time`	否	Integer	静音断句阈值（ms），范围 240-2000，默认 800
`vad_level`	否	Integer	VAD 场景档：`0` 高召回，`1` 远场过滤（服务端默认）
`noise_threshold`	否	Float	VAD 噪声微调，范围 `0.0-4.0`；设置后覆盖 `vad_level` 档位
`max_speak_time`	否	Integer	强制断句时间（ms），范围 5000-90000，默认 60000
`input_sample_rate`	否	Integer	输入 PCM 采样率，仅支持 `8000`（8k 音频喂 16k 引擎）
`speaker_diarization`	否	Integer	说话人分离：`0` 关闭（默认），`1` 匿名聚类，`3` 声纹角色认证
`speaker_number`	否	Integer	说话人数量提示（分离开启时生效，用于在线聚类）；`0` 自动检测
`speaker_roles`	否	String	临时声纹角色 JSON 数组，仅 `speaker_diarization=3`，如 `[{"RoleName":"teacher","AudioUrl":"https://.../a.wav"}]`
`voiceprintids`	否	String	已注册声纹 ID JSON 数组，仅 `speaker_diarization=3`
`language`	否	String	指定识别语言（如 `zh`、`en`），留空为自动检测
`signature`	是	String	接口签名参数，值与 `usersig` 一致

实时识别响应

字段	类型	说明
`code` / `message`	Integer / String	错误码与提示，`0` 表示成功
`voice_id` / `message_id`	String	音频流 ID / 单条消息 ID
`final`	Integer	`1` 表示会话结束包
`result.slice_type`	Integer	`0` 句子开始，`1` 中间结果，`2` 句末稳定结果
`result.index`	Integer	句子序号
`result.start_time` / `end_time`	Integer	当前结果起止时间（ms）
`result.voice_text_str`	String	当前结果文本
`result.word_size` / `word_list`	Integer / Array	词级（字级）时间戳，需 `word_info != 0`
`result.speaker_segments`	Array	说话人分段，开启说话人分离后返回
`result.language`	String	识别语言（引擎上报时）
`result.finish_silence_ms`	Integer	触发断句的尾部静音时长（ms）
`result.last_token_runtime_ms`	Integer	末字服务端解码耗时（ms）

说话人分离（实时）

开启 speaker_diarization 后，说话人归属通过两个入口返回：

result.speaker_segments[]：推荐入口。一个 result 可能包含多个说话人，句子级归属天然有歧义，因此协议按说话人切段返回。len(speaker_segments) == 1 即为单说话人句。
result.word_list[].speaker_id：字级归属，需同时设置 word_info != 0。

speaker_id 语义：会话内有效，从 1 开始编号，-1 表示未知，0 为保留值。

speaker_segments[] 字段：

字段	类型	说明
`speaker_id`	Integer	说话人编号
`speaker_name`	String	角色名，仅 `speaker_diarization=3` 命中注册声纹时返回，等于请求侧 `RoleName`
`start_time` / `end_time`	Integer	该分段起止时间（ms）
`text`	String	该分段文本
`word_start` / `word_end`	Integer	对应 `word_list` 的闭区间下标，即 `word_list[word_start:word_end+1]`；`word_info=0` 时不返回
`stable_flag`	Integer	该分段是否稳定：`1` 稳定，`0` 非稳定

Python 用法示例：

from trtc_asr import Credential, SpeechRecognizer, SpeechRecognitionListener, SPEAKER_DIARIZATION_CLUSTER

recognizer = SpeechRecognizer(credential, "16k_zh", MyListener())
recognizer.set_word_info(1)                                        # 需要字级说话人时开启
recognizer.set_speaker_diarization(SPEAKER_DIARIZATION_CLUSTER)    # 1：匿名聚类

# 声纹角色认证（返回角色名）：
# recognizer.set_speaker_diarization(SPEAKER_DIARIZATION_VOICEPRINT)  # 3
# recognizer.set_speaker_roles([SpeakerRole(role_name="teacher", audio_url="https://example.com/teacher.wav")])
# recognizer.set_voiceprint_ids(["vp-1"])  # 已注册声纹
# recognizer.set_speaker_number(2)         # 0 = 自动检测；两种分离模式都生效

# 回调里读取：
def on_sentence_end(self, response):
    for seg in response.result.speaker_segments:
        name = seg.speaker_name          # speaker_diarization=3 才有
        if not name:
            name = f"spk{seg.speaker_id}"
        print(f"[{name}] {seg.text}")

VAD 调优（noise_threshold / vad_level）

方法	取值	说明
`set_vad_level(level)`	`0` / `1`	`0` 高召回，`1` 远场过滤（服务端默认）
`set_noise_threshold(v)`	`0.0` - `4.0`	噪声抑制微调，值越大抑制越强、召回越低；设置后覆盖 `vad_level` 档位
`set_vad_silence_time(ms)`	240 - 2000	静音断句阈值

两者都是三态语义：只有显式调用 setter 才会下发，因此显式传 0 与「不配置」可以区分（服务端 vad_level 默认是 1）。超出范围会在 start() 阶段本地报错，不会浪费一次连接。

一句话识别接口

请求地址：
- 国内站：https://asr.cloud-rtc.com/v1/SentenceRecognition?{请求参数}
- 国际站：https://asr-intl.cloud-rtc.com/v1/SentenceRecognition?{请求参数}
请求方法：HTTP POST，Content-Type 为 application/json; charset=utf-8

鉴权方式

HTTP 接口的鉴权信息携带在请求 Header 中（与流式不同，不走 query）：

Header	说明
`X-TRTC-SdkAppId`	TRTC 应用 ID，从 TRTC 控制台获取（国内站 / 国际站）
`X-TRTC-UserSig`	TRTC 签名，UserID 等于 URL 参数中的 `RequestId`（SDK 内部自动生成）

URL 请求参数

参数	必填	类型	说明
`AppId`	是	String	腾讯云 APPID
`Secretid`	是	String	SDK 内部自动用 APPID 填充
`RequestId`	是	String	全局请求唯一 ID（UUID），用于生成 UserSig
`Timestamp`	是	Integer	当前 UNIX 时间戳（秒）

请求体参数（JSON）

参数	必填	类型	说明
`EngSerViceType`	是	String	引擎类型：`bigmodel`(大模型，推荐)、`16k_zh`(中文)、`16k_zh_en`(中英文)
`SourceType`	是	Integer	`0` URL 上传、`1` 本地数据（base64）
`VoiceFormat`	是	String	音频格式：`wav`、`pcm`、`ogg-opus`、`mp3`、`m4a`
`Data`	条件	String	base64 编码的音频数据（SourceType=1 时必填）
`DataLen`	条件	Integer	音频数据原始长度（SourceType=1 时必填）
`Url`	条件	String	音频 URL（SourceType=0 时必填）
`WordInfo`	否	Integer	词级时间：`0` 不显示、`1` 显示、`2` 含标点
`FilterDirty`	否	Integer	脏词过滤：`0` 不过滤、`1` 过滤、`2` 替换
`FilterModal`	否	Integer	语气词过滤：`0` 不过滤、`1` 部分、`2` 严格
`FilterPunc`	否	Integer	标点过滤：`0` 不过滤、`2` 过滤全部
`ConvertNumMode`	否	Integer	数字转换：`0` 不转、`1` 智能转换（默认）
`HotwordId`	否	String	热词表 ID
`HotwordList`	否	String	临时热词列表
`CustomizationId`	否	String	自学习模型 ID
`InputSampleRate`	否	Integer	PCM 输入采样率（仅 PCM 格式，支持 8000）
`Language`	否	String	指定识别语言，留空为自动检测

限制：音频时长 ≤ 60s，文件大小 ≤ 3MB，单账号并发 ≤ 30次/秒

录音文件识别接口

录音文件识别是异步接口，适用于较长音频（≤12h）。工作流程为：提交任务 → 轮询结果。

创建任务：CreateRecTask

请求地址：
- 国内站：https://asr.cloud-rtc.com/v1/CreateRecTask?{请求参数}
- 国际站：https://asr-intl.cloud-rtc.com/v1/CreateRecTask?{请求参数}
请求方法：HTTP POST，Content-Type 为 application/json; charset=utf-8
并发限制：默认 20次/秒

鉴权方式（Header 中的 X-TRTC-SdkAppId / X-TRTC-UserSig）与 URL 请求参数（AppId、Secretid、RequestId、Timestamp）均与一句话识别相同。

请求体参数（JSON）

参数	必填	类型	说明
`EngineModelType`	是	String	引擎类型：`bigmodel`(大模型，推荐)、`16k_zh`(中文)、`16k_zh_en`(中英文)
`ChannelNum`	是	Integer	声道数：`1` 单声道；`2` 双声道（8k 电话，自动区分说话人并返回 `ChannelId`：1=左/2=右）
`ResTextFormat`	是	Integer	结果详细度，不是时间戳开关：`0` 只返回 `Result`（`ResultDetail` 为空，拿不到任何时间戳）；`1` 返回 `ResultDetail`（句级 + 词级时间戳）；`2` 同 `1` 且 `SliceSentence` 带标点；`3` 同 `2`（字幕模式）。要时间戳就用 `1` 及以上
`SourceType`	是	Integer	`0` URL 上传、`1` 本地数据（base64）
`Url`	条件	String	音频 URL（SourceType=0，时长≤12h，大小≤1GB）
`Data`	条件	String	base64 编码音频数据（SourceType=1，大小≤5MB）
`DataLen`	条件	Integer	音频数据原始长度（SourceType=1）
`CallbackUrl`	否	String	回调 URL，任务完成后 POST 结果
`FilterDirty`	否	Integer	脏词过滤
`FilterModal`	否	Integer	语气词过滤
`FilterPunc`	否	Integer	标点过滤
`ConvertNumMode`	否	Integer	数字转换
`HotwordId`	否	String	热词表 ID
`HotwordList`	否	String	临时热词列表
`CustomizationId`	否	String	自学习模型 ID
`ReplaceTextId`	否	String	替换词表 ID
`Language`	否	String	指定识别语言，留空为自动检测
`SpeakerDiarization`	否	Integer	说话人分离：`0` 关闭（默认），`1` 匿名聚类，`3` 声纹角色认证
`SpeakerNumber`	否	Integer	说话人数量提示，`0` 自动检测
`SpeakerRoles`	否	Array	临时声纹角色，元素含 `RoleName` 与 `AudioUrl`，仅 `SpeakerDiarization=3`
`VoiceprintIds`	否	Array	已注册声纹 ID 列表，仅 `SpeakerDiarization=3`
`VadSilenceMs`	否	Integer	静音断句阈值（ms）
`VadLevel`	否	Integer	VAD 场景档：`0` 高召回（默认），`1` 远场过滤
`NoiseThreshold`	否	Float	VAD 噪声微调，范围 `0.0-4.0`；设置后覆盖 `VadLevel` 档位

VadLevel / NoiseThreshold 在 Python 结构体里是 Optional（vad_level=None / noise_threshold=None），因为 0 是合法取值，用 None 才能区分「显式传 0」与「不配置」。

响应

返回 RecTaskId（任务 ID），用于后续查询。任务有效期 24 小时。

查询结果：DescribeTaskStatus

请求地址：
- 国内站：https://asr.cloud-rtc.com/v1/DescribeTaskStatus?{请求参数}
- 国际站：https://asr-intl.cloud-rtc.com/v1/DescribeTaskStatus?{请求参数}
请求方法：HTTP POST
并发限制：默认 50次/秒

请求体参数（JSON）

参数	必填	类型	说明
`RecTaskId`	是	String	CreateRecTask 返回的任务 ID

响应（TaskStatus）

字段	类型	说明
`RecTaskId`	String	任务 ID
`Status`	Integer	`0` 等待、`1` 执行中、`2` 成功、`3` 失败
`StatusStr`	String	waiting / executing / success / failed
`Progress`	Integer	处理进度（0-100）
`Result`	String	识别结果文本。实测是字幕格式：`[声道:起始秒,声道:结束秒,序号] 文本\n`（如 `[0:0.020,0:2.560,1] 今天天气不错，挺风和日丽的。`），不是纯文本；纯文本请用 `ResultDetail[].FinalSentence` 拼接
`ErrorMsg`	String	失败原因
`ResultDetail`	Array	句级详细结果（含句级 / 词级时间戳），仅 `ResTextFormat >= 1` 时返回
`AudioDuration`	Float	音频时长（秒）

ResultDetail[] 字段：

字段	类型	说明
`FinalSentence`	String	该句最终文本
`SliceSentence`	String	该句分词文本（空格分隔）；`ResTextFormat=1` 不带标点，`>=2` 带标点
`StartMs` / `EndMs`	Integer	该句起止时间（ms）
`WordsNum`	Integer	词数
`Words[]`	Array	词级时间戳，字段为 `Word` / `StartTime` / `EndTime`（ms）
`SpeechSpeed`	Float	语速（字/秒）
`SilenceTime`	Integer	尾部静音时长（ms，部分引擎返回）
`Language`	String	该句识别语言（引擎上报时）

ResultDetail[] 中与说话人相关的字段：

字段	类型	说明
`SpeakerId`	Integer	说话人编号，开启 `SpeakerDiarization` 后返回
`SpeakerRoleName`	String	角色名，`SpeakerDiarization=3` 命中注册声纹时返回
`ChannelId`	Integer	双声道（`ChannelNum=2`）时的声道编号：1=左、2=右；此场景下优先用它区分说话人

上表字段名于 2026-09-14 用 16k_zh 与 bigmodel 两个引擎实测确认（resources/test.wav，2.4s）。 SDK 的 SentenceWords.offset_start_ms / offset_end_ms 会优先读 StartTime / EndTime，并回退兼容 OffsetStartMs / OffsetEndMs。

凭证获取

参数	国内站	国际站	说明
`app_id`	CAM 密钥管理	Tencentcloud 控制台「账号信息」（trtc.io 不显示）	腾讯云账号 APPID，用于 URL 路径
`sdk_app_id`	TRTC 控制台 > 应用管理	console.trtc.io > 应用详情	TRTC 应用 ID
`secret_key`	TRTC 控制台 > 应用概览 > SDK密钥	console.trtc.io > 应用详情	用于生成 UserSig，不会传输到网络

配置项

实时语音识别（SpeechRecognizer）：

方法	说明	默认值
`set_voice_format(f)`	音频格式	1 (PCM)
`set_need_vad(v)`	是否开启 VAD	1 (开启)
`set_convert_num_mode(m)`	数字转换模式	1 (智能)
`set_hotword_id(id)`	热词表 ID	-
`set_hotword_list(list)`	临时热词列表 `词\|权重,...`	-
`set_customization_id(id)`	自学习模型 ID	-
`set_replace_text_id(id)`	替换词表 ID	-
`set_filter_dirty(m)`	脏词过滤	0 (关闭)
`set_filter_modal(m)`	语气词过滤	0 (关闭)
`set_filter_punc(m)`	句号过滤	0 (关闭)
`set_filter_empty_result(m)`	空结果是否回调	1 (不回调)
`set_word_info(m)`	词级/字级时间	0 (关闭)
`set_vad_silence_time(ms)`	VAD 静音阈值（240-2000）	800ms
`set_vad_level(level)`	VAD 场景档：0 高召回 / 1 远场过滤	1
`set_noise_threshold(v)`	VAD 噪声微调（0.0-4.0），覆盖场景档	未设置
`set_max_speak_time(ms)`	强制断句时间（5000-90000）	60000ms
`set_input_sample_rate(r)`	输入 PCM 采样率，仅 8000	-
`set_speaker_diarization(m)`	说话人分离：0 关 / 1 聚类 / 3 声纹角色	0 (关闭)
`set_speaker_number(n)`	说话人数量提示（分离开启时生效）	0 (自动)
`set_speaker_roles(roles)`	临时声纹角色（仅模式 3）	-
`set_voiceprint_ids(ids)`	已注册声纹 ID（仅模式 3）	-
`set_language(lang)`	指定识别语言	自动检测
`set_voice_id(id)`	自定义 voice_id	自动 UUID

引擎模型

类型	说明
`bigmodel`	大模型引擎，推荐；配合 `language` 指定语种（如 `zh`）
`8k_zh`	中文通用，常用于电话场景
`16k_zh`	中文通用
`16k_zh_en`	中英文通用

示例

完整示例请参见：

实时语音识别：examples/realtime_asr.py — WebSocket 流式识别
一句话识别：examples/sentence_asr.py — HTTP 短音频识别（≤60s）
录音文件识别：examples/file_asr.py — 异步长音频识别

运行示例：

git clone https://github.com/Tencent-RTC/trtc-asr-sdk-python.git
cd trtc-asr-sdk-python
pip install -r requirements.txt

# 实时语音识别
python examples/realtime_asr.py -e bigmodel -f examples/test.pcm

# 一句话识别
python examples/sentence_asr.py -e bigmodel -f examples/test.pcm

# 录音文件识别
python examples/file_asr.py -e bigmodel -f examples/test.wav

# 说话人分离（实时：匿名聚类 + 字级说话人）
python examples/realtime_asr.py -e bigmodel -f examples/test.pcm --diarization 1 --word-info 1

# 说话人分离（实时：声纹角色认证，返回角色名）
python examples/realtime_asr.py -e bigmodel -f examples/test.pcm --diarization 3 \
  --roles "teacher=https://example.com/teacher.wav,student=https://example.com/student.wav"

# VAD 调优（远场过滤 + 噪声阈值）
python examples/realtime_asr.py -e bigmodel -f examples/test.pcm --vad-level 1 --noise-threshold 1.5

# 说话人分离（录音文件）
python examples/file_asr.py -e bigmodel -u https://example.com/call.wav --diarization 1

# 查看所有选项
python examples/realtime_asr.py -h
python examples/sentence_asr.py -h

项目结构

trtc-asr-sdk-python/
├── trtc_asr/                       # 包源码
│   ├── __init__.py                 # 包入口，统一导出
│   ├── credential.py               # 凭证管理（APPID + SDKAppID + SDK密钥）
│   ├── usersig.py                  # TRTC UserSig 生成
│   ├── signature.py                # URL 请求参数构建
│   ├── speech_recognizer.py        # 实时语音识别器（WebSocket）
│   ├── params.py                   # 说话人分离 / VAD 调优参数校验
│   ├── sentence_recognizer.py      # 一句话识别器（HTTP）
│   ├── file_recognizer.py          # 录音文件识别器（异步 HTTP）
│   └── errors.py                   # 错误定义
├── examples/                       # 示例代码
│   ├── test.pcm                    # 测试音频文件
│   ├── realtime_asr.py             # 实时语音识别示例
│   ├── sentence_asr.py             # 一句话识别示例
│   └── file_asr.py                 # 录音文件识别示例
├── tests/                          # 测试
│   ├── test_signature.py           # 签名参数测试
│   ├── test_signature_speaker.py   # 说话人分离 / VAD 调优参数测试
│   ├── test_params.py              # 参数校验测试
│   ├── test_diarization.py         # 说话人分离端到端测试
│   ├── test_recognizer_lifecycle.py # 生命周期健壮性测试
│   ├── test_sentence_recognizer.py # 一句话识别测试
│   └── test_file_recognizer.py     # 录音文件识别测试
├── pyproject.toml                  # 包定义
├── setup.py                        # 兼容安装
└── .gitignore

常见问题

APPID 和 SDKAppID 有什么区别？

APPID（如 13xxxxxxxx）：腾讯云账号级别的 ID，用于 WebSocket URL 路径；国内站从 CAM 密钥管理获取，国际站见 Tencentcloud 控制台「账号信息」
SDKAppID（如 14xxxxxxxx）：TRTC 应用级别的 ID，用于鉴权（SDK 自动填入 URL query 的 sdkappid）；国内站从 TRTC 控制台获取，国际站从 console.trtc.io 获取

UserSig 是什么？

UserSig 是基于 SDKAppID 和 SDK 密钥计算的签名，用于 TRTC 服务鉴权。SDK 会自动生成，无需手动计算。详见鉴权文档。

signature 参数怎么计算？

根据协议，signature 与 usersig 的值都等于 UserSig，SDK 内部自动处理，用户无需关心。

支持哪些音频格式？

实时语音识别：支持 PCM 格式（voice_format=1），建议 16kHz、16bit、单声道
一句话识别：支持 wav、pcm、ogg-opus、mp3、m4a，音频时长 ≤ 60s，文件 ≤ 3MB
录音文件识别：支持 wav、ogg-opus、mp3、m4a，本地文件 ≤ 5MB，URL ≤ 1GB / ≤ 12h

License

MIT License

FilesExpand file tree

v2_protocol.md

Latest commit

History

v2_protocol.md

File metadata and controls

TRTC-ASR Python SDK

安装

快速开始

一句话识别

录音文件识别

前提条件

协议说明

WebSocket 连接

鉴权方式

请求参数

实时识别响应

说话人分离（实时）

VAD 调优（noise_threshold / vad_level）

一句话识别接口

鉴权方式

URL 请求参数

请求体参数（JSON）

录音文件识别接口

创建任务：CreateRecTask

请求体参数（JSON）

响应

查询结果：DescribeTaskStatus

请求体参数（JSON）

响应（TaskStatus）

凭证获取

配置项

引擎模型

示例

项目结构

常见问题

APPID 和 SDKAppID 有什么区别？

UserSig 是什么？

signature 参数怎么计算？

支持哪些音频格式？

License