跳到主要内容
Twitch Drops API

Twitch Drops API 参考

一个免费的 JSON API,列出所有进行中的 Twitch 掉宝和奖励活动(每分钟刷新),以及 Twitch 的全局聊天徽章。可匿名调用,也可使用免费 API 密钥获得更高的限额。

基础 URLhttps://drops.sunkwi.com/api/twitch
获取免费 API 密钥阅读参考文档

试用

匿名:每个路由每5分钟1次请求。使用密钥:每分钟1次。

GET
正在加载预览…
浏览

路由

所有路由都以 JSON 响应 GET 请求,任何网站的浏览器都可以调用 API(CORS)。/drops、/rewards 和 /badges 均无需注册;免费的 API 密钥可提高每个路由的限额。

三个路由的响应方式相同:列表、最近一次读取 Twitch 的时间(refreshedAt)以及您的速率限制(rateLimit)。

路由说明
GET /drops按游戏分组的掉宝活动. 所有进行中的掉宝活动,按游戏分组,位于 games 中:每款游戏一项,其活动位于 rewards 中。
GET /rewards奖励活动. 所有进行中的奖励活动(Twitch 全站活动、聊天徽章、合作伙伴奖励),位于 campaigns 中。
GET /badges全局聊天徽章. Twitch 的全局聊天徽章,位于 badges 中,每个版本一项,已知时附带获取方式。

身份验证

读取 /drops、/rewards 和 /badges 均无需账户和密钥。匿名调用按 IP 地址计数:每个路由每5分钟1次请求。

密钥免费:使用 Discord、Twitch 或 GitHub 登录,在控制面板中创建密钥,并通过 X-API-Key 标头发送。密钥默认将您的限额提升至每分钟1次请求(可申请进一步提高),并可查看您的流量。

请求标头

标头值说明
X-API-Keyjdk_…您的 API 密钥:在每个路由上均为可选。未知、已吊销或已停用的密钥永远不会被拒绝:该调用按匿名计算,并通过 x-api-key-status: invalid 告知。
请求示例 · curl
# 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次请求,您还可以在控制面板中查看其流量。

  1. 使用 Discord、Twitch 或 GitHub 登录:无需密码,无需填写表单。
  2. 在控制面板中打开 API 密钥,以您的机器人或网站名称创建一个密钥。
  3. 在密钥显示时复制它(仅显示一次),并从您的服务器通过 X-API-Key 标头发送。

获取掉宝活动

GEThttps://drops.sunkwi.com/api/twitch/drops

所有进行中的掉宝活动,按游戏分组:每款游戏为 games 中的一项,其活动位于 rewards 中,并附带最近一次 Twitch 扫描的时间和您的速率限制。

响应正文

字段类型说明
gamesGame[]进行中的活动,按最近一次扫描的顺序排列。空数组也是有效的响应。
refreshedAtstring (ISO 8601) | null最近一次成功扫描 Twitch 的时间,首次扫描前为 null。
rateLimit{ limit, remaining, resetAt }本次调用后您在此路由上的限额,与 ratelimit-* 标头所示一致:limit 为每个时间窗口的请求数,remaining 为仍允许的请求数,resetAt 为限额完全恢复的时间(ISO 8601)。

Game

games 中的一项。

字段类型说明
gameIdstring游戏的 Twitch ID。
gameDisplayNamestring游戏名称。
gameBoxArtURLstring (URL)游戏封面,120×160。
startAtstring (ISO 8601)该游戏最早一个活动的开始时间。
endAtstring (ISO 8601)该游戏最晚一个活动的结束时间。
rewardsDropCampaign[]该游戏的掉宝活动。
DropCampaign、TimeBasedDrop 和 Benefit 字段

DropCampaign

一个掉宝活动,位于游戏的 rewards 中。

字段类型说明
idstring活动的 Twitch ID。
name, descriptionstring发行商提供的名称和描述。
owner{ id, name }举办活动的发行商。
game{ id, displayName, slug }活动所属的游戏。
statusstringTwitch 状态,进行中的活动为 ACTIVE。
startAt, endAtstring (ISO 8601)活动的进行时间。
imageURLstring (URL)活动图片。
detailsURL, accountLinkURLstring (URL)发行商的详情页面和账户关联页面。
allow{ isEnabled, channels? }当 isEnabled 为 true 时,可发放掉宝的频道;否则为任何直播该游戏的频道。displayName 可能为 null 或缺失。
timeBasedDropsTimeBasedDrop[]通过观看获得的掉宝。
eventBasedDropsunknown[]通过事件获得的掉宝,按 Twitch 原样传递。
firstSeenAtstring (ISO 8601) | null本 API 首次发现该活动的时间。离开列表后一天内重新出现的活动保留原来的时间。本字段出现时 API 已在提供的活动为 null。

