Clips Discovery API (V4)

The Clips Discovery API provides a way to discover user-generated, short-form video content about a game or channel or from a user’s followed games. The API allows you to retrieve Clips in multiple ways, such as for a specified time period or based on viewcount or trending popularity.

You can use the Clips Discovery API in conjunction with video embedding to showcase the top content about your game or channel directly on your own Web site. (See the Embedding Video guide.)

This guide cover two use cases for the Clips Discovery API:

  • Retrieving the trending Clips for a specified game.
  • Retrieving the most viewed Clips for a specified channel.

Both scenarios take advantage of video embedding, to show a complete, end-to-end experience.

Clips Discovery API Reference documentation is at the end of this guide.

Versioning

All API calls must be versioned. The Clips Discovery API uses V4 of the Twitch API. You can set the version by sending an Accept header with the value of application/vnd.twitchtv.v4+json.

In this example, we use a simple HTML page that requests Clips for a specified game and embeds Clips for the top 10 trending Clips.

First, we create a simple HTML page with a div id that we will use later to display the embedded Clips:

1
2
3
4
5
6
7
8
<html>
<head>
   <title>Clips Carousel</title>
</head>
<body>
   <div id="clips-display"></div>
</body>
</html>

Second, we add JavaScript to the page, to request the Clips and handle the event when data has loaded:

1
2
3
4
5
6
7
var httpRequest = new XMLHttpRequest();

httpRequest.addEventListener('load', clipsLoaded);
httpRequest.open('GET', 'https://api.twitch.tv/kraken/clips/top?limit=10&game=Overwatch&trending=true');
httpRequest.setRequestHeader('Client-ID', 'uo6dggojyb8d6soh92zknwmi5ej1q2');
httpRequest.setRequestHeader('Accept', 'application/vnd.twitchtv.v4+json');
httpRequest.send();

Finally, we add JavaScript to display the Clips embeds on the page:

1
2
3
4
5
6
7
8
9
10
function clipsLoaded() {
    var clipsDisplay = document.getElementById('clips-display'),
        clipList = JSON.parse(httpRequest.responseText);

    clipList.clips.forEach(function(clip, index, array) {
        clipItem = document.createElement('div');
        clipItem.innerHTML = clip.embed_html;
        clipsDisplay.appendChild(clipItem);
    });
}

Example: Retrieving Most Viewed Clips for a Channel

For this example, we re-use the HTML and rendering above and simply change the JavaScript call in the second part, to get the most-viewed Clips:

1
2
3
4
5
6
7
var httpRequest = new XMLHttpRequest();

httpRequest.addEventListener('load', clipsLoaded);
httpRequest.open('GET', 'https://api.twitch.tv/kraken/clips/top?limit=10&channel=moonmoon_ow');
httpRequest.setRequestHeader('Client-ID', 'uo6dggojyb8d6soh92zknwmi5ej1q2');
httpRequest.setRequestHeader('Accept', 'application/vnd.twitchtv.v4+json');
httpRequest.send();

Clips Discovery API Reference

Endpoint Description
Get Clip Gets details about a specified Clip. Clips are referenced by a randomly generated string called a slug. Every clip has a globally unique slug.
Get Top Clips Gets the top Clips which meet a specified set of parameters.
Get Followed Clips Gets the top Clips for the games followed by a specified user.

Get Clip

Gets details about a specified Clip. Clips are referenced by a randomly generated string called a slug. Every clip has a globally unique slug.

Authentication

None

URL

https://api.twitch.tv/kraken/clips/<slug>

Optional Query String Parameters

None

Example Request

This gets the Clip referenced by the slug AmazonianEncouragingLyrebirdAllenHuhu.

1
2
3
curl -H 'Accept: application/vnd.twitchtv.v4+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/clips/AmazonianEncouragingLyrebirdAllenHuhu'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
   "broadcaster": {
      "channel_url": "https://www.twitch.tv/twitch",
      "display_name": "Twitch",
      "id": "12826",
      "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
      "name": "twitch"
   },
   "created_at": "2016-12-14T16:28:49Z",
   "curator": {
      "channel_url": "https://www.twitch.tv/skiptoplay",
      "display_name": "SkipToPlay",
      "id": "59222117",
      "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/skiptoplay-profile_image-323645c2f79a6f44-300x300.jpeg",
      "name": "skiptoplay"
   },
   "duration": 32.000333,
   "embed_html": "<iframe src='https://clips.twitch.tv/embed?clip=AmazonianEncouragingLyrebirdAllenHuhu&tt_medium=clips_api&tt_content=embed' width='640' height='360' frameborder='0' scrolling='no' allowfullscreen='true'></iframe>",
   "embed_url": "https://clips.twitch.tv/embed?clip=AmazonianEncouragingLyrebirdAllenHuhu&tt_medium=clips_api&tt_content=embed",
   "game": "",
   "id": "AmazonianEncouragingLyrebirdAllenHuhu",
   "language": "en",
   "thumbnails": {
      "medium": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-480x272.jpg",
      "small": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-260x147.jpg",
      "tiny": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-86x45.jpg"
   },
   "title": "Clip Title Editing",
   "tracking_id": "13160765",
   "url": "https://clips.twitch.tv/AmazonianEncouragingLyrebirdAllenHuhu?tt_medium=clips_api&tt_content=url",
   "views": 82,
   "vod": {
      "id": "107049351",
      "url": "https://www.twitch.tv/videos/107049351?t=0s"
   }
}

