本文档 API 接口为最新版本接口,后续相关功能的新增都会在此更新,推荐使用最新版本接口。旧版接口文档请参考历史版本。
在实时音视频通话场景中,例如在线教育或远程会议,你可以通过调用此接口实现网页音视频内容的推送至 RTC 房间
通过设定应用标识、业务标识、房间 ID、任务 ID、用户 ID 以及网页源地址等信息,你能够将指定的网页内容转推到RTC房间。此外,通过配置你可以控制输出流的视频参数,如分辨率、帧率和码率。接口还提供了页面可用性监控和事件通知配置,以增强稳定性和交互性。
你提供的源地址需要兼容 Chrome 浏览器,浏览器版本为 117.0.5938.92。
在首帧发送完成和任务结束时,你在控制台上设置的回调地址会收到相关回调。有关回调结果的详细说明,参看 Webcast。
请求频率:QPS 不得超过 150。
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Action | String | 是 | StartWebcast | 接口名称。当前 API 的名称为 StartWebcast 。 |
Version | String | 是 | 2023-11-01 | 接口版本。当前 API 的版本为 2023-11-01 。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
AppId | String | 是 | 661e****543cf | 你的音视频应用的唯一标志,参看获取 AppId。 |
BusinessId | String | 否 | B****23 | 业务标识 |
RoomId | String | 是 | Room1 | 向指定 RTC 房间推送网页音视频内容,房间 ID 是房间的唯一标志 |
TaskId | String | 是 | Task1 | 任务 ID。你必须对每个云录屏任务设定 TaskId,且在后续结束任务时也须使用该 TaskId。
关于 TaskId 及以上 Id 字段的命名规则符合正则表达式: TaskId 重复调用开始接口不会导致请求失败,BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly 。 |
UserId | String | 是 | User1 | 推送网页音视频内容的用户对应的 UserId。不能与房间中其他用户的 ID 重复,否则先进房的用户会被移出房间。 建议添加有规律的前缀,避免重复。例如, webcast_ 。 |
SourceURL | String | 是 | https://xxx.xxx.xxx | 需要转推的网页地址,可以携带自定义的 queryParams 来鉴权等,总体长度不超过 1024。 |
VideoSolutions | Object[] | 否 | - | 输出流的视频参数。网页渲染分辨率为输入最大视频流的分辨率。该值为空时按默认值填充一路。
|
Width | Integer | 否 | 1280 | 视频宽度,单位为像素,范围为 [50,1920] ,默认值为 1280 。必须是偶数,值为奇数时自动调整为偶数。 |
Height | Integer | 否 | 720 | 视频高度,单位为像素,范围为 [50,1080] ,默认值为 720 。必须是偶数,值为奇数时自动调整为偶数。 |
FrameRate | Integer | 否 | 15 | 发送帧率,单位为 fps ,范围为[1,60] ,默认值为 15 。帧率和码率设置建议参照视频发布参数对照表以获取最佳体验。 |
Bitrate | Integer | 否 | 0 | 最大发送码率,取值范围为 [0,10000] ,单位为 Kbps ,默认值 0 ,为 0 时表示自适应码率。 |
MaxRunningTime | Integer | 否 | 3600 | 最大运行时间,超过此时间后,任务自动终止。取值范围为 [10,86400] ,单位为秒,默认值为 86400 。不填时自动调整为默认值。 |
MonitorConfig | Object | 否 | - | 页面可用性监控配置 |
FreezeCheckInterval | Integer | 否 | 5 | 对页面内容是否无变化的检测间隔。取值范围为
|
BlankCheckInterval | Integer | 否 | 5 | 对页面是否白屏的检测间隔。取值范围为
|
CrashCheckInterval | Integer | 否 | 5 | 对页面 JS 线程是否崩溃/卡死的检测间隔。 取值范围为 Status=5,Reason="PageCrash" 。 |
EventNotifyConfig | Object | 否 | - | 页面事件通知配置。若需要避免未载入完成时的不完整页面被采集,可以启用此配置。 |
EnableEventNotify | Boolean | 否 | true | 是否启用页面主动事件通知,。
当页面判断资源加载完成之后调用 当启用页面主动事件通知后,你可以参考以下示例代码来通知采集开始。
|
StartTimeout | Integer | 否 | 2 | 启用页面主动事件通知后,等待开始事件的超时时间。取值范围为
|
本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 Result
仅在请求成功时返回 ok
,失败时为空。
POST https://rtc.volcengineapi.com?Action=StartWebcast&Version=2023-11-01 { "AppId": "661e****543cf", "RoomId": "Room1", "TaskId": "Task1", "UserId": "user1", "SourceURL": "https://xxx.xxx.xxx", "VideoSolutions": [ { "Width": 1280, "Height": 720, "FrameRate": 30 } ], "MonitorConfig": { "FreezeCheckInterval": 3, "BlankCheckInterval": 5, "CrashCheckInterval": 5 }, "EventNotifyConfig": { "EnableEventNotify": false, "StartTimeout": 0 }, "MaxRunningTime": 60 }
{ "ResponseMetadata": { "RequestId": "20230****10420", "Action": "StartWebcast", "Version": "2023-11-01", "Service": "rtc", "Region": "cn-north-1" }, "Result": "ok" }
您可访问公共错误码,获取更多错误码信息。