时间	更新内容
2024.9.8	创建文档
2024.9.27	修正错误码及其排查建议
2024.10.30	标注「获取直播信息」部分响应字段仅在观众一键同玩能力开放
2024.12.4	修正「嘉宾云启动玩法」、「嘉宾关闭玩法」room_id格式

能力介绍

开放平台观众一键同玩能力，可支持玩法接入以下能力：

•

支持玩法获取直播信息，获取当前进入游戏的用户 open_id、用户角色、当前直播间可支持的游戏场景等信息。

•

支持玩法查询直播间当前麦位信息、嘉宾宿主是否具备云启动条件等。

•

支持玩法指定嘉宾云启动玩法。

•

支持玩法指定嘉宾关闭玩法。

注意：
嘉宾关闭玩法的来源，除了开放给开发者的 API，还包括主播退出玩法、嘉宾自行下麦、嘉宾被踢出麦。

•

（可选）支持玩法上报连麦对局内用户积分，同步展示在直播间麦位上。

接入时序

厂商接入观众一键同玩能力需要接入红色箭头 API。

接口明细

获取直播信息

接口说明

主播使用直播伴侣或移动端云启动玩法后，直播伴侣/移动端云启动会传入 token 到玩法中，当玩法获取 token 后，传递给玩法的服务端。玩法服务端通过该接口，使用 token 获取直播间信息。

使用限制

token 有效期为 30 分钟。小玩法 app_id 维度，限流配置为 10 次 /s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/webcastmate/info
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
content-type	String	是	固定值"application/json"
X-Token	String	是	getAccessToken

请求参数

•

Body

字段	数据类型	必填	说明
token	string	是	获取到的 token

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/webcastmate/info' \
--header 'X-Token: 080112184630394f5735585a344f74546645794b544b786f30413d3d' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token":"pJKr395h6O5x2ykBjgrBIxnuot8nn62djr70EocUFXtiN1s9VpsHHuEPdZYKHVJFzftyIOb8lj9i0lrLnUhQsK55pT8shfX98qGuUBO7PSKoIVRq6tWMRdsjPVw="
}'

响应参数

•

Body

字段			数据类型	说明
errcode			int	请求错误码，0 表示成功，非 0 表示失败
errmsg			string	非 0 错误码时，携带额外的错误提示信息
data			struct	请求成功时的返回数据
	ack_cfg		[Array Item]	预留信息，sdk 接入使用，开发者不用感知
	linker_info		struct	连屏数据预留信息，开发者目前不用感知
	info		struct
		room_id	int64	直播间房间 id
		anchor_open_id	string	主播 open_id
		avatar_url	string	主播头像地址
		nick_name	string	主播昵称
		available_game_scenes	[Array Item]	数组中元素为 int64，当前直播间支持的游戏场景，枚举值如下： 1 观众一键同玩，当前直播间已经进入观众连麦、聊天室连麦模式，可支持观众一键同玩场景本字段仅在开通观众一键同玩能力时返回
		join_game_user_open_id	string	当前加入游戏的用户 open_id 本字段仅在开通观众一键同玩能力时返回
		join_game_user_role	int64	当前加入游戏的用户角色，枚举值：1 主播；2 观众本字段仅在开通观众一键同玩能力时返回

注意：

本接口应用在较多能力接入过程中，注意部分字段仅在观众一键同玩能力中开放，即 available_game_scenes 等3个字段；在未开通观众一键同玩能力时，无法使用这三个字段。

响应示例

正常响应示例

{
  "data": {
    "ack_cfg": [ // 预留信息，sdk接入使用，开发者不用感知
    ],
    "linker_info": { // 连屏数据预留信息，开发者目前不用感知
        "linker_id": 0,
        "linker_status": 0,
        "master_status": 0
    }，
    "info": {
        "room_id": 7214015683695250235,
        "anchor_open_id": "_000oJIu6APhomK7KIBGqSYm5XYPxCJB_xxx",
        "avatar_url": "https://p11.douyinpic.com/aweme/720x720/aweme-avatar/tos-cn-avt-0015_973c31e8055f78a41d3f7de3def9821d.jpeg?from=3067671334",
        "nick_name": "xxx",
        "join_game_scenes": 720575940380000262,
        "join_game_user_role": 1,
        "available_game_scenes":[ 1 ],
    }
  }
}