Get Top Clips

Gets the top Clips which meet a specified set of parameters.

Authentication

None

URL

https://api.twitch.tv/kraken/clips/top

Optional Query String Parameters

Name Type Description
channel string Comma-separated list of channel names. If this is not specified, top Clips for all channels are returned. If both channel and game are specified, game is ignored. Maximum: 10.
cursor string Tells the server where to start fetching the next set of results, in a multi-page response.
game string Comma-separated list of case-sensitive game names. Game names can be retrieved with the Search Games endpoint. If this is not specified, top Clips for all games are returned. If both channel and game are specified, game is ignored. Maximum: 10.
limit long Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
period string The window of time to search for Clips. Valid values: day, week, month, all. Default: week.
trending boolean If true, the Clips returned are ordered by popularity; otherwise, by viewcount. Default: false.

Example Request

This gets the most popular Clip on the Twitch channel during the last month.

1
2
3
curl -H 'Accept: application/vnd.twitchtv.v4+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/clips/top?channel=Twitch&period=month&trending=true&limit=1'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
   "_cursor": "MQ==",
   "clips": [{
      "broadcaster": {
         "channel_url": "https://www.twitch.tv/twitch",
         "id": "12826",
         "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-bd6df6672afc7497-300x300.png",
         "name": "twitch",
         "display_name": "Twitch"
      },
      "created_at": "2016-12-14T16:28:49Z",
      "curator": {
         "channel_url": "https://www.twitch.tv/skiptoplay",
         "id": "59222117",
         "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/skiptoplay-profile_image-323645c2f79a6f44-300x300.jpeg",
         "name": "skiptoplay",
         "display_name": "skiptoplay"
      },
      "duration": 32.000333,
      "embed_html": "<iframe src='https://clips.twitch.tv/embed?clip=twitch/AdventurousOkapi4Head'></iframe>",
      "embed_url": "https://clips.twitch.tv/embed?clip=twitch/AdventurousOkapi4Head",
      "game": "",
      "id": "twitch/AdventurousOkapi4Head",
      "thumbnails": {
         "medium": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-480x272.jpg",
         "small": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-260x147.jpg",
         "tiny": "https://clips-media-assets.twitch.tv/vod-107049351-offset-26-preview-86x45.jpg"
      },
      "title": "Clip Title Editing",
      "url": "https://clips.twitch.tv/twitch/AdventurousOkapi4Head?tt_medium=clips_api&tt_content=url",
      "views": 2,
      "vod": {
         "id": "107049351",
         "url": "https://www.twitch.tv/twitch/v/107049351?t=27s"
      }
   }]
}

Get Followed Clips

Gets the top Clips for the games followed by a specified user, identified by an OAuth token.

Authentication

Required scope: user_read

URL

https://api.twitch.tv/kraken/clips/followed

Optional Query String Parameters

Name Type Description
limit long Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
cursor string Tells the server where to start fetching the next set of results, in a multi-page response.
trending boolean If true, the Clips returned are ordered by popularity; otherwise, by viewcount. Default: false.

Example Request

This gets the 10 top Clips for games followed by the user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512y. Results are ordered by popularity.

1
2
3
4
curl -H 'Accept: application/vnd.twitchtv.v4+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-H 'Authorization: OAuth cfabdegwdoklmawdzdo98xt2fo512y' \
-X GET 'https://api.twitch.tv/kraken/clips/followed?trending=true'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
   "_cursor": "MQ==",
   "clips": [{
      "broadcaster": {
         "channel_url": "https://www.twitch.tv/ratsmah",
         "id": "43263511",
         "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/ratsmah-profile_image-7397cfdeba10718f-300x300.png",
         "name": "ratsmah",
         "display_name": "ratsmah"
      },
      "created_at": "2016-11-23T15:53:52Z",
      "curator": {
         "channel_url": "https://www.twitch.tv/anarchykb",
         "id": "40989469",
         "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/anarchykb-profile_image-0ffe0232553cd6d0-300x300.jpeg",
         "name": "anarchykb",
         "display_name": "anarchykb"
      },
      "duration": 31.999333,
      "embed_html": "<iframe src='https://clips.twitch.tv/embed?clip=ratsmah/InquisitiveSquirrelPRChase'></iframe>",
      "embed_url": "https://clips.twitch.tv/embed?clip=ratsmah/InquisitiveSquirrelPRChase",
      "game": "Hearthstone: Heroes of Warcraft",
      "id": "ratsmah/InquisitiveSquirrelPRChase",
      "thumbnails": {
         "medium": "https://clips-media-assets.twitch.tv/vod-102873283-offset-7594-preview-480x272.jpg",
         "small": "https://clips-media-assets.twitch.tv/vod-102873283-offset-7594-preview-260x147.jpg",
         "tiny": "https://clips-media-assets.twitch.tv/vod-102873283-offset-7594-preview-86x45.jpg"
      },
      "title": "Happy Thanksgiving! | Last Stream Til Back From Vegas",
      "url": "https://clips.twitch.tv/ratsmah/InquisitiveSquirrelPRChase?tt_medium=clips_api&tt_content=url",
      "views": 213680,
      "vod": {
            "id": "102873283",
            "url": "https://www.twitch.tv/ratsmah/v/102873283?t=2h6m34s"
      }
   }]
}