跳至主要內容
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。