Contents

Clips Reference

Endpoint Description
Get Clip

Gets details about a specified clip. Clips are referenced by a globally unique string called a 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 globally unique string called a slug.

Authentication

None

URL

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

Optional Query String Parameters

None

Example Request

This gets the clip referenced by the slug AmazonianEncouragingLyrebirdAllenHuhu.

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

Example Response

{
  "slug": "AmazonianEncouragingLyrebirdAllenHuhu",
  "tracking_id": "13160765",
  "url": "https://clips.twitch.tv/AmazonianEncouragingLyrebirdAllenHuhu?tt_medium=clips_api&tt_content=url",
  "embed_url": "https://clips.twitch.tv/embed?clip=AmazonianEncouragingLyrebirdAllenHuhu&tt_medium=clips_api&tt_content=embed",
  "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>",
  "broadcaster": {
    "id": "12826",
    "name": "twitch",
    "display_name": "Twitch",
    "channel_url": "https://www.twitch.tv/twitch",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-8a8c5be2e3b64a9a-300x300.png"
  },
  "curator": {
    "id": "59222117",
    "name": "skiptoplay",
    "display_name": "SkipToPlay",
    "channel_url": "https://www.twitch.tv/skiptoplay",
    "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/skiptoplay-profile_image-1d66e001a46b0c9d-300x300.png"
  },
  "vod": {
    "id": "107049351",
    "url": "https://www.twitch.tv/videos/107049351?t=0s"
  },
  "game": "",
  "language": "en",
  "title": "Clip Title Editing",
  "views": 106,
  "duration": 32.000333,
  "created_at": "2016-12-14T16:28:49Z",
  "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"
  }
}

Get Top Clips

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

Authentication

None

URL

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

Optional Query String Parameters

Name Type Description
channel string Channel name. If this is specified, top clips for only this channel are returned; otherwise, top clips for all channels are returned. If both channel and game are specified, game is ignored.
cursor string Tells the server where to start fetching the next set of results, in a multi-page response.
game string Game name. (Game names can be retrieved with the Search Games endpoint.) If this is specified, top clips for only this game are returned; otherwise, top clips for all games are returned. If both channel and game are specified, game is ignored.
language string Comma-separated list of languages, which constrains the languages of videos returned. Examples: es, en,es,th. If no language is specified, all languages are returned. Default: "". Maximum: 28 languages.
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.

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

Example Response

{
  "clips": [
    {
      "slug": "ShakingPoliteQuailGingerPower",
      "tracking_id": "64579613",
      "url": "https://clips.twitch.tv/ShakingPoliteQuailGingerPower?tt_medium=clips_api&tt_content=url",
      "embed_url": "https://clips.twitch.tv/embed?clip=ShakingPoliteQuailGingerPower&tt_medium=clips_api&tt_content=embed",
      "embed_html": "<iframe src='https://clips.twitch.tv/embed?clip=ShakingPoliteQuailGingerPower&tt_medium=clips_api&tt_content=embed' width='640' height='360' frameborder='0' scrolling='no' allowfullscreen='true'></iframe>",
      "broadcaster": {
        "id": "12826",
        "name": "twitch",
        "display_name": "Twitch",
        "channel_url": "https://www.twitch.tv/twitch",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/twitch-profile_image-8a8c5be2e3b64a9a-300x300.png"
      },
      "curator": {
        "id": "151724913",
        "name": "comakarzi",
        "display_name": "comakarzi",
        "channel_url": "https://www.twitch.tv/comakarzi",
        "logo": null
      },
      "vod": {
        "id": "92629129",
        "url": "https://www.twitch.tv/videos/92629129?t=3h6m15s"
      },
      "game": "TwitchCon 2016",
      "language": "en",
      "title": "TwitchCon 2016 - Kappa Theater - Day 3/3 - twitch.tv/twitchcon - twitchcon.com/schedule",
      "views": 3,
      "duration": 32.031678,
      "created_at": "2017-04-05T01:42:38Z",
      "thumbnails": {
        "medium": "https://clips-media-assets.twitch.tv/vod-92629129-offset-11174-preview-480x272.jpg",
        "small": "https://clips-media-assets.twitch.tv/vod-92629129-offset-11174-preview-260x147.jpg",
        "tiny": "https://clips-media-assets.twitch.tv/vod-92629129-offset-11174-preview-86x45.jpg"
      }
    }
  ],
  "_cursor": "Mw=="
}

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

GET 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 top clip for games followed by the user identified by OAuth token cfabdegwdoklmawdzdo98xt2fo512y. Results are ordered by popularity.

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

Example Response

{
  "clips": [
    {
      "slug": "DeliciousExcitedSalmonStinkyCheese",
      "tracking_id": "13211072",
      "url": "https://clips.twitch.tv/DeliciousExcitedSalmonStinkyCheese?tt_medium=clips_api&tt_content=url",
      "embed_url": "https://clips.twitch.tv/embed?clip=DeliciousExcitedSalmonStinkyCheese&tt_medium=clips_api&tt_content=embed",
      "embed_html": "<iframe src='https://clips.twitch.tv/embed?clip=DeliciousExcitedSalmonStinkyCheese&tt_medium=clips_api&tt_content=embed' width='640' height='360' frameborder='0' scrolling='no' allowfullscreen='true'></iframe>",
      "broadcaster": {
        "id": "52968416",
        "name": "asmodaitv",
        "display_name": "AsmodaiTV",
        "channel_url": "https://www.twitch.tv/asmodaitv",
        "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/asmodaitv-profile_image-0f62202546cff589-300x300.png"
      },
      "curator": {
        "id": "32879573",
        "name": "zoterek",
        "display_name": "Zoterek",
        "channel_url": "https://www.twitch.tv/zoterek",
        "logo": null
      },
      "vod": {
        "id": "107324228",
        "url": "https://www.twitch.tv/videos/107324228?t=6h4m29s"
      },
      "game": "Hearthstone",
      "language": "no",
      "title": "CoL.Asmodai Legend Ladder",
      "views": 182047,
      "duration": 29.999667,
      "created_at": "2016-12-14T08:59:02Z",
      "thumbnails": {
        "medium": "https://clips-media-assets.twitch.tv/23926639360-offset-21868-preview-480x272.jpg",
        "small": "https://clips-media-assets.twitch.tv/23926639360-offset-21868-preview-260x147.jpg",
        "tiny": "https://clips-media-assets.twitch.tv/23926639360-offset-21868-preview-86x45.jpg"
      }
    }
  ],
  "_cursor": "MQ=="
}
+