文档中心

自定义查询直播间信息

最近更新时间：2023.12.20 17:03:55

首次发布时间：2022.09.15 14:09:46

按需查询直播间信息，包括直播状态等直播间基础信息、外观主题等直播间基础配置、直播间内各直播频道的推拉流信息及直播间在线人数。

注意事项

请求频率：单用户请求频率限制为 120 次/分钟。

请求说明

请求方式：GET
请求地址：https://livesaas.volcengineapi.com/?Action=GetCustomActMsgAPI&Version=2020-06-01

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`GetCustomActMsgAPI`	接口名称。当前 API 的名称为 `GetCustomActMsgAPI`。
Version	String	是	`2020-06-01`	接口版本。当前 API 的版本为 `2020-06-01`。
ActivityId	Long	是	`172183460671`	直播间 ID。您可以通过 ListActivityAPI 接口查询 ID。
NeedActMsg	Integer	否	`1`	是否查询直播状态、观看地址等直播间基础信息，默认不查询。 `1`：是 `其他值`：否
NeedActBasicMsg	Integer	否	`1`	是否查询文本标签、外观主题等直播间基础配置，默认不查询。 `1`：是 `其他值`：否
NeedActStreamMsg	Integer	否	`1`	是否查询直播间内各直播频道的推拉流信息，默认不查询。 `1`：是 `其他值`：否
NeedRealTimeOnlineNumber	Integer	否	`1`	是否查询直播间在线人数（包含虚拟人气），默认不查询。 `1`：是 `其他值`：否

返回参数

参数	类型	示例值	描述
ActMsg	Object of ActMsg	`-`	直播状态、观看地址等直播间基础信息。
ActBasicMsg	Object of ActBasicMsg	`-`	文本标签、外观主题等直播间基础配置。
ActStreamMsg	Object of ActStreamMsg	`-`	直播间内各直播频道的推拉流信息。
RealTimeOnlineNumber	Object of RealTimeOnlineNumber	`-`	直播间在线人数（包含虚拟人气）。

ActMsg

参数	类型	示例值	描述
Id	Long	`172183460671`	直播间 ID。
Name	String	`直播间 A`	直播间名称。
LiveTime	Long	`1642070520`	直播间的开播时间。Unix 时间戳，单位为秒。
CoverImage	String	`https://image1.xxx`	横屏直播的封面图 URL。若通过控制台配置横屏直播封面图且配置成功，则封面图的 URL 无协议头。若通过调用 API 接口配置横屏直播封面，则封面图的 URL 有协议头。
VerticalCoverImage	String	`https://image2.xxx`	竖屏直播的封面图 URL，包含协议头。
Status	Integer	`2`	直播状态。支持以下取值： `1`：直播中 `2`：预告 `3`：回放 `4`：已结束
ViewUrl	String	`https://live.xxx.com/xxx`	直播间的观看地址。
IsLockPreview	Integer	`0`	是否锁定预告。支持以下取值： `0`：否 `1`：是
OwnerSubAccount	String	`admin@bytedance.com`	创建直播间的账号信息。返回 `admin@bytedance.com` 表示当前直播间由主账号创建。
LiveReviewStatus	Integer	`2`	直播间审核状态。支持以下取值： `1`：审核中 `2`：审核通过 `3`：审核驳回 `4`：审核归档 `5`：草稿 `6`：无需审核

ActBasicMsg

