Twitch Drops API 参考
一个免费的 JSON API,列出所有进行中的 Twitch 掉宝和奖励活动(每分钟刷新),以及 Twitch 的全局聊天徽章。可匿名调用,也可使用免费 API 密钥获得更高的限额。
试用
路由
所有路由都以 JSON 响应 GET 请求,任何网站的浏览器都可以调用 API(CORS)。/drops、/rewards 和 /badges 均无需注册;免费的 API 密钥可提高每个路由的限额。
三个路由的响应方式相同:列表、最近一次读取 Twitch 的时间(refreshedAt)以及您的速率限制(rateLimit)。
身份验证
读取 /drops、/rewards 和 /badges 均无需账户和密钥。匿名调用按 IP 地址计数:每个路由每5分钟1次请求。
密钥免费:使用 Discord、Twitch 或 GitHub 登录,在控制面板中创建密钥,并通过 X-API-Key 标头发送。密钥默认将您的限额提升至每分钟1次请求(可申请进一步提高),并可查看您的流量。
请将密钥保存在服务器上:任何读到它的人都能消耗您的限额。请从环境变量中读取,而不是直接写在代码里。
请求标头
# Anonymouscurl https://drops.sunkwi.com/api/twitch/drops
# With an API key, showing the rate-limit headerscurl -i -H "x-api-key: $DROPS_API_KEY" https://drops.sunkwi.com/api/twitch/drops获取免费 API 密钥
密钥免费。它会将每个路由的限额从每5分钟1次请求提升至每分钟1次请求,您还可以在控制面板中查看其流量。
- 使用 Discord、Twitch 或 GitHub 登录:无需密码,无需填写表单。
- 在控制面板中打开 API 密钥,以您的机器人或网站名称创建一个密钥。
- 在密钥显示时复制它(仅显示一次),并从您的服务器通过
X-API-Key标头发送。
获取掉宝活动
所有进行中的掉宝活动,按游戏分组:每款游戏为 games 中的一项,其活动位于 rewards 中,并附带最近一次 Twitch 扫描的时间和您的速率限制。
响应正文
Game
DropCampaign、TimeBasedDrop 和 Benefit 字段
DropCampaign
TimeBasedDrop
Benefit
字段名称来自 Twitch,且永远不会改变:可能会新增字段,现有字段始终保留。
响应代码
curl https://drops.sunkwi.com/api/twitch/drops{ "games": [ { "gameId": "460630", "gameDisplayName": "Rainbow Six Siege", "gameBoxArtURL": "https://static-cdn.jtvnw.net/ttv-boxart/460630-120x160.jpg", "startAt": "2026-10-17T05:00:00Z", "endAt": "2026-11-02T13:59:59.999Z", "rewards": [ { "id": "ef80b803-…", "name": "R6S S2 2026 19", "startAt": "2026-10-17T05:00:00Z", "endAt": "2026-11-02T13:59:59.999Z", "firstSeenAt": "2026-10-17T05:00:41.208Z", "accountLinkURL": "https://drops-register.ubi.com", "timeBasedDrops": [ { "name": "Esports Pack", "requiredMinutesWatched": 120, "repeat": null, "benefitEdges": [{ "benefit": { "name": "Esports Pack", … } }] } ], … } ] }, … ], "refreshedAt": "2026-10-24T21:14:01.936Z", "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }}获取奖励活动
所有进行中的奖励活动(Twitch 全站活动、聊天徽章、合作伙伴奖励)位于 campaigns 中,并附带最近一次 Twitch 扫描的时间和您的速率限制。
响应正文
RewardCampaign
奖励字段
RewardGroup
Reward
响应代码
curl https://drops.sunkwi.com/api/twitch/rewards{ "campaigns": [ { "id": "19f00aac-…", "name": "First Partners Collection", "brand": "Pokemon", "status": "ACTIVE", "startsAt": "2026-08-24T17:00:00Z", "endsAt": "2026-11-01T07:00:00Z", "firstSeenAt": null, "isSitewide": true, "unlockRequirements": { "minuteWatchedGoal": 20, "subsGoal": 0 }, "rewards": [{ "name": "Great Ball", "earnableUntil": "2026-11-01T07:00:00Z", … }] }, { "id": "b7669f9e-…", "name": "GTAVI Launch Celebration", "brand": "Rockstar Games", "status": "UPCOMING", "startsAt": "2026-11-18T11:00:00Z", "endsAt": "2026-12-01T07:59:59.999Z", "unlockRequirements": { "minuteWatchedGoal": 60, "subsGoal": 0 }, "rewardGroups": [ { "id": "6a0e…", "unlockRequirements": { "minuteWatchedGoal": 60, "subsGoal": 0 }, "repeat": { "everyHours": 24, "times": 6 }, "categories": [{ "id": "1867279146", "displayName": "Grand Theft Auto VI", "slug": "grand-theft-auto-vi" }], "rewards": [{ "name": "GTA DVD Chest", … }] }, … ], … }, … ], "refreshedAt": "2026-10-24T21:14:01.936Z", "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }}获取聊天徽章
Twitch 的全局聊天徽章位于 badges 中,每个版本一项;本 API 知道获取方式时会附上(requirement),并附带最近一次读取 Twitch 徽章的时间和您的速率限制。
响应正文
Badge
BadgeRequirement 字段
BadgeRequirement
适用于掉宝挂机工具:保留 requirement.watchTimeOnly 为 true 的徽章。它们来自仅凭观看时长、而非订阅即可获得徽章的掉宝活动。同时请检查 startAt 和 endAt:已结束的活动仍会保留在列表中。
有些徽章要求更多:有 repeat 时,每个周期都要再次观看 requiredMinutes,在 endAt 之前共 times 次;categories 中任何直播频道都计入;有 collection 时,宝箱可能开出您想要之外的徽章(chestSize),而 completeAll 需要完成整个合集,包括订阅。有 evolvesFrom 时,请在观看前佩戴该徽章。
响应代码
curl https://drops.sunkwi.com/api/twitch/badges速率限制
每个路由独立计数:调用 /drops 不会消耗 /rewards 或 /badges 的额度。活动每分钟更新一次,徽章每5分钟更新一次,更频繁地轮询不会获得新内容。
响应标头
被拒绝的调用(429)同样计数:请等待 Retry-After 指定的时间后再重试。
HTTP/1.1 429 Too Many Requestscontent-type: application/json; charset=utf-8retry-after: 214ratelimit-limit: 1ratelimit-remaining: 0ratelimit-reset: 214ratelimit-policy: 1;w=300
{ "code": "RATE_LIMITED" }错误
错误会返回带有固定代码的 JSON 正文:{ "code": "RATE_LIMITED" }。代码永远不会改变:请依据 code 而非消息进行处理。
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }从网站到 API
本站的每个页面都读取这些路由。以下列出页面上显示的内容在响应中的位置。
游戏页面的地址由游戏名称生成(Rocket League → /drops/rocket-league)。它是本站的地址,而不是 API 的字段:请使用 gameId 匹配游戏。