按登录名获取 Twitch 直播间状态与开播详情
查看 Twitch 频道、剪辑、视频与直播数据 API 的全部接口 →按频道登录名查询某个 Twitch 频道当前的直播情况,返回请求时刻的一次快照。输入参数:channel(必填)是公开 Twitch 网址中显示的频道登录名,例如 ninja,而不是展示用的标题。以频道 ninja 离线时的一次实测为例:返回 HTTP 200,使用统一的外层结构 {status, request_id, message, data};status 为 'ok',message 中带有“频道当前处于离线状态”的提示,data.user 包含字符串类型的 id、值为 null 的 stream 以及 __typename 'User'。stream 为 null 表示频道没有在直播,或请求时没有可用的直播数据,这是有效结果而不是请求失败,可结合 status 和 message 区分两种情况。实测中没有出现正在直播时的完整返回,因此这里不列出直播状态下的字段名,接入前请先用真实开播频道的响应核对再做字段映射。该接口不会录制或下载直播,也不保证持续的直播状态;需要观众数据请使用“获取直播观看人数”,需要分类标签请使用“获取直播标签列表”。
API 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/api/project/twitch-scraper/get-stream-details API 响应 (JSON)
{} curl -X GET 'https://api.opendata-api.com/api/project/twitch-scraper/get-stream-details?key=<API_KEY>&channel=ninja'
查询结果
使用场景
- 为 Discord 或 Telegram 机器人做开播通知,在某个频道的 stream 从 null 变为非空时只提醒一次
- 在粉丝站或赞助商页面上显示“直播中”徽标,并用明确的离线状态代替错误提示
- 综合 stream 值、status 和离线提示,把每次查询归类为直播中、离线或未能解析
- 在推广档期开始前确认受赞助的主播是否真的在约定时间开播
- 每隔几分钟轮询一批主播名单,记录各频道的实际开播时段,用来核对排期执行情况
常见问题
data.user.stream 为 null 是什么意思?
对频道 ninja 的实测中,频道离线时 stream 为 null。stream 为 null 表示频道没有在直播,或请求时没有可用的直播数据。它是 status 为 'ok' 的有效结果,不是请求失败。
“频道当前处于离线状态”这条 message 算错误吗?
不算。实测返回 HTTP 200 和 status 'ok',message 只是提示频道当前处于离线状态。三个直播相关接口中只有“获取直播详情”会附带这条提示,因此可以用它区分频道离线与请求未能解析。
如何区分频道离线和请求失败?
请同时检查 HTTP 状态码、外层的 status 字段和 message。频道离线时会返回 status 'ok'、带有 id 的 data.user 对象、值为 null 的 stream 以及离线提示;请求失败则不会返回这样一个完整的 user 对象。
频道正在直播时会返回哪些字段?
实测中没有出现正在直播时的完整返回,所以这里不列出具体字段名。请在频道开播期间调用一次,先查看 data.user.stream 的内容再建立字段映射,并把没有看到的字段都当作可选字段处理。
channel 参数应该传什么?
传公开 Twitch 网址中显示的频道登录名,例如 ninja。展示名称或随意输入的文字都不是登录名;如果只知道名字,请先用“搜索频道”接口,再从结果里取登录名。
这个接口会录制或下载直播吗?
不会。它只返回开播元数据的一次时点查询,不会录制、截取或下载直播内容,也不保证持续的直播状态,需要最新结果时请重新请求。
观看人数和直播标签在哪里获取?
观众数量请使用“获取直播观看人数”,分类标签请使用“获取直播标签列表”。两者都只需要同一个频道登录名,实测中对离线频道返回的也是相同的 data.user 结构,其中 stream 为 null。