异常响应示例

{
        "data": {
        },
        "errcode": 40001,
        "errmsg": "invalid params",
        "extra": {
                "now": 1717059693095
        },
        "status_code": 40001
}

错误码

错误码	错误信息	描述
-1	服务内部异常	服务内部异常
40001	参数有误	检查请求 body 、请求 header 参数是否缺漏、错误
40002	通常为小程序没有该项能力	需开通当前观众一键同玩能力
40007	调用频率过高	接口有频控限制，建议降低请求的并发量
40014	缺少必要的参数	检查请求 body 、请求 header 参数是否缺漏、错误
50036	token 解析异常	检查生成 token 使用的参数、取得的 token 是否正常
50037	x-token 和 token 解析到的 app_id 不一致	检查生成 x-token 使用的 app_id 和生成 token 使用的 app_id 是否相匹配
50038	token 解析到的 room_id 对应房间不存在	检查生成 token 使用的参数、取得的 token 是否正常
50039	token 已过期	重新生成 token

查询直播间麦位信息

接口说明

可获取直播间麦位信息，获取在麦位上用户的 open_id、用户的宿主版本是否支持云启动。

使用限制

小玩法 app_id 维度，限流配置为 100/s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/linkmic/query
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
Content-Type	String	是	固定值"application/json"
X-Token	String	是	通过接口获取的 access_token

请求参数

•

Body

字段	数据类型	必填	说明
app_id	string	是	应用 ID
room_id	string	是	直播间 ID

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/linkmic/query' \
--header 'X-Token: 08011218462f4f49645946664c6f3466473' \
--header 'Content-Type: application/json' \
--data-raw '{"app_id":"tt50f82645cfcxxxxxxx","room_id":"741145185683402xxxx"}'

响应参数

•

Body

名称			字段类型	描述
errmsg			String	错误描述
errcode			Int64	错误码，0 代表成功
base_info			struct	麦位基本信息
	linker_id		string	本次连麦唯一 ID
	total_count		int32	麦位总数
	free_count		int32	麦位剩余数量
user_list			[Array Item]	麦上用户基本信息列表，元素结构为 struct
	open_id		string	麦上用户的 openId
	avatar_url		string	麦上用户的头像
	nick_name		string	麦上用户的昵称
	link_state		int32	连麦状态；1-已在麦上；2-邀请上麦中
	link_position		int32	麦上用户的麦位位置
	disable_microphone		int32	麦上用户是否禁用麦克风；1-未禁用；2-已禁用；注意：已经在麦上的用户，这个值才有效
	microphone_state		int32	麦上用户麦克风打开/关闭状态；1-已打开；2-已关闭；注意：已经在麦上的用户有效，这个值才有效
	disable_camera		int32	麦上用户是否禁用摄像头；1-未禁用；2-已禁用；注意：已经在麦上的用户有效，这个值才有效
	camera_state		int32	麦上用户摄像头打开/关闭状态；1-已打开；2-已关闭；注意：已经在麦上的用户有效，这个值才有效
	app_info		struct	麦上用户玩法相关信息
		host_app_start_app_available	bool	麦上用户宿主是否支持云启动玩法

响应示例

正常响应示例

{"errcode": 0,"errmsg": ""}

异常响应示例

{"errcode": 40001,"errmsg": "request params are invalid"}

错误码

http 状态码	错误码	错误码描述	排查建议
200	40001	参数错误	请求体中的必传参数是否都上传、请求的小玩法 app_id 是否与请求时 access_token 相匹配
200	4014034	请求过于频繁	接口有频控限制，建议降低请求的并发量
200	40004	access_token 过期	重新生成 access_token

嘉宾云启动玩法

接口说明

开发者可指定嘉宾云启动玩法。

嘉宾启动玩法成功的必要条件：

当前玩法支持云启动；

当前用户已在麦上；

当前用户的宿主和版本支持云启动。

如不满足以上任一条件，则本次请求会被拦截并返回启动失败。

