Към съдържанието
Twitch Drops API

Справочник на Twitch Drops API

Безплатен JSON API с всички активни кампании за Twitch Drops и с награди, обновявани всяка минута, и с глобалните значки за чата в Twitch. Извиквайте го анонимно или с безплатен API ключ за по-висок лимит.

Базов URLhttps://drops.sunkwi.com/api/twitch
Вземете безплатен API ключКъм справочника

Изпробвайте

Анонимно: 1 заявка на всеки 5 мин за маршрут. С ключ: 1 на минута.

GET
Зареждане на прегледа…
Разглеждане

Маршрути

Всеки маршрут отговаря с JSON на заявка GET, а браузърите на всеки сайт могат да извикват API (CORS). Нито /drops, нито /rewards, нито /badges изискват регистрация; безплатен API ключ вдига лимита за всеки от тях.

Трите маршрута отговарят по един и същ начин: списъкът, времето на последното извличане от Twitch (refreshedAt) и лимитът ви на заявките (rateLimit).

МаршрутОписание
GET /dropsКампании за Drops по игри. Всички активни кампании за Drops, групирани по игра, в games: по един елемент на игра, кампаниите ѝ в rewards.
GET /rewardsКампании с награди. Всички активни кампании с награди (събития в целия Twitch, значки за чата, награди от партньори), в campaigns.
GET /badgesГлобални значки за чата. Глобалните значки за чата в Twitch, по един елемент на версия в badges, с начина на получаване, когато е известен.

Удостоверяване

За четене на /drops, /rewards и /badges не са нужни нито акаунт, нито ключ. Анонимните извиквания се броят по IP адрес: 1 заявка на всеки 5 мин за всеки маршрут.

Ключовете са безплатни: влезте с 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 ключ

Ключът е безплатен. Той вдига лимита ви от 1 заявка на всеки 5 мин до 1 заявка на минута за всеки маршрут, а таблото ви показва трафика му.

  1. Влезте с Discord, Twitch или GitHub: без парола, без формуляри.
  2. Отворете API ключове в таблото си и създайте ключ с името на вашия бот или сайт.
  3. Копирайте ключа, когато бъде показан (само веднъж), и го изпращайте в заглавката X-API-Key от сървъра си.

Получаване на кампании за Drops

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

Всички активни кампании за Drops, групирани по игра: по един елемент от games на игра, кампаниите ѝ в rewards, с времето на последното сканиране на Twitch и лимита ви на заявките.

Тяло на отговора

ПолеТипОписание
gamesGame[]Активните кампании, в реда от последното сканиране. Празен масив е валиден отговор.
refreshedAtstring (ISO 8601) | nullВремето на последното успешно сканиране на Twitch, null преди първото.
rateLimit{ limit, remaining, resetAt }Лимитът ви за този маршрут след това извикване, както го съобщават заглавките ratelimit-*: limit заявки на прозорец, remaining все още разрешени и resetAt – кога целият лимит се възстановява (ISO 8601).

Game

Един елемент от games.

ПолеТипОписание
gameIdstringTwitch ID на играта.
gameDisplayNamestringИме на играта.
gameBoxArtURLstring (URL)Обложка на играта, 120×160.
startAtstring (ISO 8601)Начало на най-ранната кампания на играта.
endAtstring (ISO 8601)Край на най-късната кампания на играта.
rewardsDropCampaign[]Кампаниите за Drops на играта.
Полета на DropCampaign, TimeBasedDrop и Benefit

DropCampaign

Кампания за Drops, в rewards на игра.