参数	类型	示例值	描述
ActivityId	Long	`172183460671`	直播间 ID。
Name	String	`直播间 A`	直播间名称。
LiveTime	Long	`1642070520`	直播间的开播时间。Unix 时间戳，单位为秒。
IsCoverImageEnable	Integer	`1`	开启直播封面。取值固定为 `1`。
CoverImageUrl	String	`//gjrfd7ferd-image.image`	横屏直播封面图的 URL。若通过控制台配置横屏直播封面图且配置成功，则封面图的 URL 无协议头。若通过调用 API 接口配置横屏直播封面，则封面图的 URL 有协议头。
IsPcBackImageEnable	Integer	`1`	是否开启 PC 端背景图和背景颜色。支持以下取值： `0`：关闭背景图 `1`：开启背景图 `2`：开启背景颜色
PcBackImageUrl	String	`//p-imagex-live18n.test.org/tos-live18n-i-fhdptwgppv.png`	PC 端背景图的 URL。当 `IsPcBackImageEnable` 取值为 `1` 时，此处为 PC 端背景图的 URL，否则为空。
IsMobileBackImageEnable	Integer	`1`	是否开启移动端背景图和背景颜色。支持以下取值： `0`：关闭背景图 `1`：开启背景图 `2`：开启背景颜色
MobileBackImageUrl	String	`//p-imagex-live18n.test.org/tos-live18n-i-fhdptwgppv.png`	移动端背景图的 URL。当 `IsMobileBackImageEnable` 取值为 `1` 时，此处为移动端背景图的 URL，否则为空。
IsPreviewVideoEnable	Integer	`1`	是否开启预告片。支持以下取值： `0`：关闭 `1`：开启
PreviewVideoVid	String	`491568852`	预告片 Vid。当 `IsPreviewVideoEnable` 取值为 `1` 时，此处为预告片 Vid，否则为空。
IsPeopleCountEnable	Integer	`0`	是否在观看页显示观看人数。支持以下取值： `0`：关闭 `1`：开启
IsHeaderImageEnable	Integer	`0`	是否开启移动端页头图。支持以下取值： `0`：关闭 `1`：开启
HeaderImageUrl	String	`//p.test.org/tos-live18n-i-fhdptwgppv.png`	移动端页头图的 URL。当 `IsHeaderImageEnable` 取值为 `1` 时，此处为移动端页头图的 URL，否则为空。
IsWatermarkImageEnable	Integer	`0`	是否在观看页显示 Logo。支持以下取值： `0`：关闭 `1`：开启
WatermarkImageUrl	String	`//p-imagex.org/tos-live18n-i-fhdptwgppv.png`	Logo 的 URL。当 `IsWatermarkImageEnable` 取值为 `1` 时，此处为 Logo 的 URL，否则为空。
IsThumbUpEnable	Integer	`1`	是否开启直播间点赞。支持以下取值： `0`：关闭 `1`：开启
ThumbUpUrl	String	`//p-imagex.png`	直播间点赞图的 URL。当 `IsThumbUpEnable` 取值为 `1` 时，此处为直播间点赞图的 URL，否则为空。
IsShareIconEnable	Integer	`1`	是否开启分享图标。支持以下取值： `0`：关闭 `1`：开启
ShareIconUrl	String	`//p-imagex-live18n.test.org/tos-live18n-i-fhdptwgppv.pn`	分享图标的 URL。当 `IsShareIconEnable` 取值为 `1` 时，此处为分享图标的 URL，否则为空。
IsCommentTranslateEnable	Integer	`-`	已废弃。
Announcement	String	`直播间信息`	直播描述。
BackgroundColor	String	`77778888`	PC 端背景颜色。遵循 RGB 色彩模型。
FontColor	String	`55557777`	字体颜色。遵循 RGB 色彩模型。
InteractionColor	String	`45784444`	PC 端互动区颜色。遵循 RGB 色彩模型。
ColorThemeIndex	String	`light`	外观主题。支持以下取值： `light`：清爽模式 `dark`：暗黑模式 `cold`：经典模式 `holiday`：传统节庆
IsCountDownEnable	Integer	`1`	是否开启倒计时。支持以下取值： `0`：关闭 `1`：开启
IsAutoStartEnable	Integer	`1`	是否开启自动开播。支持以下取值： `0`：关闭 `1`：开启
IsPCHeaderImageEnable	Integer	`1`	是否开启 PC 端页头图。支持以下取值： `0`：关闭 `1`：开启
PCHeaderImageUrl	String	`//p-imagex-fhdptwgppv.pn`	PC 端页头图的 URL。当 `IsPCHeaderImageEnable` 取值为 `1` 时，此处为 PC 端页头图的 URL，否则为空。
IsPageLimitEnable	Integer	`1`	是否开启页面限制。支持以下取值： `0`：关闭 `1`：开启
PageLimitType	String	`pc`	页面限制类型。当 `IsPageLimitEnable` 取值为 `1` 时，此处为页面限制类型，否则为空。支持以下取值： `pc`：仅 PC 端可观看 `mobile`：仅移动端可观看
IsLanguageEnable	Integer	`1`	是否开启页面语言。支持以下取值： `0`：关闭 `1`：开启
PlayerTopType	Array of String	`1`	播放器置顶的终端。支持以下取值： `0`：关闭（已废弃） `1`：PC 端 `2`：移动端
IsReplayAutoOnlineEnable	Integer	`1`	是否开启回放自动上架。支持以下取值： `0`：关闭 `1`：开启
SiteTags	Array of SiteTags	`-`	直播间分类标签信息列表。
TextSiteTags	Array of TextSiteTags	`-`	直播间文本标签信息列表。