使用限制

小玩法 app_id 维度，qps 限流配置为 100 次 /s。

小玩法 app_id 嘉宾 open_id + 直播间 room_id 维度，启动和结束玩法 qps 限流配置为 1 次 /s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/audience/join_game
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
Content-Type	String	是	固定值"application/json"
X-Token	String	是	通过接口获取的 access_token

请求参数

•

Body

名称	字段类型	是否必填	描述
app_id	String	是	小玩法 app_id
open_id	String	是	用户 open_id
room_id	Int64	是	房间 Id

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/audience/join_game' \
--header 'Content-Type: application/json' \
--header 'X-Token: 08011218462f4f516b5333xxx' \
--data-raw '{"room_id":740769665344184xxxx,"app_id":"tt50f82645cfcxxxxxxx","open_id":"xxx"}'

响应参数

请求响应都以 HTTP 200 的形式返回，具体错误由响应字段中的错误码字段来标记。

名称	字段类型	是否必填	描述
errcode	Int64	是	错误码，0 代表成功
errmsg	String	是	错误描述，成功为 success

响应示例

正常响应示例

{
        "errcode": 0,
        "errmsg": "success",
}

异常响应示例

{
    "errcode": 40004,
    "errmsg": "access token is expired"
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	40001	参数错误	房间id、小玩法app_id等入参解析失败，检查参数解析逻辑
200	40007	请求过于频繁	接口有频控限制，建议降低请求的并发量
200	40004	access_token过期	重新生成access_token
200	50041	玩法同玩场景未准备好	请检查当前直播间是否在观众连麦/聊天室连麦中
200	50042	玩法同玩场景未准备好	请检查当前玩法是否支持云启动
200	50047	当前用户不在连麦中	当前传入的用户已经不在连麦中
200	50048	观众一键同玩能力繁忙	观众一键同玩能力繁忙，暂停使用

嘉宾关闭玩法

接口说明

开发者可指定嘉宾关闭玩法。

使用限制

小玩法 app_id 维度，qps 限流配置为 100 次 /s。

小玩法 app_id + 嘉宾 open_id + 直播间 room_id 维度，启动和结束玩法 qps 限流配置为 1 次 /s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/audience/leave_game
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
Content-Type	String	是	固定值"application/json"
X-Token	String	是	通过接口获取的 access_token

请求参数

•

Body

名称	字段类型	是否必填	描述
app_id	String	是	小玩法 app_id
open_id	String	是	用户 open_id
room_id	Int64	是	房间 id

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/audience/leave_game' \
--header 'Content-Type: application/json' \
--header 'X-Token: 08011218462f4f516b5333xxx' \
--data-raw '{"room_id":740769665344184xxxx,"app_id":"tt50f82645cfcxxxxxxx","open_id":"xxx"}'

响应参数

请求响应都以 HTTP 200 的形式返回，具体错误由响应字段中的错误码字段来标记。

名称	字段类型	是否必填	描述
errcode	Int64	是	错误码，0 代表成功
errmsg	String	是	错误描述，成功为 success

响应示例

正常响应示例

{
        "errcode": 0,
        "errmsg": "success",
}

异常响应示例

{
  "errcode": 1,
  "errmsg": "参数不合法"
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	40001	参数错误	房间id、小玩法app_id等入参解析失败，检查参数解析逻辑
200	40007	请求过于频繁	接口有频控限制，建议降低请求的并发量
200	40004	access_token过期	重新生成access_token
200	50041	玩法同玩场景未准备好	请检查当前直播间是否在观众连麦/聊天室连麦中
200	50042	玩法同玩场景未准备好	请检查当前玩法是否支持云启动
200	50047	当前用户不在连麦中	当前传入的用户已经不在连麦中
200	50048	观众一键同玩能力繁忙	观众一键同玩能力繁忙，暂停使用

上报连麦对局内用户积分

接口说明

上报连麦对局内用户积分，在对局开始、对局结束上报一次，对局期间定时上报，上报后会将积分值展示在麦位上。

底层以直播间维度覆盖存储最新的对局数据，因此每次调用会将直播间上次的麦位积分完全覆盖。

•比如：直播间内嘉宾对局数据定时上报到开发平台，每 30s 上报一次
◦8:00:00：调用【上报连麦对局内用户积分】接口一次，一次性上报当前时刻的连麦对局内用户积分
◦8:00:30：调用【上报连麦对局内用户积分】接口一次，一次性上报当前时刻的连麦对局内用户积分，直播间8:00:00 上报的数据，将被 8:00:30 这次上报的数据完全覆盖

注意：如果嘉宾在麦位上，但不在上报用户集合中，则会被默认设置为观战中。

•比如：玩法内调用【上报连麦对局内用户积分】接口一次，一次性上报当前时刻的连麦对局内用户积分，包含三位用户，用户 A，用户 B，用户 C；此时在直播间麦位上的用户有用户 A，用户 B，用户 C，用户 D
◦此时用户 A，用户 B，用户 C 的麦位上展示玩法上报的积分值，用户 D 的麦位上展示为观战中

建议每 30s 调用一次，刷新最新的对局积分，保障麦位上对局积分时效。

使用限制

小玩法 app_id 维度，qps 限流配置为 200/s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/gaming_con/round/co_game_upload_user_data
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
content-type	String	是	固定值"application/json"
X-Token	String	是	getAccessToken

请求参数

•

Body

名称		字段类型	是否必填	描述
app_id		String	是	小玩法 app_id
round_id		Int64	是	对局 id
round_status		Int64	是	对局状态，枚举值：1 开始；2 结束；3 进行中
anchor_infos		[Array Item]	是	对局关联的直播房间列表，目前仅支持传入 1 个
	anchor_open_id	String	是	主播的 open_id
	room_id	String	是	房间 room_id
user_list		[Array Item]	是	用户对局数据列表
	open_id	String	是	用户 open_id
	score	Int64	是	核心数值，用户排名的依据

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/gaming_con/round/co_game_upload_user_data' \
--header 'X-Token: 08011218462f4f516b53xxx' \
--header 'Content-Type: application/json' \
--data-raw '{"app_id":"ttb101c7bc2e30xxxxxx","round_id":1,"round_status":1,"anchor_infos":[{"anchor_open_id":"xxxx","room_id":"741033347597639xxxx"}],"user_list":[{"open_id":"xxxx","score":396}]}'

响应参数

•

Body

名称	字段类型	是否必填	描述
errmsg	String	是	错误描述
errcode	Int64	是	错误码，0 代表成功

响应示例

正常响应示例

{"errcode": 0,"errmsg": ""}

异常响应示例

{"errcode": 40001,"errmsg": "request params are invalid"}

错误码

HTTP 状态码	错误码	描述	排查建议
200	40001	参数错误	房间 id、小玩法 app_id 等入参解析失败，检查参数解析逻辑
200	40007	请求过于频繁	接口有频控限制，建议降低请求的并发量
200	40004	access_token 过期	重新生成 access_token
200	50048	观众一键同玩能力繁忙	观众一键同玩能力繁忙，暂停使用

礼物推送

具体数据开放接入流程参考：数据开放__抖音开放平台

礼物数据-payload

当观众一键同玩能力开通后，观众可以给嘉宾送礼，送礼的流水中会增加audience_sec_open_id。

•如果被送礼的是嘉宾，则audience_sec_open_id为被送礼的嘉宾open_id。
•如果被送礼的是主播，则audience_sec_open_id为空字符串。

[ 
  {
    msg_id: "123456782", // string类型id
    sec_openid: "xxxx", // 用户的加密openid，当前其实没有加密
    sec_gift_id: "xxxx", // 加密的礼物id
    gift_num: 123, // 送出的礼物数量
    gift_value: 10000, // 礼物总价值，单位分
    avatar_url: "xxx", // 用户头像
    nickname: "xxxx", // 用户昵称(不加密)
    timestamp: 1649068964, // 礼物毫秒级时间戳
    test: true, // 非真实测试数据，会下发该字段。测试工具下发的送礼数据属于调试模式，不会有该字段
    audience_sec_open_id:"xxx" // 被送礼的嘉宾openid，当前没有加密
  },
];