ПолеТипОписание
idstringTwitch ID на кампанията.
name, descriptionstringИме и описание, зададени от издателя.
owner{ id, name }Издателят, който провежда кампанията.
game{ id, displayName, slug }Играта на кампанията.
statusstringСтатус в Twitch, ACTIVE за текуща кампания.
startAt, endAtstring (ISO 8601)Период на провеждане на кампанията.
imageURLstring (URL)Изображение на кампанията.
detailsURL, accountLinkURLstring (URL)Страницата с подробности и страницата за свързване на акаунт на издателя.
allow{ isEnabled, channels? }Каналите, на които е позволено да дават Drops, когато isEnabled е true; иначе всеки канал, който излъчва играта. displayName може да е null или да липсва.
timeBasedDropsTimeBasedDrop[]Drops, печелени с гледане.
eventBasedDropsunknown[]Drops, печелени чрез събития, предадени както идват от Twitch.
firstSeenAtstring (ISO 8601) | nullКога този API е видял кампанията за първи път. Кампания, която се върне по-малко от ден след като е изчезнала от списъка, запазва датата си. null за кампаниите, които API вече е предоставял, когато това поле се е появило.

TimeBasedDrop

Награда Drops, печелена с гледане, в timeBasedDrops.

ПолеТипОписание
id, namestringTwitch ID и име на наградата.
startAt, endAtstring (ISO 8601)Период, в който наградата може да бъде спечелена.
requiredMinutesWatchednumberНужни минути гледане.
requiredSubsnumberНужни абонаменти.
repeat{ everyHours, times } | nullДобавено от този API: колко често Drop се получава отново, с times (колко пъти) и everyHours (24: веднъж на ден; null, когато Twitch не казва). requiredMinutesWatched тогава е времето за гледане за един период. null за Drop, който се получава веднъж.
preconditionDropsunknownDrops, които трябва да спечелите първо, предадени както идват от Twitch.
benefitEdges{ benefit: Benefit, entitlementLimit }[]Какво дава наградата и колко пъти може да бъде получена.

Benefit

Предмет в играта, в benefitEdges.

ПолеТипОписание
id, namestringTwitch 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, brandstringTwitch ID, име и марка на кампанията.
statusstringСтатус към момента на заявката, определен по датите: UPCOMING преди startsAt, ACTIVE до endsAt, след това EXPIRED.
summary, instructionsstringТекстове, показвани от Twitch.
startsAt, endsAtstring (ISO 8601)Период на провеждане на кампанията.
image{ image1xURL }Изображение на кампанията.
aboutURL, externalURLstring (URL)Страница за помощ и външна страница на кампанията.
isSitewidebooleanДали се брои всеки канал, а не само тези на дадена игра.
game{ id, displayName, slug }?Играта на кампанията, ако има такава.
rewardValueURLParamstringСтойност, която Twitch добавя към връзките за получаване на наградите.
unlockRequirements{ minuteWatchedGoal, subsGoal }Нужни минути гледане и абонаменти.
rewardGroupsRewardGroup[]?Награди, печелени по една група наведнъж, всяка група със своя цел: по една награда на ден означава по една група на ден. Само когато Twitch ги изпраща.
rewardsReward[]Наградите на кампанията, включително тези от групите ѝ, всяка по веднъж.
firstSeenAtstring (ISO 8601) | nullКога този API е видял кампанията за първи път. Кампания, която се върне по-малко от ден след като е изчезнала от списъка, запазва датата си. null за кампаниите, които API вече е предоставял, когато това поле се е появило.
Полета на наградите

RewardGroup

Група награди от кампания с награди, печелени заедно.

ПолеТипОписание
idstringTwitch ID на групата.
unlockRequirements{ minuteWatchedGoal, subsGoal, turboSubsGoal?, eventTriggerGoal? }Какво изисква групата. Twitch добавя тук цели за Turbo и събития.
repeat{ everyHours, times } | nullКолко често групата се получава отново, както repeat на Drop: minuteWatchedGoal тогава е времето за гледане за един период. null за група, която се получава веднъж.
categories{ id, displayName, slug }[]Категориите, чиито канали на живо се зачитат, коя да е от тях; празно, когато Twitch не посочва нито една.
rewardsReward[]Наградите на групата, изброени също в rewards на кампанията.

Reward

Награда от кампания с награди.

ПолеТипОписание
id, namestringTwitch 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 при щракване върху значката и връзката към това; null, когато Twitch не дава такава.
firstSeenAtstring (ISO 8601) | nullКога този API е видял значката за първи път. Ако значката се върне повече от 7 дни след като Twitch я е премахнал, тя получава нова дата; ако се върне по-рано, запазва предишната. null за значките, които вече са били там при първото му извличане.
requirementBadgeRequirement | nullКак се получава; null, когато този API не знае.
Полета на BadgeRequirement