TimeBasedDrop

一个通过观看获得的掉宝,位于 timeBasedDrops 中。

字段类型说明
id, namestring掉宝的 Twitch ID 和名称。
startAt, endAtstring (ISO 8601)可获得该掉宝的时间段。
requiredMinutesWatchednumber所需的观看分钟数。
requiredSubsnumber所需的订阅数。
repeat{ everyHours, times } | null由本 API 添加:该掉宝可再次获得的频率,包含 times(次数)和 everyHours(24:每天一次;Twitch 未说明时为 null)。此时 requiredMinutesWatched 为一个周期的观看时长。只能获得一次的掉宝为 null。
preconditionDropsunknown需要先获得的掉宝,按 Twitch 原样传递。
benefitEdges{ benefit: Benefit, entitlementLimit }[]该掉宝提供的内容,以及可领取的次数。

Benefit

一个游戏内物品,位于 benefitEdges 中。

字段类型说明
id, namestring物品的 Twitch ID 和名称。
imageAssetURLstring (URL)物品图片。
createdAtstring (ISO 8601)物品在 Twitch 上的创建日期。
distributionTypestring物品的发放方式:游戏内物品为 DIRECT_ENTITLEMENT,聊天徽章为 BADGE。
entitlementLimitnumber物品可领取的次数。
isIosAvailableboolean物品是否可在 iOS 上领取。
game, ownerOrganization{ id, name }物品所属的游戏和发行商。

响应代码

状态说明
200进行中的活动。空列表也是有效的响应。
304自您发送的 ETag 以来没有变化:请保留您的副本。免费,不计入您的限额。
429RATE_LIMITED: 请等待 Retry-After 指定的秒数。
429INVALID_API_KEY_RATE_LIMITED: 无法识别该密钥,且您 IP 地址的匿名限额已用完:请修正密钥。
503SERVICE_UNAVAILABLE: 列表尚未加载(API 刚重启时):请在 Retry-After 后重试。免费,不计入您的限额。
请求示例
curl https://drops.sunkwi.com/api/twitch/drops
响应示例 · 200 OK
{  "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" }}

获取奖励活动

GEThttps://drops.sunkwi.com/api/twitch/rewards

所有进行中的奖励活动(Twitch 全站活动、聊天徽章、合作伙伴奖励)位于 campaigns 中,并附带最近一次 Twitch 扫描的时间和您的速率限制。

响应正文

字段类型说明
campaignsRewardCampaign[]进行中的活动,按最近一次扫描的顺序排列。空数组也是有效的响应。
refreshedAtstring (ISO 8601) | null最近一次成功扫描 Twitch 的时间,首次扫描前为 null。
rateLimit{ limit, remaining, resetAt }本次调用后您在此路由上的限额,与 ratelimit-* 标头所示一致:limit 为每个时间窗口的请求数,remaining 为仍允许的请求数,resetAt 为限额完全恢复的时间(ISO 8601)。

RewardCampaign

campaigns 中的一项。

字段类型说明
id, name, brandstring活动的 Twitch ID、名称和品牌。
statusstring请求时的状态,按日期得出:startsAt 之前为 UPCOMING,至 endsAt 为 ACTIVE,之后为 EXPIRED。
summary, instructionsstringTwitch 显示的文本。
startsAt, endsAtstring (ISO 8601)活动的进行时间。
image{ image1xURL }活动图片。
aboutURL, externalURLstring (URL)活动的帮助页面和外部页面。
isSitewideboolean是否所有频道都计入,而不仅限于某款游戏的频道。
game{ id, displayName, slug }?活动所属的游戏(如有)。
rewardValueURLParamstringTwitch 添加到兑换链接中的值。
unlockRequirements{ minuteWatchedGoal, subsGoal }所需的观看分钟数和订阅数。
rewardGroupsRewardGroup[]?按组逐一获得的奖励,每组有各自的目标:每天一个奖励就是每天一组。仅在 Twitch 发送时提供。
rewardsReward[]活动的所有奖励,包括各组中的奖励,每个只列一次。
firstSeenAtstring (ISO 8601) | null本 API 首次发现该活动的时间。离开列表后一天内重新出现的活动保留原来的时间。本字段出现时 API 已在提供的活动为 null。
奖励字段

RewardGroup

奖励活动中一同获得的一组奖励。

