服务端接口
业务服务端对接 TiRTC 云端 tirtc-server-api（TGV1-HMAC-SHA256 鉴权）， 用于查询设备通话状态，并为设备侧 TiRtcWhipConnect 签发 WHIP peer_id（service_desc）与 Bearer token。
tirtc-server-api 地址：https://api-tirtc.tange365.com。
TGV1-HMAC-SHA256 签名
与探鸽云端 OpenAPI 服务端签名一致，详见 服务端API接口签名算法Demo。
查询设备微信 VoIP 通话状态：GET /v1/device/wxvoip-call-status
用途：业务服务端在发起呼叫前，查询指定设备是否处于微信 VoIP 连接建立中、呼叫/振铃中或已接通状态。该接口使用 TGV1-HMAC-SHA256 鉴权，仅允许查询当前鉴权应用所关联产品下存在且未过期的设备。
状态上报和清理存在延迟。查询结果适合用于降低重复呼叫的概率，不能作为无竞态的设备预占机制。
请求
Headers
| Header | 说明 |
|---|---|
Authorization | TGV1 鉴权行 |
X-Tg-Algorithm | 算法名 |
X-Tg-Date | 请求时间（UTC） |
X-Tg-App-Id | 应用 ID，须与凭证 app_id 一致 |
X-Tg-Content-Sha256 | 空请求体的 SHA-256 |
X-Tg-Signed-Headers | 参与签名的头名列表 |
以上与 TGV1 相关的头：格式与计算见 TGV1-HMAC-SHA256 签名。
Query 参数
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
device_id | string | 是 | 设备 ID。设备须存在、未过期，且其所属产品已关联到当前鉴权应用。 |
响应
成功响应示例：
{
"code": 0,
"message": "ok",
"data": {
"in_call": true
}
}| 字段 | 类型 | 说明 |
|---|---|---|
data.in_call | boolean | true 表示设备处于连接建立中、呼叫/振铃中或已接通状态；false 表示当前状态存储中未发现上述会话，不代表设备已被原子预占，也不保证此刻不会有新的呼叫并发发起。状态上报存在延迟或失败时，也可能短时间未查询到已经开始的会话。 |
主要业务错误：
code | 说明 |
|---|---|
40003 | 缺少 device_id 等请求参数错误 |
40302 | 设备所属产品未关联到当前鉴权应用 |
40304 | 设备已过期 |
40403 | 设备不存在 |
50000 | 查询通话状态时发生服务端内部错误 |
签发微信VoIP通话凭证：POST /v1/token/wxvoip
用途：根据当前微信VoIP通话会话与设备媒体能力，向探鸽平台申请 peer_id 与 token，由业务服务端在 wxa_join_voip_room 中一并下发给设备。
请求
Headers
| Header | 说明 |
|---|---|
Content-Type | application/json |
Authorization | TGV1 鉴权行 |
X-Tg-Algorithm | 算法名 |
X-Tg-Date | 请求时间（UTC） |
X-Tg-App-Id | 应用 ID，须与凭证 app_id 一致 |
X-Tg-Content-Sha256 | 请求体 SHA-256（十六进制小写） |
X-Tg-Signed-Headers | 参与签名的头名列表 |
以上与 TGV1 相关的头：格式与计算见 TGV1-HMAC-SHA256 签名。
Body（JSON）
| 字段 | 类型 | 说明 |
|---|---|---|
wx_session_key | string | 必填。微信 join_voip_room 通知中的 session_key |
wx_room_id | string | 必填。微信通知中的 room_id |
wx_session_token | string | 必填。微信通知中的 server_token |
wx_app_id | string | 必填。小程序 appId |
device_id | string | 必填。设备标识，须与下发推送中的设备身份一致 |
wx_model_id | string | 必填（示例要求配置）。微信硬件设备的微信VoIP通话模型 ID |
wx_payload | string | 可选。主叫透传 payload；不传或省略时视为空字符串 |
calling_timeout_sec | number | 可选。振铃超时（秒），默认 30 |
no_video | boolean | 可选。纯音频时为 true |
video_mt | string | 可选兼容字段；同时设置上下行视频格式：h264 / mjpeg / none。若同时传 up_video_mt/down_video_mt 且不一致，则请求失败 |
up_video_mt | string | 设备到微信小程序方向的视频格式：h264 / h265 / mjpeg / none；不要与 video_mt 同时使用 |
down_video_mt | string | 微信小程序到设备方向的视频格式：h264 / mjpeg / none；不要与 video_mt 同时使用 |
down_video_rotation | number | 可选。微信小程序到设备方向的视频流方向，仅支持 0、1、2，默认 0。0：使用微信 SDK 默认行为；1：订阅 0° 正向流，微信侧须同时设置 encodeVideoRotation=1；2：明确保持旋转流 |
screen_width / screen_height | number | 非纯音频时的屏幕宽高 |
video_res_mode | string | 可选。下行视频分辨率模式：auto / fit_screen / fill_screen；不传等同于 auto |
down_audio_mt | string | 微信小程序到设备方向的音频编码：alaw / amr / opus；不传默认 alaw |
audio_rate | number | 必填。仅支持 8000、16000 |
audio_channels | number | 必填。仅支持 1、2 |
业务服务端通常在收到微信 join_voip_room 后，结合微信通知字段与设备事先上报的媒体能力组装上述 JSON。
下行视频分辨率模式
| 模式 | 行为 |
|---|---|
auto | 透传微信下行视频，不进行缩放或裁剪 |
fit_screen | 在 auto 协商得到的微信视频上二次缩放，使其等比适配屏幕边界 |
fill_screen | 在 auto 协商得到的微信视频上二次处理，通过等比缩放和居中裁剪铺满屏幕 |
auto
不传 video_res_mode 或传 auto 时，服务端不缩放、不裁剪，直接向设备透传微信下行视频。向微信协商的分辨率由屏幕大小决定：
screen_width × screen_height <= 480 × 240：订阅固定长边320。横屏为320×240，竖屏为240×320。screen_width × screen_height > 480 × 240：由微信自适应下发可变分辨率，最大长边640。横屏最大为640×480，竖屏最大为480×640。
fit_screen
先按 auto 规则取得微信下行视频，再以 screen_width × screen_height 为最大边界进行等比缩小：
- 保持源视频宽高比，不拉伸、不裁剪、不补黑。
- 只缩小，不放大。
- 输出宽高向下对齐为偶数。
- 微信源分辨率变化时，重新计算输出尺寸并重建缩放器和 MJPEG 编码器。
- 缩放器或编码器初始化失败时丢弃当前帧，不回退下发原尺寸帧。
fill_screen
先按 auto 规则取得微信下行视频，再等比缩放并居中裁剪；输出尺寸精确等于 screen_width × screen_height：
- 保持源视频宽高比，不拉伸、不补黑。
- 允许放大视频，并裁掉超出屏幕宽高比的上下或左右区域。
- 微信源分辨率变化时，重新计算裁剪区域并重建缩放器和 MJPEG 编码器。
- 缩放器或编码器初始化失败时丢弃当前帧，不回退下发原尺寸帧。
例如，微信下发 240×320 视频，设备屏幕为 160×100：
| 模式 | 输出分辨率 | 处理结果 |
|---|---|---|
fit_screen | 74×100 | 完整保留画面，宽度不足屏幕宽度 |
fill_screen | 160×100 | 居中裁剪上下区域并铺满屏幕 |
当前限制：
fit_screen和fill_screen仅支持下行MJPEG，并要求同时传入screen_width和screen_height。fill_screen允许放大视频，并会裁掉超出屏幕宽高比的上下或左右区域；screen_width和screen_height必须为偶数。- 两种模式都不旋转画面。微信下行视频方向仍由微信视频协商决定。
响应
HTTP 200 且业务成功时，正文为统一包装，示例形态：
{
"code": 0,
"msg": "ok",
"data": {
"peer_id": "whips://wxvoip?x_wx_session_key=...&x_device_id=...",
"token": "<Bearer token 字符串>"
}
}code !== 0：表示失败，msg含说明；勿将无效peer_id/token下发给设备。data.peer_id：即TiRtcWhipConnect(service_desc, ...)的第一个参数（完整whips://wxvoip?...URL）。data.token：即TiRtcWhipConnect(..., token, ...)的第二个参数。