Clips

Create and manage clips on Twitch

View as markdown
Provide feedback for this page

Get Clips

Gets one or more video clips that were captured from streams. For information about clips, see How to use clips.

You must specify exactly one of the broadcaster_id, game_id and id query parameters; the request fails if you specify none of them or more than one.

When using pagination for clips, note that the maximum number of results returned over multiple requests will be approximately 1,000. If additional results are necessary, paginate over different query parameters such as multiple 'started_at' and 'ended_at' timeframes to refine the search.

Endpoint

GEThttps://api.twitch.tv/helix/clips

Authorization

Requires one of the following:

Query Parameters

  • broadcaster_idString
    An ID that identifies the broadcaster whose video clips you want to get. Use this parameter to get clips that were captured from the broadcaster's streams.
  • game_idString
    An ID that identifies the game whose clips you want to get. Use this parameter to get clips that were captured from streams that were playing this game.
  • idString

    An ID that identifies the clip to get. To specify more than one ID, include this parameter for each clip you want to get. For example, 'id=foo&id=bar'. You may specify a maximum of 100 IDs. The API ignores duplicate IDs and IDs that aren't found.

    If you specify id, the API ignores the started_at, ended_at, is_featured, first, and after query parameters, and the response doesn't include a cursor.

  • started_atString
    The start date used to filter clips. The API returns only clips within the start and end date window. Specify the date and time in RFC3339 format. The API truncates the start and end times to the minute.
  • ended_atString
    The end date used to filter clips. If not specified, the time window is the start date plus one week. Specify the date and time in RFC3339 format. The API ignores this parameter if you don't specify started_at.
  • firstInteger
    The maximum number of clips to return per page in the response. The minimum page size is 1 clip per page and the maximum is 100. The default is 20.
  • afterString
    The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More
  • is_featuredBoolean
    A Boolean value that determines whether the response includes featured clips. If true, returns only clips that are featured. If false, returns only clips that aren't featured. All clips are returned if this parameter is not present.

Response Body

  • dataObject[]
    The list of video clips. For clips returned by game_id or broadcaster_id, the list is in descending order by view count. For lists returned by id, the order isn't guaranteed to match the order of the input IDs. The list is always empty if the request comes from a region where videos aren't available.
    Hide child attributesShow child attributes
    • data.idString
      An ID that uniquely identifies the clip.
    • data.urlString
      A URL to the clip.
    • data.embed_urlString
      A URL that you can use in an iframe to embed the clip (see Embedding Video and Clips).
    • data.broadcaster_idString
      An ID that identifies the broadcaster that the video was clipped from.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.creator_idString
      An ID that identifies the user that created the clip.
    • data.creator_nameString
      The user's display name.
    • data.video_idString
      An ID that identifies the video that the clip came from. This field contains an empty string if the video is not available.
    • data.game_idString
      The ID of the game that was being played when the clip was created.
    • data.languageString
      The ISO 639-1 two-letter language code that the broadcaster broadcasts in. For example, en for English. The value is other if the broadcaster uses a language that Twitch doesn't support.
    • data.titleString
      The title of the clip.
    • data.view_countInteger
      The number of times the clip has been viewed.
    • data.created_atString
      The date and time of when the clip was created. The date and time is in RFC3339 format.
    • data.thumbnail_urlString
      A URL to a thumbnail image of the clip.
    • data.durationFloat
      The length of the clip, in seconds. Precision is 0.1.
    • data.vod_offsetIntegerNullable

      The zero-based offset, in seconds, to where the clip starts in the video (VOD). Is null if the video is not available or hasn't been created yet from the live stream (see 'video_id').

      Note that there's a delay between when a clip is created during a broadcast and when the offset is set. During the delay period, 'vod_offset' is null. The delay is indeterminant but is typically minutes long.

    • data.is_featuredBoolean
      A Boolean value that indicates if the clip is featured or not.
  • paginationObject
    The information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
    Hide child attributesShow child attributes
    • pagination.cursorString
      The cursor used to get the next page of results. Set the request's after query parameter to this value.

Response Codes

200OK
Successfully retrieved the list of video clips.
400Bad Request
  • The id or game_id or broadcaster_id query parameter is required.
  • The id, game_id, and broadcaster_id query parameters are mutually exclusive; you may specify only one of them.
  • Every id query parameter is an empty string.
  • The number of id query parameters exceeds the maximum allowed.
  • The ID in game_id is not valid.
  • The first query parameter is outside the allowed range of values.
  • The cursor specified in the after query parameter is not valid.
  • The started_at or ended_at query parameter isn't in RFC3339 format.
401Unauthorized
  • The Authorization header is required and must contain an app access token or user access token.
  • The OAuth token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the OAuth token.
404Not Found
  • The ID in game_id was not found.