ActStreamMsg

参数	类型	示例值	描述
LineDetails	Array of LineDetails	`-`	直播频道的推拉流信息列表。

RealTimeOnlineNumber

参数	类型	示例值	描述
RealPopularity	Integer	`2000`	直播间真实人数。
FakePopularity	Integer	`2000`	直播间虚拟人气。

SiteTags

参数	类型	示例值	描述
Name	String	`分类标签`	分类标签名称。
Value	String	`标签1`	分类标签的标签值。
Index	Integer	`0`	分类标签的索引值，用于标识分类标签在控制台展示的位置。取值范围为 [0,19]。

TextSiteTags

参数	类型	示例值	描述
Name	String	`文本标签`	文本标签名称。
Value	String	`标签2`	文本标签值。
Index	Integer	`0`	文本标签的索引值，用于标识文本标签在控制台展示的位置，取值范围为 [0,4]。

LineDetails

参数	类型	示例值	描述
LineId	Long	`123`	直播频道 ID。
LineName	String	`线路1`	直播频道名称。
MainPushInfo	Array of MainPushInfo	`-`	直播频道主流的推流地址。
BackPushInfo	Array of BackPushInfo	`-`	直播频道备流的推流地址。
ForwardInfo	Array of ForwardInfo	`-`	直播频道主流的拉流转推信息。
BackupForwardInfo	Array of BackupForwardInfo	`-`	直播频道备流的拉流转推信息。
ExpireTime	Long	`1643004493`	直播频道推流码的过期时间。

MainPushInfo

参数	类型	示例值	描述
PushPath	String	`https://example-livesaas.com/example`	推流服务器 URL。
PushUrl	String	`https://example-livesaas.com/example/livesaas?key=example`	推流完整 URL。
StreamingCode	String	`livesaas?key=example`	推流串流秘钥。

BackPushInfo

参数	类型	示例值	描述
PushPath	String	`https://example2-livesaas.com/example2`	推流服务器 URL。
PushUrl	String	`https://example2-livesaas.com/example/livesaas?key=example2`	推流完整 URL。
StreamingCode	String	`livesaas?key=example2`	推流串流秘钥。

ForwardInfo

参数类型示例值描述

PullStreamUrl String https://example-livesaas.com/example/livesaas?key=example 拉流直播拉流 URL。

参数	类型	示例值	描述
PullStreamUrl	String	`https://example-livesaas.com/example/livesaas?key=example`	拉流直播拉流 URL。
PullStreamStatus	String	`1`	拉流直播任务状态。支持以下取值： `0`：拉流任务初始化中 `1`：拉流任务运行中 `2`：拉流任务已结束
PullStreamCheckStatus	String	`1`	拉流检测状态。支持以下取值： `0`：检测中 `1`：源流未推流 `2`：正常拉流 `3`：拉流结束 `4`：拉流异常

PullStreamStatus

String

1

拉流直播任务状态。支持以下取值：

0：拉流任务初始化中
1：拉流任务运行中
2：拉流任务已结束

PullStreamCheckStatus

String

1

拉流检测状态。支持以下取值：

0：检测中
1：源流未推流
2：正常拉流
3：拉流结束
4：拉流异常

BackupForwardInfo

参数类型示例值描述

PullStreamUrl String https://example2-livesaas.com/example/livesaas?key=example2 拉流直播拉流 URL。

参数	类型	示例值	描述
PullStreamUrl	String	`https://example2-livesaas.com/example/livesaas?key=example2`	拉流直播拉流 URL。
PullStreamStatus	String	`1`	拉流直播任务状态。支持以下取值： `0`：拉流任务初始化中 `1`：拉流任务运行中 `2`：拉流任务已结束
PullStreamCheckStatus	String	`1`	拉流检测状态。支持以下取值： `0`：检测中 `1`：源流未推流 `2`：正常拉流 `3`：拉流结束 `4`：拉流异常

PullStreamStatus

String

1

拉流直播任务状态。支持以下取值：

0：拉流任务初始化中
1：拉流任务运行中
2：拉流任务已结束

PullStreamCheckStatus

String

1

拉流检测状态。支持以下取值：

0：检测中
1：源流未推流
2：正常拉流
3：拉流结束
4：拉流异常

示例

请求示例

GET https://livesaas.volcengineapi.com/?Action=GetCustomActMsgAPI&Version=2020-06-01&ActivityId=172183460671&NeedActMsg=1&NeedActBasicMsg=1&NeedActStreamMsg=1&NeedRealTimeOnlineNumber=1