字段类型说明
idstring该组的 Twitch ID。
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }该组的要求。Twitch 会在此加入 Turbo 和活动目标。
repeat{ everyHours, times } | null该组可再次获得的频率,与掉宝的 repeat 相同:此时 minuteWatchedGoal 为一个周期的观看时长。只能获得一次的组为 null。
categories{ id, displayName, slug }[]其直播频道计入的分类,任意一个均可;Twitch 未指定时为空。
rewardsReward[]该组的奖励,同样列在活动的 rewards 中。

Reward

奖励活动中的一个奖励。

字段类型说明
id, namestring奖励的 Twitch ID 和名称。
bannerImage, thumbnailImage{ image1xURL }奖励的图片。
earnableUntilstring (ISO 8601)可获得该奖励的最后时间。
redemptionInstructions, redemptionURLstring如何兑换奖励,以及在哪里兑换。

响应代码

状态说明
200进行中的活动。空列表也是有效的响应。
304自您发送的 ETag 以来没有变化:请保留您的副本。免费,不计入您的限额。
429RATE_LIMITED: 请等待 Retry-After 指定的秒数。
429INVALID_API_KEY_RATE_LIMITED: 无法识别该密钥,且您 IP 地址的匿名限额已用完:请修正密钥。
503SERVICE_UNAVAILABLE: 列表尚未加载(API 刚重启时):请在 Retry-After 后重试。免费,不计入您的限额。
请求示例
curl https://drops.sunkwi.com/api/twitch/rewards
响应示例 · 200 OK
{  "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" }}

获取聊天徽章

GEThttps://drops.sunkwi.com/api/twitch/badges

Twitch 的全局聊天徽章位于 badges 中,每个版本一项;本 API 知道获取方式时会附上(requirement),并附带最近一次读取 Twitch 徽章的时间和您的速率限制。

响应正文

字段类型说明
badgesBadge[]全局徽章,每个版本一项。空数组也是有效的响应。
refreshedAtstring (ISO 8601) | null最近一次成功读取 Twitch 徽章的时间(每5分钟一次),首次读取前为 null。
rateLimit{ limit, remaining, resetAt }本次调用后您在此路由上的限额,与 ratelimit-* 标头所示一致:limit 为每个时间窗口的请求数,remaining 为仍允许的请求数,resetAt 为限额完全恢复的时间(ISO 8601)。

Badge

badges 中的一项:全局聊天徽章的一个版本,与 Twitch 当前列出的一致。

字段类型说明
setId, versionIdstring徽章组及其版本:两者共同确定一个徽章(sub-gifter 和 5)。
title, descriptionstring徽章名称和 Twitch 的说明,均为英文。
imageUrl1x, imageUrl2x, imageUrl4xstring (URL)18、36 和 72 像素的徽章图片。
clickAction, clickUrlstring | null点击徽章时 Twitch 执行的操作及其链接;Twitch 未提供时为 null。
firstSeenAtstring (ISO 8601) | null本 API 首次发现该徽章的时间。徽章在 Twitch 移除超过 7 天后重新出现时,记为新的时间;7 天内重新出现则保留原来的时间。首次读取时已存在的徽章为 null。
requirementBadgeRequirement | null获取方式;本 API 不知道时为 null。
BadgeRequirement 字段

BadgeRequirement

徽章的获取方式:来自发放该徽章的掉宝活动(DROPS),或来自 Twitch 对订阅徽章或观看徽章的说明(TWITCH_DESCRIPTION)。

字段类型说明
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS 或 TWITCH_DESCRIPTION。
watchTimeOnlyboolean仅在观看即可获得时为 true:要求观看时长(requiredMinutes 大于 0)且不要求订阅(requiredSubs 为 0)的 DROPS 活动。
requiredMinutes, requiredSubsnumber所需的观看分钟数,以及订阅数或赠送订阅数。
gameId, gameNamestring游戏:其 Twitch ID(未知时为 null)和名称。
channels, channelCountstring[] (≤ 5), number发放该徽章的前5个频道(登录名)及频道总数;0 表示任何直播该游戏的频道。
startAt, endAtstring (ISO 8601) | null活动的进行时间;TWITCH_DESCRIPTION 时为 null。已结束的活动仍会保留。
campaignId, campaignNamestring | null掉宝活动;TWITCH_DESCRIPTION 时为 null。
repeat{ everyHours, times } | null仅 DROPS:每个周期都需再次观看,requiredMinutes 为一个周期的时长,包含 times 和 everyHours(每天 20 分钟,共 3 天:times 为 3,everyHours 为 24);否则为 null。
categories{ id, name }[] (≤ 50)仅 DROPS:其直播频道计入的分类,任意一个均可(id 和 name,最多 50 个);gameId 和 gameName 为第一个分类。否则为空。
collection{ chestSize, completeAll } | null仅 DROPS:该徽章是活动合集(即该活动)的奖励之一。chestSize:它从装有这么多奖励的宝箱中开出,每个宝箱一个,无法自选(null:直接发放)。completeAll:完成整个合集(包括订阅)后发放。否则为 null。
evolvesFrom{ setId, versionId } | null仅 DROPS:观看前需要在聊天中佩戴的徽章,以其在本列表中的 setId 和 versionId 表示:宝可梦的进化需要其上一阶段(Pikachu:Pichu)。其他情况或未知时为 null。

