Tài liệu tham khảo Twitch Drops API
API JSON miễn phí liệt kê mọi chiến dịch Twitch Drops và chiến dịch phần thưởng đang diễn ra, cập nhật mỗi phút, cùng các huy hiệu trò chuyện toàn cục của Twitch. Gọi ẩn danh, hoặc dùng khóa API miễn phí để có giới hạn cao hơn.
Dùng thử
Route
Mọi route đều trả về JSON cho yêu cầu GET, và trình duyệt của bất kỳ trang web nào cũng có thể gọi API (CORS). Không route nào trong số /drops, /rewards hay /badges cần đăng ký; khóa API miễn phí sẽ tăng giới hạn trên mỗi route.
Cả ba route đều trả lời giống nhau: danh sách, thời điểm đọc Twitch gần nhất (refreshedAt) và giới hạn tần suất của bạn (rateLimit).
Xác thực
Đọc /drops, /rewards và /badges không cần tài khoản hay khóa. Lệnh gọi ẩn danh được tính theo địa chỉ IP: 1 yêu cầu mỗi 5 phút trên mỗi route.
Khóa hoàn toàn miễn phí: đăng nhập bằng Discord, Twitch hoặc GitHub, tạo khóa trong bảng điều khiển và gửi khóa trong header X-API-Key. Theo mặc định, khóa nâng giới hạn của bạn lên 1 yêu cầu mỗi phút, có thể nâng thêm khi có yêu cầu, và cho bạn xem lưu lượng của mình.
Giữ khóa trên máy chủ của bạn: ai đọc được khóa đều có thể dùng hết giới hạn của bạn. Hãy đọc khóa từ biến môi trường thay vì viết thẳng vào mã.
Header yêu cầu
# 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/dropsNhận khóa API miễn phí
Khóa hoàn toàn miễn phí. Khóa nâng giới hạn của bạn từ 1 yêu cầu mỗi 5 phút lên 1 yêu cầu mỗi phút trên mỗi route, và bảng điều khiển cho bạn xem lưu lượng của khóa.
- Đăng nhập bằng Discord, Twitch hoặc GitHub: không mật khẩu, không biểu mẫu.
- Mở Khóa API trong bảng điều khiển và tạo một khóa đặt theo tên bot hoặc trang web của bạn.
- Sao chép khóa khi khóa hiển thị (chỉ một lần) và gửi khóa trong header
X-API-Key, từ máy chủ của bạn.
Lấy chiến dịch Drops
Mọi chiến dịch Drops đang diễn ra, nhóm theo game: mỗi game một mục trong games, các chiến dịch của game nằm trong rewards, kèm thời điểm của lần quét Twitch gần nhất và giới hạn tần suất của bạn.
Body phản hồi
Game
Các trường DropCampaign, TimeBasedDrop và Benefit
DropCampaign
TimeBasedDrop
Benefit
Tên trường lấy từ Twitch và không bao giờ thay đổi: có thể có trường mới, các trường hiện có vẫn giữ nguyên.
Mã phản hồi
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" }}Lấy chiến dịch phần thưởng
Mọi chiến dịch phần thưởng đang diễn ra (sự kiện toàn Twitch, huy hiệu trò chuyện, phần thưởng đối tác) trong campaigns, kèm thời điểm của lần quét Twitch gần nhất và giới hạn tần suất của bạn.
Body phản hồi
RewardCampaign
Các trường phần thưởng
RewardGroup
Reward
Mã phản hồi
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" }}Lấy huy hiệu trò chuyện
Các huy hiệu trò chuyện toàn cục của Twitch trong badges, mỗi phiên bản một mục, kèm cách nhận khi API này biết (requirement), cùng thời điểm đọc huy hiệu Twitch gần nhất và giới hạn tần suất của bạn.
Body phản hồi
Badge
Các trường BadgeRequirement
BadgeRequirement
Dành cho công cụ cày Drops: giữ lại các huy hiệu có requirement.watchTimeOnly là true. Chúng đến từ một chiến dịch Drops trao huy hiệu chỉ cho thời gian xem, không bao giờ cho lượt đăng ký. Hãy kiểm tra cả startAt và endAt: chiến dịch đã kết thúc vẫn nằm trong danh sách.
Một số huy hiệu đòi hỏi nhiều hơn: với repeat, hãy xem lại requiredMinutes mỗi chu kỳ, times lần, trước endAt; mọi kênh đang phát thuộc categories đều được tính; với collection, rương có thể cho huy hiệu khác với huy hiệu bạn muốn (chestSize), còn completeAll cần toàn bộ bộ sưu tập, kể cả lượt đăng ký. Với evolvesFrom, hãy đeo huy hiệu đó trước khi xem.
Mã phản hồi
curl https://drops.sunkwi.com/api/twitch/badgesGiới hạn tần suất
Mỗi route có bộ đếm riêng: gọi /drops không bao giờ dùng vào hạn mức của /rewards hay /badges. Chiến dịch thay đổi mỗi phút một lần và huy hiệu mỗi 5 phút, nên gọi nhanh hơn cũng không có gì mới.
Header phản hồi
Lệnh gọi bị từ chối (429) vẫn được tính: hãy chờ hết Retry-After rồi mới thử lại.
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" }Lỗi
Lỗi trả về một body JSON với mã ổn định: { "code": "RATE_LIMITED" }. Mã không bao giờ thay đổi: hãy dựa vào code, không dựa vào thông báo.
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }Từ trang web đến API
Mọi trang của trang web này đều đọc chính các route này. Dưới đây là vị trí trong phản hồi của những gì mỗi trang hiển thị.
Địa chỉ trang game được tạo từ tên game (Rocket League → /drops/rocket-league). Đó là địa chỉ của trang web này, không phải một trường của API: hãy đối chiếu game theo gameId.