实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考云录屏开启云录屏 StartWebCast
复制全文
下载 pdf开启云录屏 StartWebCast
文档反馈
问问助手调用 StartWebcast 接口，将指定网页的内容渲染成音视频流，并推送到 RTC 房间中，实现如共享 PPT、播放视频文件等效果。
- 网页源地址需要兼容 Chrome 浏览器，浏览器版本为 117.0.5938.92。
注意事项
请求频率：QPS 不得超过 150。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=StartWebcast&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：StartWebcast
接口名称。当前 API 的名称为 StartWebcast。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：66****3cf
BusinessId String 可选 示例值：B****3
RoomId String 必选 示例值：Room1
RTC 房间 ID，向该 RTC 房间推送网页音视频内容。
TaskId String 必选 示例值：Task1
任务 ID。由您自定义，用于标识和管理（更新、停止）任务。
- 命名规范：符合正则表达式 [a-zA-Z0-9_@-.]{1,128}。
- 唯一性规则：在同一个 AppId 和 RoomId 组合下，TaskId 必须唯一。
任务运行中，使用相同 TaskId 重复调用该接口，系统将返回提示而非报错。
UserId String 必选 示例值：User1
需要你自定义，用于标识推送至 RTC 房间的网页内容。发起任务后，服务端会用该 ID 作为虚拟用户加入 RTC 房间，客户端也可通过此 ID 在房间订阅该流。
注意
不能与房间中其他用户的 ID 重复。可添加有规律的前缀来避免重复。例如， webcast_。
SourceURL String 必选 示例值：https://xxx.xxx.xxx
需要转推的网页地址，可以携带自定义的 queryParams 来鉴权等，总体长度不超过 1024。
VideoSolutions Object[] 可选 示例值：-
输出流的视频参数。网页渲染分辨率为输入最大视频流的分辨率。该值为空时按默认值填充一路。
- 当设置一路流时，不会输出多路流，输出流参数与设置值相同。
- 当设置两路流时， RTC 会启动推送多路流功能，设置的两路分辨率相当于分辨率等级划分中的大流和中流的上限。
Width Integer 可选 示例值：1280
视频宽度，单位为像素，范围为 [50,1920]，默认值为 1280。必须是偶数，值为奇数时自动调整为偶数。
Height Integer 可选 示例值：720
视频高度，单位为像素，范围为 [50,1080]，默认值为 720。必须是偶数，值为奇数时自动调整为偶数。
FrameRate Integer 可选 示例值：15
Bitrate Integer 可选 示例值：0
最大发送码率，取值范围为[0,10000]，单位为 Kbps，默认值 0，为 0 时表示自适应码率。
MaxRunningTime Integer 可选 示例值：3600
最大运行时间，超过此时间后，任务自动终止。取值范围为 [10,86400]，单位为秒，默认值为 86400。不填时自动调整为默认值。
MonitorConfig Object 可选 示例值：-
页面可用性监控配置。
FreezeCheckInterval Integer 可选 示例值：5
对页面内容是否无变化的检测间隔，单位为秒。默认值为 0，表示不启用。
- 当连续两次出现检测命中时，将对页面进行刷新，并回调Status=4，Reason="PageFreeze"。
- 再次出现连续两次检测命中时，将进行任务重调度，并回调Status=5，Reason="PageFreeze"。
注意：页面无变化可能是您业务的正常场景，请谨慎评估页面实际内容情况后再开启此功能，以免任务提前退出。
BlankCheckInterval Integer 可选 示例值：5
对页面是否白屏的检测间隔，单位为秒。默认值为0，表示不启用。
- 当连续两次出现检测命中时，将对页面进行刷新，并回调Status=4，Reason="PageBlank" 。
- 再次出现连续两次检测命中时将进行任务重调度，并回调Status=5，Reason="PageBlank"。
注意：页面全白可能是您业务的正常场景，请谨慎评估页面实际内容情况后再开启此功能，以免任务提前退出。
CrashCheckInterval Integer 可选 示例值：5
对页面 JS 线程是否崩溃/卡死的检测间隔，单位为秒。默认值为 0，表示不启用。
当出现检测命中时将进行任务重调度，并回调 Status=5，Reason="PageCrash"。
EventNotifyConfig Object 可选 示例值：-
页面事件通知配置。若需要避免未载入完成时的不完整页面被采集，可以启用此配置。
EnableEventNotify Boolean 可选 示例值：true
是否启用页面主动事件通知,。
- false：页面在打开后就会开始采集，在收到 StopWebCast openAPI 请求后结束采集。
- true：在页面中注入两个 JS 函数：onWebcastStart()和 onWebcastEnd()。
当页面判断资源加载完成之后调用onWebcastStart()，控制程序才会开始进行页面内容的采集。当页面判断本次任务内容已完成时调用onWebcastEnd() 通知控制程序结束本次任务。StopWebCast openAPI 效果不变，业务可提前结束任务。其他页面内容、JS 线程的检测（若启用），将在收到 onWebcastStart()事件后才开始。
当启用页面主动事件通知后，你可以参考以下示例代码来通知采集开始。
<script> if (ready() && typeof onWebcastStart === 'function') onWebcastStart();</script>
StartTimeout Integer 可选 示例值：2
启用页面主动事件通知后，等待开始事件的超时时间，单位为秒。默认值为 0，表示不启用。仅当 EnableEventNotify 为 true 时，此参数有效。
- 当在超时时间内收到开始事件，采集功能正常运行，用户将收到 Status=1的回调。
- 当超时时间内未收到开始事件，将进行刷新，等待时间被重置，再次发生超时后将进行任务重调度。刷新时将回调 Status=4，Reason=" StartEventTimeout"。重调度时将回调 Status=5，Reason="StartEventTimeout"。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
请求示例
POST https://rtc.volcengineapi.com?Action=StartWebcast&Version=2023-11-01
{
"AppId": "66****3cf",
"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": "20230604110420",
"Action": "StartWebcast",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
},
"Result": "ok"
}
错误码
最近更新时间：2026.08.20 10:13:42
这个页面对您有帮助吗？
有用
有用
无用
无用