按登录名获取 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 功能

一次 GET 判断开播或离线 传入频道登录名,读取 data.user.stream 即可:实测离线频道返回 null,出现非空对象则表示正在直播。无需注册 Twitch 开发者应用,也不用获取 client-credentials 令牌。
明确的离线提示 频道离线时,外层结构返回 HTTP 200、status 为 'ok',并在 message 中说明频道当前处于离线状态,程序可以直接展示“未开播”,而不必把它当成错误处理。
离线时也返回用户 id 无论频道是否在直播,data.user.id 和 __typename 都会返回,可以据此确认登录名对应的是真实的 Twitch 用户,并用该 id 作为自己数据表中的关联键。
每次响应附带请求编号 外层结构在 status 和 message 之外还包含 request_id 字符串,建议每次轮询都记录下来,之后需要追查某次开播检测时可以快速定位。
只是快照,不是录像 结果只反映请求当时的频道状态,不会录制或下载任何直播内容。轮询频率由你自己安排,并建议随每条结果保存检索时间。

在线 API 演示

GET /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'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

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。

相关接口

相关指南

查看订阅方案 →