互动白板
视频服务与安全产品捉虫活动邀您参加！> HOT
文档中心>互动白板>服务端 API>白板推流相关接口>开始白板推流

开始白板推流

最近更新时间：2024-03-12 01:56:22

我的收藏

本页目录：

1. 接口描述

接口请求域名： tiw.tencentcloudapi.com 。

发起一个白板推流任务

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：StartWhiteboardPush。
Version 是 String 公共参数，本接口取值：2019-09-19。
Region 是 String 公共参数，详见产品支持的 地域列表。
SdkAppId 是 Integer 客户的SdkAppId
示例值：1400000001
RoomId 是 Integer 需要推流的白板房间号，取值范围: (1, 4294967295)。

1. 在没有指定GroupId的情况下，白板推流默认以RoomId的字符串表达形式作为IM群组ID（比如RoomId为1234，则IM群组ID为"1234"），并加群进行信令同步，请在开始推流前确保相应IM群组已创建完成，否则会导致推流失败。
2. 在没有指定TRTCRoomId和TRTCRoomIdStr的情况下，默认会以RoomId作为白板流进行推流的TRTC房间号。
示例值：12345
PushUserId 是 String 用于白板推流服务进入白板房间的用户ID。在没有额外指定IMAuthParam和TRTCAuthParam的情况下，这个用户ID同时会用于IM登录、IM加群、TRTC进房推流等操作。
用户ID最大长度不能大于60个字节，该用户ID必须是一个单独的未同时在其他地方使用的用户ID，白板推流服务使用这个用户ID进入房间进行白板音视频推流，若该用户ID和其他地方同时在使用的用户ID重复，会导致白板推流服务与其他使用场景帐号互踢，影响正常推流。
示例值：tic_push_12345_xxx
PushUserSig 是 String 与PushUserId对应的IM签名(usersig)。
示例值：eJwtjb0OgjAAhN*lK4a0tcVC4iDGkIg-g7K4NEiLViLUUsFgfHcRmS733eXuDY6b
Whiteboard 否 Whiteboard 白板参数，例如白板宽高、背景颜色等
AutoStopTimeout 否 Integer 自动停止推流超时时间，单位秒，取值范围[300, 259200], 默认值为1800秒。

当白板超过设定时间没有操作的时候，白板推流服务会自动停止白板推流。
示例值：300
AutoManageBackup 否 Boolean 对主白板推流任务进行操作时，是否同时同步操作备份任务
示例值：false
Backup 否 WhiteboardPushBackupParam 备份白板推流相关参数。

指定了备份参数的情况下，白板推流服务会在房间内新增一路白板画面视频流，即同一个房间内会有两路白板画面推流。
PrivateMapKey 否 String TRTC高级权限控制参数，如果在实时音视频开启了高级权限控制功能，必须提供PrivateMapKey才能保证正常推流。
VideoFPS 否 Integer 白板推流视频帧率，取值范围[0, 30]，默认20fps
示例值：15
VideoBitrate 否 Integer 白板推流码率， 取值范围[0, 2000]，默认1200kbps。

这里的码率设置是一个参考值，实际推流的时候使用的是动态码率，所以真实码率不会固定为指定值，会在指定值附近波动。
示例值：1200
AutoRecord 否 Boolean 在实时音视频云端录制模式选择为 指定用户录制 模式的时候是否自动录制白板推流。

默认在实时音视频的云端录制模式选择为 指定用户录制 模式的情况下，不会自动进行白板推流录制，如果希望进行白板推流录制，请将此参数设置为true。

如果实时音视频的云端录制模式选择为 全局自动录制 模式，可忽略此参数。
示例值：false
UserDefinedRecordId 否 String 指定白板推流这路流在音视频云端录制中的RecordID，指定的RecordID会用于填充实时音视频云端录制完成后的回调消息中的 "userdefinerecordid" 字段内容，便于您更方便的识别录制回调，以及在点播媒体资源管理中查找相应的录制视频文件。

限制长度为64字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。

此字段设置后，不管AutoRecord字段取值如何，都将自动进行白板推流录制。

默认RecordId生成规则如下：
urlencode(SdkAppID_RoomID_PushUserID)

例如：
SdkAppID = 12345678，RoomID = 12345，PushUserID = push_user_1
那么：RecordId = 12345678_12345_push_user_1
示例值：12345678_12345_push_user_1
AutoPublish 否 Boolean 在实时音视频旁路推流模式选择为指定用户旁路模式的时候，是否自动旁路白板推流。

默认在实时音视频的旁路推流模式选择为 指定用户旁路 模式的情况下，不会自动旁路白板推流，如果希望旁路白板推流，请将此参数设置为true。

如果实时音视频的旁路推流模式选择为 全局自动旁路 模式，可忽略此参数。
示例值：false
UserDefinedStreamId 否 String 指定实时音视频在旁路白板推流这路流时的StreamID，设置之后，您就可以在腾讯云直播 CDN 上通过标准直播方案（FLV或HLS）播放该用户的音视频流。