BadgeRequirement

Как се получава значка: от кампанията за Drops, която я дава (DROPS), или от собственото описание на Twitch за значка за абонамент или гледане (TWITCH_DESCRIPTION).

ПолеТипОписание
source'DROPS' | 'TWITCH_DESCRIPTION'DROPS или TWITCH_DESCRIPTION.
watchTimeOnlybooleantrue точно когато е достатъчно да се гледа: кампания DROPS, която изисква време за гледане (requiredMinutes над 0) и никакъв абонамент (requiredSubs е 0).
requiredMinutes, requiredSubsnumberНужни минути гледане и абонаменти или подарени абонаменти.
gameId, gameNamestringИграта: нейното Twitch ID (null, когато е неизвестно) и името ѝ.
channels, channelCountstring[] (≤ 5), numberПървите 5 канала, които я дават (потребителски имена), и колко са общо; 0: всеки канал, който излъчва играта.
startAt, endAtstring (ISO 8601) | nullКога тече кампанията; null за TWITCH_DESCRIPTION. Приключила кампания остава в списъка.
campaignId, campaignNamestring | nullКампанията за Drops; null за TWITCH_DESCRIPTION.
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 в този списък: еволюция на Pokémon изисква предишния си стадий (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 минути, така че по-честите заявки не носят нищо ново.

КлиентЛимит за маршрутБроене по
Анонимно1 заявка на всеки 5 минIP адрес
С API ключ1 заявка на минута по подразбиране, с увеличение при поискванеAPI ключ

Заглавки на отговора

Заглавки, които API чете и изпраща.

ЗаглавкаПосокаОписание
x-last-updated-atresponseВремето на последното успешно извличане от Twitch: сканирането за /drops и /rewards, значките за /badges.
x-refresh-interval-secondsresponseСекунди между две извличания от Twitch: по-честите заявки връщат същите данни (60 за /drops и /rewards, 300 за /badges).
ratelimit-limitresponseРазрешени заявки в прозореца за този маршрут.
ratelimit-remainingresponseОставащи заявки в текущия прозорец.
ratelimit-resetresponseСекунди, докато отново бъде разрешена заявка.
ratelimit-policyresponseПолитиката във формат <лимит>;w=<прозорец в секунди>.
retry-afterresponseСекунди за изчакване преди нов опит, при отговор 429 или 503.
x-api-keyrequestВашият API ключ: по избор за всеки маршрут.
x-api-key-statusresponseinvalid, когато изпратеният ключ е непознат, отменен или деактивиран: извикването се отчете като анонимно, към лимита на вашия IP адрес.
etagresponseЕтикет на този отговор. Изпратете го обратно в If-None-Match: докато данните не са се променили, отговорът е 304 и не се брои към лимита ви.
if-none-matchrequestETag от последния ви отговор, по избор: непроменен списък отговаря с 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/drops/dropsgames: по един елемент на игра, кампаниите ѝ в rewards. Изгледът „Мрежа“ рисува startAt и endAt на всяка кампания.
Страница на игра/drops/<game>/dropsЕдин елемент от games, съпоставен по gameId. Всяка кампания е games[i].rewards[j]; наградите ѝ са benefitEdges от timeBasedDrops, с requiredMinutesWatched.
Награди/rewards/rewardscampaigns: по един елемент на кампания с награди, наградите ѝ в rewards и условията ѝ в unlockRequirements.
Страница на кампания с награди/rewards/<campaign>/rewardsЕдин елемент от campaigns, съпоставен по id; наградите му са в rewards.
Значки/badges/badgesbadges: всички елементи, първо тези с requirement, с начина на получаване. Изгледът „Мрежа“ рисува requirement.startAt и requirement.endAt на всяка значка.
Страница на значка/badges/<badge>/badgesЕдин елемент от badges, съпоставен по setId и versionId; „Как се получава“ е неговото requirement.