Request Example
curl -X GET 'https://api.twitch.tv/helix/clips?id=AwkwardHelplessSalamanderSwiftRage' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'
Response Example
{
  "data": [
    {
      "id": "AwkwardHelplessSalamanderSwiftRage",
      "url": "https://clips.twitch.tv/AwkwardHelplessSalamanderSwiftRage",
      "embed_url": "https://clips.twitch.tv/embed?clip=AwkwardHelplessSalamanderSwiftRage",
      "broadcaster_id": "67955580",
      "broadcaster_name": "ChewieMelodies",
      "creator_id": "53834192",
      "creator_name": "BlackNova03",
      "video_id": "205586603",
      "game_id": "488191",
      "language": "en",
      "title": "babymetal",
      "view_count": 10,
      "created_at": "2017-11-30T22:34:18Z",
      "thumbnail_url": "https://clips-media-assets.twitch.tv/157589949-preview-480x272.jpg",
      "duration": 60,
      "vod_offset": 480,
      "is_featured": false
    }
  ]
}

Create Clip

Creates a clip from the broadcaster's stream.

This API captures up to 90 seconds of the broadcaster's stream. The 90 seconds spans the point in the stream from when you called the API. For example, if you call the API at the 4:00 minute mark, the API captures from approximately the 2:35 mark to approximately the 4:05 minute mark. Twitch tries its best to capture 90 seconds of the stream, but the actual length may be less. This may occur if you begin capturing the clip near the beginning or end of the stream.

By default, Twitch publishes up to the last 30 seconds of the 90 seconds window and provides a default title for the clip. To specify the title and the portion of the 90 seconds window that's used for the clip, use the URL in the response's 'edit_url' field. You can specify a clip that's from 5 seconds to 60 seconds in length. The URL is valid for up to 24 hours or until the clip is published, whichever comes first.

Creating a clip is an asynchronous process that can take a short amount of time to complete. To determine whether the clip was successfully created, call Get Clips using the clip ID that this request returned. If Get Clips returns the clip, the clip was successfully created. If after 60 seconds Get Clips hasn't returned the clip, assume it failed.

Endpoint

POSThttps://api.twitch.tv/helix/clips

Authorization

Requires one of the following:

Query Parameters

  • broadcaster_idStringRequired
    The ID of the broadcaster whose stream you want to create a clip from.
  • titleString
    The title of the clip.
  • durationFloat
    The length of the clip in seconds. Possible values range from 5 to 60 inclusively with a precision of 0.1. The default is 30.

Response Body

  • dataObject[]
    A list containing the created clip.
    Hide child attributesShow child attributes
    • data.idString
      An ID that uniquely identifies the clip.
    • data.edit_urlString

      A URL that you can use to edit the clip's title, identify the part of the clip to publish, and publish the clip. Learn More

      The URL is valid for up to 24 hours or until the clip is published, whichever comes first.

Response Codes

202Accepted
Successfully started the clip process.
400Bad Request
  • The broadcaster_id query parameter is required.
  • The category is not clippable.
  • The title did not pass AutoMod checks.
401Unauthorized
  • The Authorization header is required and must specify user access token.
  • The user access token must include the clips:edit scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403Forbidden
  • The broadcaster has restricted the ability to capture clips to followers and/or subscribers only.
  • The specified broadcaster has not enabled clips on their channel.
  • The user is banned or timed out from the broadcaster's channel.
404Not Found
  • The broadcaster in the broadcaster_id query parameter must be broadcasting live. This error is also returned if broadcaster_id doesn't identify an existing broadcaster.
  • The broadcaster is banned.
Request Example
curl -X POST 'https://api.twitch.tv/helix/clips?broadcaster_id=141981764' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'
Response Example
{
  "data": [
    {
      "id": "FiveWordsForClipSlug",
      "edit_url": "https://www.twitch.tv/twitchdev/clip/FiveWordsForClipSlug"
    }
  ]
}

Get Clips Download

Provides URLs to download the video file(s) for the specified clips.

For information about clips, see How to use clips. These links are temporary and should have a long-term expectation to expire.

Rate Limits: Limited to 100 requests per minute.

Endpoint

GEThttps://api.twitch.tv/helix/clips/downloads

Authorization

Requires one of the following:

  • A user access token that includes the editor:manage:clips or channel:manage:clips scope.
  • An app access token.The application, through prior authorization, must have been granted:
    • The editor:manage:clips or channel:manage:clips scope for the user represented by the editor_id query parameter.

Query Parameters

  • editor_idStringRequired
    The User ID of the editor for the channel you want to download a clip for. If using the broadcaster's auth token, this is the same as broadcaster_id. This must match the user_id in the user access token.
  • broadcaster_idStringRequired
    The ID of the broadcaster you want to download clips for.
  • clip_idStringRequired
    The ID that identifies the clip you want to download. Include this parameter for each clip you want to download, up to a maximum of 10 clips. For example, 'clip_id=SleepyGiftedPeppermintNerfRedBlaster-KbkBXYt3lOk3jy8-&clip_id=WimpyAltruisticKleeKeyboardCat-EiY5yMrEwZ4i4gwC'.

Response Body

  • dataObject[]
    List of clips and their download URLs. Clips that weren't found, that the editor may not access, or that belong to a different broadcaster are left out of the list.
    Hide child attributesShow child attributes
    • data.clip_idString
      An ID that uniquely identifies the clip.
    • data.landscape_download_urlStringNullable
      The landscape URL to download the clip. This field is 'null' if the URL is not available.
    • data.portrait_download_urlStringNullable
      The portrait URL to download the clip. This field is 'null' if the URL is not available.