限制长度为64字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。

此字段设置后，不管AutoPublish字段取值如何，都将自动旁路白板推流。

默认StreamID生成规则如下：
urlencode(SdkAppID_RoomID_PushUserID_main)

例如：
SdkAppID = 12345678，RoomID = 12345，PushUserID = push_user_1
那么：StreamID = 12345678_12345_push_user_1_main
示例值：12345678_12345_push_user_1_main
ExtraData 否 String 内部参数，不需要关注此参数
TRTCRoomId 否 Integer TRTC数字类型房间号，取值范围: (1, 4294967295)。

在同时指定了RoomId与TRTCRoomId的情况下，优先使用TRTCRoomId作为白板流进行推流的TRTC房间号。

当指定了TRTCRoomIdStr的情况下，此字段将被忽略。
示例值：12345
TRTCRoomIdStr 否 String TRTC字符串类型房间号。

在指定了TRTCRoomIdStr的情况下，会优先使用TRTCRoomIdStr作为白板流进行推流的TRTC房间号。
示例值：wbpush-12345
IMAuthParam 否 AuthParam IM鉴权信息参数，用于IM鉴权。
当白板信令所使用的IM应用与白板应用的SdkAppId不一致时，可以通过此参数提供对应IM应用鉴权信息。

如果提供了此参数，白板推流服务会优先使用此参数指定的SdkAppId作为白板信令的传输通道，否则使用公共参数中的SdkAppId作为白板信令的传输通道。
TRTCAuthParam 否 AuthParam TRTC鉴权信息参数，用于TRTC进房推流鉴权。
当需要推流到的TRTC房间所对应的TRTC应用与白板应用的SdkAppId不一致时，可以通过此参数提供对应的TRTC应用鉴权信息。

如果提供了此参数，白板推流服务会优先使用此参数指定的SdkAppId作为白板推流的目标TRTC应用，否则使用公共参数中的SdkAppId作为白板推流的目标TRTC应用。
TRTCEnterRoomMode 否 String 指定白板推流时推流用户进TRTC房间的进房模式。默认为 TRTCAppSceneVideoCall

TRTCAppSceneVideoCall - 视频通话场景，即绝大多数时间都是两人或两人以上视频通话的场景，内部编码器和网络协议优化侧重流畅性，降低通话延迟和卡顿率。
TRTCAppSceneLIVE - 直播场景，即绝大多数时间都是一人直播，偶尔有多人视频互动的场景，内部编码器和网络协议优化侧重性能和兼容性，性能和清晰度表现更佳。
示例值：TRTCAppSceneVideoCall
GroupId 否 String 白板进行信令同步的 IM 群组 ID。
在没有指定GroupId的情况下，白板推流服务将使用 RoomId 的字符串形式作为同步白板信令的IM群组ID。
在指定了GroupId的情况下，白板推流将优先GroupId作为同步白板信令的群组ID。请在开始推流前确保指定的IM群组已创建完成，否则会导致推流失败。
示例值：12345

3. 输出参数

参数名称 类型 描述
TaskId String 推流任务Id
示例值：0c69baivvc3lp8t4f80b
Backup String 备份任务结果参数
注意：此字段可能返回 null，表示取不到有效值。
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 开始白板推流

创建一个白板推流任务

输入示例

POST / HTTP/1.1
Host: tiw.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartWhiteboardPush
<公共请求参数>

{
    "PushUserId": "tic_push_user_1203_141551",
    "PushUserSig": "usersig_of_<tic_push_user_1203_141551>",
    "RoomId": "1203",
    "SdkAppId": "1400000001"
}

输出示例

{
    "Response": {
        "Backup": "{\"RequestId\":\"8e9b2bc4-ec7f-46cd-823b-66676e2375f8\",\"TaskId\":\"052lfmu5uc3lp0rrqvvb\"}",
        "RequestId": "eac6b301-a322-493a-8e36-83b295459397",
        "TaskId": "bj0mt2l23osdj300hl30"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

错误码 描述
AuthFailure CAM签名/鉴权错误。
InvalidParameter.BodyParameterTypeUnmatched 参数类型不匹配。
InvalidParameter.InvalidExtra 额外指定的特殊功能不存在。
InvalidParameter.RecordParameter 实时录制参数格式不正确。
InvalidParameter.SdkAppIdNotFound SdkAppId不存在或格式错误。
LimitExceeded.TaskConcurrency 转码或录制任务并发数量超过限制，请参考错误描述或稍后重试。
ResourceInUse.RecordUserId 实时录制任务录制用户已被其他录制任务使用。
ResourceUnavailable.NotRegistered 未开通互动白板。
ResourceUnavailable.ServiceExpired 账户欠费或者互动白板服务已过期。
UnauthorizedOperation.SdkAppId SdkAppId不存在或者SdkAppId与当前腾讯云账号不对应。
中国站
文档反馈
文档活动
message-icon联系我们
目录