返回示例

{
		"ResponseMetadata":{
				"RequestId":"202201201826170101501312091D1C09D2",
				"Action":"GetCustomActMsgAPI",
				"Version":"2020-06-01",
				"Service":"livesaas",
				"Region":"cn-north-1",
				"SystemTime":1656067132
		},
		"Result":{
				"ActMsg":{
						"Id":172183460671,
						"Name":"直播间 A",
						"Status":2,
						"ViewUrl":"https://live.xxx.com/xxx",
						"LiveTime":1642070520,
						"IsLockPreview":0,
						"CoverImage":"https://image1.xxx",
						"VerticalCoverImage":"https://image2.xxx",
						"OwnerSubAccount":"admin@bytedance.com",
						"LiveReviewStatus":2
				},
				"ActBasicMsg":{
				    "ActivityId":172183460671,
				    "Name":"直播间 A",
				    "LiveTime":1625129340,
				    "IsCoverImageEnable":1,
				    "CoverImageUrl":"https://image1.xxx",
				    "IsPcBackImageEnable":1,
				    "PcBackImageUrl":"//p-imagex-live18n.test.org/tos-live18n-i-fhdptwgppv.png",
				    "IsMobileBackImageEnable":1,
				    "MobileBackImageUrl":"//p-imagex-live18n.test.org/tos-live18n-i-fhdptwgppv.png"
				    "IsPreviewVideoEnable":0,
				    "PreviewVideoVid":"",
				    "IsPeopleCountEnable":0,
				    "IsHeaderImageEnable":0,
				    "HeaderImageUrl":"",
				    "IsWatermarkImageEnable":0,
				    "WatermarkImageUrl":"",
				    "IsThumbUpEnable":0,
				    "ThumbUpUrl":"",
				    "IsShareIconEnable":1,
				    "ShareIconUrl":"//p-imagex-live18n.test.org/tos-live18n-i-fhdptwgppv.png",
				    "IsCommentTranslateEnable":0,
				    "Announcement":"",
				    "BackgroundColor":"",
				    "FontColor":"",
				    "InteractionColor":"",
				    "ColorThemeIndex":"",
				    "IsCountDownEnable":0,
				    "IsAutoStartEnable":0,
				    "IsPCHeaderImageEnable":"0",
				    "PCHeaderImageUrl":"",
				    "IsPageLimitEnable":0,
				    "PageLimitType":"",
				    "IsLanguageEnable":1,
				    "PlayerTopType":1,
				    "IsReplayAutoOnlineEnable":1,
				    "SiteTags":	[
				        {"Index":0,"Value":"标签1","Name":"分类标签"}
				        ],
				    "TextSiteTags":	[
				        {"Index":0,"Value":"标签2",	"Name":"文本标签"}
				        ]
				},
				"ActStreamMsg": {
				    "LineDetails":[
				        {
				            "LineId":123,
				            "LineName":"线路1",
				            "MainPushInfo":{
				                "PushPath":"https://example-livesaas.com/example",
				                "StreamingCode":"livesaas?key=example",
				                "PushUrl":"https://example-livesaas.com/example/livesaas?key=example"
			                },
			                "BackPushInfo":{
				                "PushPath":"",
				                "StreamingCode":"",
				                "PushUrl":""
			                },
			                "ForwardInfo":{
			                    "PullStreamUrl":"https://example-livesaas.com/example/livesaas?key=example",
			                    "PullStreamStatus":"1",
			                    "PullStreamCheckStatus":"1"
			                },
			                "BackupForwardInfo":{
			                    "PullStreamUrl":"https://example-livesaas.com/example/livesaas?key=example",
			                    "PullStreamStatus":"1",
			                    "PullStreamCheckStatus":"1"
			                },
			                "ExpireTime":1643004493
				        }
					]
			    },
				"RealTimeOnlineNumber":	{
				    "RealPopularity":2000,
				    "FakePopularity":2000
				}
		}
}

错误码

访问公共错误码和错误码获取详细信息。

企业直播

自定义查询直播间信息

注意事项

请求说明

请求参数

Query

返回参数

ActMsg

ActBasicMsg

ActStreamMsg

RealTimeOnlineNumber

SiteTags

TextSiteTags

LineDetails

MainPushInfo

BackPushInfo

ForwardInfo

BackupForwardInfo

示例

请求示例

返回示例

错误码