Response Codes

200OK
Successfully retrieved the clip download URL(s).
400Bad Request
  • The editor_id query parameter is required.
  • The broadcaster_id query parameter is required.
  • The request must include from 1 through 10 clip_id query parameters.
  • The ID in editor_id must match the user ID in the user access token.
401Unauthorized
  • The OAuth token is not valid.
  • The Authorization header is required and must contain a user access token or app access token.
  • The user access token must include the editor:manage:clips or channel:manage:clips scope.
  • If you use an app access token, the user in editor_id must have authorized your app with the editor:manage:clips or channel:manage:clips scope.
  • The access token is not valid
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403Forbidden
The user is not an editor for the specified broadcaster.
500Internal Error
Internal Server Error.
Request Example
curl -X GET 'https://api.twitch.tv/helix/clips/downloads?broadcaster_id=141981764&editor_id=141981764&clip_id=SpinelessCloudyLeopardMcaT' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'
Response Example
{
  "data": [
    {
      "clip_id": "SpinelessCloudyLeopardMcaT",
      "landscape_download_url": "https://production.assets.clips.twitchcdn.net/542j...",
      "portrait_download_url": null
    }
  ]
}

Create Clip From VOD

Creates a clip from the broadcaster's VOD.

Creates a clip from a broadcaster's VOD on behalf of the broadcaster or an editor of the channel. Since a live stream is actively creating a VOD, this endpoint can also be used to create a clip from earlier in the current stream.

The duration of a clip can be from 5 seconds to 60 seconds in length, with a default of 30 seconds if not specified.

'vod_offset' indicates where the clip will end. In other words, the clip will start at ('vod_offset' - 'duration') and end at 'vod_offset'. This means that the value of 'vod_offset' must greater than or equal to the value of 'duration'.

The URL in the response's 'edit_url' field allows you to edit the clip's title, feature the clip, create a portrait version of the clip, download the clip media, and share the clip directly to social platforms.

Endpoint

POSThttps://api.twitch.tv/helix/videos/clips

Authorization

Requires one of the following:

  • A user access token that includes the editor:manage:clips or channel:manage:clips scope.
  • An app access token.The application, through prior authorization, must have been granted:
    • The editor:manage:clips or channel:manage:clips scope for the user represented by the editor_id query parameter.

Query Parameters

  • editor_idStringRequired
    The user ID of the editor for the channel you want to create a clip for. If using the broadcaster's auth token, this is the same as broadcaster_id. This must match the user_id in the user access token.
  • broadcaster_idStringRequired
    The user ID for the channel you want to create a clip for.
  • vod_idStringRequired
    ID of the VOD the user wants to clip.
  • vod_offsetIntegerRequired
    The zero-based offset, in seconds, to where the clip should end in the video (VOD). See this endpoint's description for more information on how to use this parameter.
  • durationFloat
    The length of the clip, in seconds. Precision is 0.1. Defaults to 30. Min: 5 seconds, Max: 60 seconds.
  • titleStringRequired
    The title of the clip.

Response Body

  • dataObject[]
    A list containing the created clip.
    Hide child attributesShow child attributes
    • data.idString
      An ID that uniquely identifies the clip.
    • data.edit_urlString
      A URL you can use to edit the clip's title, feature the clip, create a portrait version of the clip, download the clip media, and share the clip directly to third-party platforms.

Response Codes

202Accepted
Successfully started the clip process.
400Bad Request
  • Validation errors: Invalid source type, missing required fields.
  • The broadcaster_id query parameter is required.
  • The category is not clippable.
  • The title did not pass AutoMod checks.
  • The value of vod_offset must be greater than or equal to the value of duration.
  • The VOD in vod_id was not found, or it doesn't belong to the broadcaster in broadcaster_id.
401Unauthorized
  • The ID in editor_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token or an app access token.
  • The user access token must include the editor:manage:clips or channel:manage:clips scope.
  • If you use an app access token, the user in editor_id must have authorized your app with the editor:manage:clips or channel:manage:clips scope.
  • The OAuth token is not valid.
  • The ID in the Client-Id header must match the Client ID in the OAuth token.
403Forbidden
  • The broadcaster has restricted the ability to capture clips to followers and/or subscribers only.
  • The specified broadcaster has not enabled clips on their channel.
  • The user defined by the editor_id is not authorized to create Clips.
  • The user is banned or timed out from the broadcaster's channel.
404Not Found
  • The VOD is not found.
  • The broadcaster is banned.
Request Example
curl -X POST 'https://api.twitch.tv/helix/videos/clips?broadcaster_id=141981764&editor_id=12826&vod_id=2277656159&vod_offset=434&title=Standard%20Output' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'
Response Example
{
  "data": [
    {
      "id": "FiveWordsForClipSlug",
      "edit_url": "https://www.twitch.tv/twitchdev/clip/FiveWordsForClipSlug"
    }
  ]
}