边录边转写（实时 ASR）接入指南

更新日期：2026-10-26。API 根地址：https://work.zingyang.com/api。

本指南依据当前平台签发服务与 iOS 实际调用方整理。实时音频由客户端通过 WebSocket 发往腾讯云；平台负责校验用户、租户、套餐并签发短时连接地址。它不同于上传文件后识别的短语音 ASR，也不是 SSE 对话接口。

1. 接入前提

• 已登录，具有有效的 X-Access-Token。
• 每次签发带 X-Tenant-Id：租户存在、启用且在有效期内，当前用户为有效成员。
• 租户拥有有效的 TALK_AI_PROCESS_MINUTES 权益，且通过至少 1 个计量单位的余量检查；无限额权益按平台规则处理。管理员身份也不绕过此检查。
• 服务端已开启实时转写，腾讯 ASR 凭据、对应产品及供应商额度可用；若配置了账号允许名单，还须命中名单。
• 客户端取得麦克风权限，并明确告知音频将发送到腾讯云、取得用户同意；尊重仅 Wi-Fi 上传设置。

计量边界：当前签发入口仅检查套餐准入，没有在此预扣额度，也没有按这条 WebSocket 实际时长结算或在余量耗尽时主动断开。 签发成功不等于完整实时用量闭环；不能将 60 秒凭证有效期理解为仅能识别 60 秒或已购买 60 秒额度。

2. 获取短时连接地址

POST /talk/v1/realtime-speech/session

无请求体，无查询参数。不接受客户端传入用户 ID、模型、腾讯密钥或签名参数。

curl --request POST \
  'https://work.zingyang.com/api/talk/v1/realtime-speech/session' \
  --header 'X-Access-Token: <平台登录token>' \
  --header 'X-Tenant-Id: <当前租户ID>' \
  --header 'Accept: application/json'

正常 App 请求使用上述平台请求头。AI 工具代用户操作时须先获得授权，并额外携带 X-Zing-Ai-Context: 1、X-Open-Confirm: confirmed。

成功响应为平台标准结构，数据从 result 读取；不要使用旧文档中的 data：

{
  "success": true,
  "code": 200,
  "message": "",
  "result": {
    "url": "wss://asr.cloud.tencent.com/asr/v2/APP_ID?SIGNED_QUERY",
    "voice_id": "00000000-0000-4000-8000-000000000001",
    "expires_at": 1792972860
  },
  "timestamp": 1792972800000
}

以上地址与时间仅为结构示例，不可直接使用。

响应带 Cache-Control: no-store。完整 URL 是敏感短时凭证，不写日志、分析平台、剪贴板或持久缓存，不转发给其他用户。客户端不接触 SecretKey，也不自行实现签名。同租户同用户签发间隔至少 1 秒；没有客户端幂等键。

3. 建立连接与发送音频

1. 检查签发请求 HTTP 状态、success、code，确认 result.url 为 wss、主机为 asr.cloud.tencent.com、路径以 /asr/v2/ 开头且凭证未过期。
2. 用完整 URL 建立 WebSocket。平台 token 和租户头只发给平台接口，不要转发到腾讯云。
3. 等待腾讯首个响应，确认 code == 0 后才开始发送音频；现有 iOS 调用方设置 10 秒握手截止时间。
4. 按录音节奏发送二进制 PCM 帧，并持续接收识别结果。
5. 结束时先发送剩余音频，再发送文本帧 {"type":"end"}；等到 final == 1 后关闭。现有 iOS 最多等待 8 秒，超时也释放连接。

当前签发参数固定为 engine_model_type=16k_zh_en_speaker、voice_format=1、result_mod=1、speaker_diarization=1、enable_speaker_context=0。客户端不能更改已签名参数。

不要直接发送麦克风产生的 44.1/48 kHz Float32 数据，也不要直接发送 m4a/mp3 压缩文件。先重采样并转换格式。当前 iOS 待发送队列最多约 5 秒；慢网应停止云连接并明确提示，不能无限缓存或高速补发整段历史音频。

4. 解析实时文本和说话人

WebSocket 消息使用腾讯 ASR V2 协议，不是平台的 Result 包装；这里的 code=0 才表示供应商成功。当前客户端读取 sentences.sentence_list：

{
  "code": 0,
  "final": 0,
  "sentences": {
    "sentence_list": [
      {
        "sentence_id": 0,
        "sentence": "我们开始今天的会议。",
        "sentence_type": 1,
        "speaker_id": 0,
        "start_time": 0,
        "end_time": 1800
      }
    ]
  }
}

已有 iOS 以当前录音轮次隔离回调，按 sentence_id 更新并排序。不同会话的同一个 speaker_id 不保证同一人；不要据此自动绑定联系人、人物或声纹身份。可选的 /realtime-speech/candidates 是另一项暂定人物候选能力，不是获取文本的必需步骤，本指南不把它当作正式身份识别。

供应商字段语义可对照腾讯云实时语音识别 V2 官方协议；平台签发参数和当前客户端解析以上述实际实现为准。

5. 暂停、续录、取消与保存

• 暂停时结束当前流；续录重新申请凭证、建立新会话。保留前文，使用新的轮次标识，忽略旧连接迟到的回调。
• 用户退出、取消、切换账号或租户时，关闭旧连接并停止发送；不能复用旧租户的 URL。
• 断线重连需要新凭证；当前没有断点续传或自动补转保证。失败期间可能存在文本空档，应如实提示。
• 具备本机识别能力的客户端可以按已获授权切回本机转写，并显示实际来源；不可通过其他云接口绕过平台的套餐拒绝。
• 此接口不会创建会议记录、登记 COS 文件或保存最终转写正文。完整录音的保存、上传和会后处理仍走原有业务链路；需要持久化文件时参考统一 COS 上传，不要把实时签发接口当作文件上传接口。

6. 错误处理

签发阶段同时检查 HTTP 状态、平台数值 code、success 和 message。Talk 业务错误可能在 result.code 附带字符串错误码；共享鉴权或套餐异常不保证有这个扩展字段。

现有客户端对腾讯 4004 提示供应商额度不可用，对 6001 提示跨境能力未开通；这两者不等于平台套餐 402。平台签发成功也不保证供应商握手、余额或识别成功。网络超时可能发生在签发完成之后，每次重试均可能得到新会话，避免无限自动重试。

7. 验证范围

已核对 TalkRealtimeSpeechController#session → TalkRealtimeSpeechService#issue/sign → AiInvocationAccess#check、TalkResponseAdvice，以及实际调用方 TencentSpeechSession.prepare/finish、TencentSpeechMessage、LiveTranscript.applyTencent。

本次仅发布接入文档与静态站资源，未签发生产语音凭证、发送生产音频或进行付费识别。公开文档可访问不代表所有租户均已开通，也不代表当前实时计量已具备完整结算闭环。

• 上传文件后进行短语音 ASR
• 本人租户列表与切换
• 文件上传与 COS