实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考输入在线媒体流开始输入在线媒体流 StartRelayStream
复制全文
下载 pdf开始输入在线媒体流 StartRelayStream
文档反馈
问问助手使用说明
前提条件
相关操作
注意事项
- 请求频率：QPS 不得超过 150。
- 任务生效时间限制：调用本接口启动推送任务后最长运行 72 小时，到期后将自动停止，并通过回调告知具体信息。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=StartRelayStream&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：StartRelayStream
接口名称。当前 API 的名称为 StartRelayStream。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：66****cf
应用 ID。根据推送目标不同，AppId 要求如下：
- 推送至 RTC 房间：必须为 RTC 的应用 ID。
- 推送至 WTN：可使用 RTC 的应用 ID 或 WTN 的应用 ID。
- 如何获取：
- RTC 应用 ID：可在 RTC 控制台获取。
- WTN 应用 ID：可在 WTN 控制台获取。
Token String 必选 示例值：00****f80
鉴权凭证。用于校验调用者的合法性，需要你自己生成。
Token 的生成算法需匹配所选 AppId 类型：
- 若使用 RTC 的 AppId：请参见使用 Token 完成鉴权。
- 若使用 WTN 的 AppId：请参见接口鉴权。
TaskId String 可选 示例值：Task1
输入在线媒体流任务 ID。
由您自定义，用于标识和管理（更新、停止）该任务。
- 命名规范：符合正则表达式 [a-zA-Z0-9_@\-\.]{1,128}。
- 唯一性规则：在同一个 AppId 和 RoomId 组合下，TaskId 必须唯一。
任务运行中，使用相同 TaskId 重复调用该接口，系统将返回提示而非报错。
注意
仅当将流推送至 RTC 房间时必填。
RoomId String 可选 示例值：Room1
在线媒体流需要被推送至的目标 RTC 房间的 ID。
注意
仅当将流推送至 RTC 房间时必填。
UserId String 可选 示例值：User1
注意
仅当将流推送至 RTC 房间时必填。
WtnStreamId String 可选 示例值：wtn_live_stream_01
自定义 WTN 流的 ID，用于在 WTN 网络中唯一标识该流。
仅支持中英文字母和数字，不支持 _、- 等任何特殊字符。
注意
仅当将流推送至 WTN 时必填。
Control Object 必选 示例值：-
配置在线媒体流的流媒体地址、媒体类型、流处理模式、视频参数等。
StreamUrl String 必选 示例值：rtmp://xxx
在线流媒体地址。
- 支持的媒体格式为：hls、rtmp、mp4、flv、dash、ts 或 mp3。
- 如源流为海外，建议联系技术支持，以保障最佳体验。
MediaType Integer 可选 示例值：0
媒体类型。
- 0（默认值）：音视频。
- 1：音频。采用此选项时，必须是 AAC 或 Opus 编码。
- 2：视频。
StreamMode Integer 可选 示例值：0
流处理模式。
- 0（默认值）：转码。采用此选项时，原视频编码方式必须是 H.264 或 ByteVC1。
- 1：转封装。采用此选项时，原视频编码方式必须是 H.264。转封装时，源流的视频关键帧间隔若过大，会影响 RTC 体验，建议 1s，但最大不超过 5s。
StartTimeStamp Integer 可选 示例值：0
任务定时启动的 Unix 时间戳（秒），用于定时播放。
默认为 0，表示立即启动。
Loop Boolean 可选 示例值：false
是否循环播放，仅对源流为点播流时生效。默认为 false（不循环）。
VideoWidth Integer 可选 示例值：640
视频宽度。当 StreamMode 为 0（转码）时必填。
单位为像素，范围为 [16, 1920]，必须是偶数，值为奇数时自动调整为偶数。
VideoHeight Integer 可选 示例值：480
视频高度，转码时必填。
单位为像素，范围为 [16, 1920]，必须是偶数，值为奇数时自动调整为偶数。
FrameRate Integer 可选 示例值：15
发送帧率，值的范围为 [1，30]，默认值为 15，转码时生效。
Bitrate Integer 可选 示例值：6000
最大发送码率，单位为 Kbps，不填则不限制，转码时生效。
IsPause Boolean 可选 示例值：false
是否暂停播放媒体流源文件：
- true：暂停播放媒体流源文件。
- false（默认值）：播放媒体流源文件。
- 在暂停状态下，不会触发 MaxIdleTime 任务空闲超时时间停止任务，因此暂停时也会正常计费。如果不再需要输入在线媒体流，可直接调用StopRelayStream 接口结束播放任务。
注意
该功能仅当媒体流为点播流且 StreamMode=0时生效。
DataStreamOptions Object 可选 示例值：-
点播数据流回调播放进度信息配置。
注意
该功能仅当媒体流为点播流时生效。
Enable Boolean 可选 示例值：false
是否通过数据流回调播放进度信息。
- true：开启。
- false（默认值）：关闭。
- 开启该功能后，RTC 按照你设置的 IntervalTime 定期通过 向房间内所有其他用户发送播放进度信息。发送内容为二进制消息，使用 protobuf 编码，解析后的格式如下：
message PositionData {
// 点播文件时长，单位为秒。
int32 duration = 1;
// 点播文件当前播放进度，单位为秒。
int32 position = 2;
// 发布者 UserId
string uid = 3;
}
IntervalTime Integer 可选 示例值：500
回调播放进度信息间隔，取值范围为 [200, 2000]，单位为毫秒，默认值为 500。
Volume Integer 可选 示例值：100
在线媒体流播放音量，范围是 [0, 400]，单位为 %。
- 0：静音
- 100（默认值）：原始音量。
- 400：原始音量的 4 倍。
MaxIdleTime Integer 可选 示例值：300
任务的空闲超时时间。超过此时间后，任务自动终止。取值范围为 [5, 600] ，单位为秒，默认值为 300。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
请求示例
POST https://rtc.volcengineapi.com?Action=StartRelayStream&Version=2023-11-01
{
"AppId": "66****3cf",
"BusinessId": "BD***23",
"RoomId": "Room1",
"TaskId": "Task1",
"UserId": "user1",
"Token": "001****80",
"MaxIdleTime": 300,
"Control" : {
"StreamUrl": "rtmp://xxx",
"MediaType": 0,
"StreamMode": 0,
"StartTimeStamp": 0,
"Loop": false,
"VideoWidth": 640,
"VideoHeight": 480,
"FrameRate": 15,
"Bitrate": 6000
}
}
返回示例
{
"Result": "ok",
"ResponseMetadata": {
"RequestId": "20230604110420",
"Action": "StartRelayStream",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
请求示例
POST https://rtc.volcengineapi.com?Action=StartRelayStream&Version=2023-11-01
{
"AppId": "661e****543cf",
"WtnStreamId": "wtn01",
"Token": "your_rtc_token",
"MaxIdleTime": 300,
"Control": {
"StreamUrl": "http://example.com/live/news.flv",
"StreamMode": 1,
"MediaType": 0
}
}
返回示例
{
"ResponseMetadata": {
"RequestId": "20230604110420****100232280022D31",
"Action": "StartRelayStream",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
},
"Result": "ok"
}
请求示例
POST https://rtc.volcengineapi.com?Action=StartRelayStream&Version=2023-11-01
{
"AppId": "your_wtn_appId",
"WtnStreamId": "wtn01",
"Token": "your_wtn_token",
"MaxIdleTime": 300,
"Control": {
"StreamUrl": "http://example.com/live/news.flv",
"StreamMode": 1,
"MediaType": 0
}
}
返回示例
{
"ResponseMetadata": {
"RequestId": "20230604110420****100232280022D31",
"Action": "StartRelayStream",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
},
"Result": "ok"
}
错误码
最近更新时间：2026.09.28 10:19:27
这个页面对您有帮助吗？
有用
有用
无用
无用