响应代码

状态说明
200全局徽章。空列表也是有效的响应。
304自您发送的 ETag 以来没有变化:请保留您的副本。免费,不计入您的限额。
429RATE_LIMITED: 请等待 Retry-After 指定的秒数。
429INVALID_API_KEY_RATE_LIMITED: 无法识别该密钥,且您 IP 地址的匿名限额已用完:请修正密钥。
503SERVICE_UNAVAILABLE: 列表尚未加载(API 刚重启时):请在 Retry-After 后重试。免费,不计入您的限额。
请求示例
curl https://drops.sunkwi.com/api/twitch/badges
正在加载预览…

速率限制

每个路由独立计数:调用 /drops 不会消耗 /rewards 或 /badges 的额度。活动每分钟更新一次,徽章每5分钟更新一次,更频繁地轮询不会获得新内容。

调用方每个路由的限额计数依据
匿名每5分钟1次请求IP 地址
使用 API 密钥默认每分钟1次请求,可申请提高API 密钥

响应标头

API 读取和发送的标头。

标头方向说明
x-last-updated-atresponse最近一次成功读取 Twitch 的时间:/drops 和 /rewards 为扫描时间,/badges 为徽章读取时间。
x-refresh-interval-secondsresponse两次读取 Twitch 之间的秒数:更频繁地请求只会返回相同的数据(/drops 和 /rewards 为60,/badges 为300)。
ratelimit-limitresponse此路由在时间窗口内允许的请求数。
ratelimit-remainingresponse当前时间窗口内剩余的请求数。
ratelimit-resetresponse距离可再次请求的秒数。
ratelimit-policyresponse限制策略,格式为 <限额>;w=<时间窗口秒数>。
retry-afterresponse收到 429 或 503 响应时,重试前需等待的秒数。
x-api-keyrequest您的 API 密钥:在每个路由上均为可选。
x-api-key-statusresponse发送的密钥未知、已吊销或已停用时为 invalid:该调用按匿名计算,计入您 IP 地址的限额。
etagresponse此响应的标签。在 If-None-Match 中发回:只要数据未变,响应就是 304,不计入您的限额。
if-none-matchrequest您上一次响应的 ETag,可选:列表未变时返回 304 Not Modified,免费。
5分钟内的第二次匿名调用
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 而非消息进行处理。

状态代码说明
429RATE_LIMITED此路由的请求过多:请等待 Retry-After 指定的秒数。
429INVALID_API_KEY_RATE_LIMITED请求过多,且 X-API-Key 标头中的密钥未知、已吊销或已停用:该调用按匿名计算。请修正密钥,或等待 Retry-After 指定的秒数。
503SERVICE_UNAVAILABLE列表尚未加载(API 刚重启时)。不会消耗任何额度:请在 Retry-After 指定的秒数后重试。
404NOT_FOUND该路由不存在。
500INTERNAL_SERVER_ERROR服务器出错:请稍后重试。
错误示例
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }

从网站到 API

本站的每个页面都读取这些路由。以下列出页面上显示的内容在响应中的位置。

页面路由在响应中的位置
掉宝/drops/dropsgames:每款游戏一项,其活动位于 rewards 中。网格视图会绘制每个活动的 startAt 和 endAt。
游戏页面/drops/<game>/dropsgames 中按 gameId 匹配的一项。每个活动为 games[i].rewards[j];其奖励是 timeBasedDrops 的 benefitEdges,附带 requiredMinutesWatched。
奖励/rewards/rewardscampaigns:每个奖励活动一项,其奖励位于 rewards 中,要求位于 unlockRequirements 中。
奖励活动页面/rewards/<campaign>/rewardscampaigns 中按 id 匹配的一项;其奖励位于 rewards 中。
徽章/badges/badgesbadges:所有项,带有 requirement 的项排在前面,并附获取方式。网格视图会绘制每个徽章的 requirement.startAt 和 requirement.endAt。
徽章页面/badges/<badge>/badgesbadges 中按 setId 和 versionId 匹配的一项;“获取方式”即其 requirement。