Today we’re introducing an API endpoint in open beta that allows developers to download video files of Twitch clips on behalf of an authenticated broadcaster or editor of a channel. This provides an official and reliable method to export video content that will empower several use cases including video editing solutions, stream video summaries, broadcasting software scene sources, and many others.
How does it work?
The new endpoint is Get Clips Download. It is designed to be used with either an app access token or a user access token that includes the editor:manage:clips or channel:manage:clips scope. This means that both broadcasters and editors can leverage applications that use this endpoint. Up to 10 clip IDs can be provided with each API request and there is a custom rate limit for this endpoint of 100 requests per minute.
Why is this not included directly in the Get Clips endpoint?
The UserVoice entry for this functionality suggested adding file information to the Get Clips API endpoint response. We’ve provided a dedicated endpoint as unique and temporary file URLs are created for downloads. This ensures that URLs are only created when downloading content is the intent, which further protects access to the broadcaster’s content and supports an efficient API infrastructure.
When will the API graduate from open beta to generally available?
Open betas typically last two weeks. During this time, we encourage developers to try the functionality and provide feedback regarding any issues. While not likely, any changes during the beta phase would be due to bugs or performance issues. The “beta” tag will be removed from the API reference documentation when it moves to generally available.
How do I get started?
Click on the link above to review the documentation. Feel free to leave comments below or join the TwitchDev Discord server for further discussion.
This is great, but doesn’t solve the problem that leaves shoutout clip players broken. Are there any plans to update the Get Clips API endpoint at all? If a shoutout bot can’t retrieve the video of a clip, then shoutouts won’t be able to feature clips like they used to. If it’s the intention of twitch to put an end to the practice of shoutout clips, I’d like to see someone at twitch say that rather than being left in the dark about my broken tools.
Being forced to use a user/app (with editor permissions) token to receive a clip (that’s publicly available anyway) makes this API completely useless to me and many others. We rather need the URL available on the Get Clips API, so that we are able again to use clips as a nice shoutout on events defined by us (e.g. raids)
Edit: It was indeed a me problem. Thanks to Twitch staff for clarifying that the editor_id in the call needs to auth to the clientID with the relevant scope, THEN an App Access token will work.
Why does this endpoint require broadcasters or editor authorization?
Anyone can open a clip’s page and manually download the clip from the share menu without even logging in. Broadcasters can’t even disable the download buttons as far as I can tell, they can only disable direct uploads to social media.
Will the download buttons in the share menu be removed once this is out of beta?
I doubt it as what first party does != what third party supports
That was me, not staff btw
Everyone on this thread is talking about a use case that isn’t covered by the uservoice that I made/wrote and what the API was built to fulfill.
People with alternative use cases that this doesn’t fit would either need to use the embeds to play the clip instead or open a uservoice detialing the use case/API requirements they need.
Twitch built what was asked for here. So a seperate uservoice for a different use case would be needed
This gets my upvote, would love the interactive player to support clips (horizontal and verical) since you’d expect it to support “everything”
Direct MP4’s can be fudgey since the expectation is that it’s gonna be downloaded not used directly, and theres probably other factors, legal and otherwise on allowing third parties to automate over first party manual actions. But I digress. (thats why my original UV was “authorized parties” led as thats eaiser to swing legal imo)
That may be true, that the original reason for the UserVoice was different, but five comments still supported the initial idea. This UserVoice would not have received so many upvotes if we hadn’t lost the clip player and shoutout features (even if they were technically a bug and never intended). It’s nice that there’s now a download function via API, but the votes were raised for a different reason. Personally, I feel a bit screwed over by Twitch. Upvote this UserVoice now: https://twitch.uservoice.com/forums/310213-developers/suggestions/40747189-interactive-frames-for-clips-and-improved-embedded and I really hope it doesn’t take another 6 years before it gets implemented -.-
Just don’t forget best practices when making uservoices or commenting on them. Just saying ‘I want this!’ isn’t as helpful as giving specifics, what’s your usecase, what impact it will have, etc… Votes may show interest but they’re also very easily manipulated by streamers who send their communities to mindlessly vote for what their streamer told them to, where as if you show Twitch that there are legitimate use cases for a feature and the value it would add to the platform that is much more likely to be looked at.
Improving the embed controls would certainly be a worthwhile improvement, but would still be a worse solution than the previously available mp4 urls, because it would reduce the theme-ability of clip player overlays, making them unsuitable for broadcasters who wish to keep their theme consistent across their overlays. My users consistently choose to integrate my clip player with their existing themes, using decorative borders, alternate fonts, crt effects, etc. In order for that functionality to return, I’ll be supporting this uservoice request as well. https://twitch.uservoice.com/forums/310213-developers/suggestions/49331324-extend-clips-api-to-provide-the-mp4-url-for-overla
As this is a beta who knows, maybe if there’s enough support it’d be considered during this beta period, but just remember your use case was never officially supported so if your previous tools broke there should be no expectation for Twitch to ‘fix’ what they never intended for you to be doing in the first place.
As for specifically your point about wanting to use themes and such, I’m not sure how that factors in to needing to download the actual file vs supporting the UserVoice for interactive iframes, as then you’ll have the control of interactive iframes, Twitch gets to keep the actual downloads scoped to broadcasters/editors, and you can still do all the themes you like as people have done with existing embeds for bringing in live streams (just keep in mind not to do anything that overlays the embed within the same browser source as the embed, do it separately and it has no impact at all on blocking autoplay).
Which is disallowed, which would suggest another reason why Twitch would disallow/not support the use case you have described, (using MP4 URL’s to play a clip)
1.3 Embeds must utilize only Twitch-approved player elements and should not be obscured in any way by other page elements in whatever domain context they may appear. Certain features, such as the ability to send chat messages, may be disabled if the iframe is obscured or not visible.
As Barry says, the clip embed has usage restrictions that limit themes, but there’s no reason that would apply to anything that is not the twitch embedded clip player.
Dan Clancy (Twitch CEO) said on an official live stream about this issue, “we’re taking a look to see if there’s a way we can make it easier for you to do this like you’ve been doing previously”, so the expectation was set by Twitch. If they changed their mind since then, I would expect clarification on that, as I said in my first post.
Regardless, my requests for clarification could only be answered by Twitch staff, so while I appreciate your expertise, I will still be waiting for their response.
And that exploration/looking can result in “well we can’t do this” becuase Clancy won’t have talked to the relevant teams or legal, since live on a live stream, so he’ll just say “ok we’ll look into this” when you put him on the spot on a live stream (or even in person for that matter). And forward it to the relevant team(s).
And you won’t get an answer (from clancy) becuase “Clancy on a stream” isn’t a uservoice where comments can be added by staff to a request.
Can we pull back on the speculative comments? Clancy had previously talked to the team about the issue, in the clip I’m referencing he said they were aware of the issue and they didn’t know why clip players were broken, and that it wasn’t their intention to break them.
The answer doesn’t have to come from clancy, I have posted the question here and in uservoice to seek answers from twitch staff as a whole.
I mean you won’t get a yay/nay answer from clancy on a stream becuase clancy doesn’t have a yay/nay answer and will return a middle of the road/we’ll pass it on.
Yes you’ll get a uservoice answer, but it seemed you were expecting an answer from Clancy themself by citing “I asked clancy on a official live stream” and if I misunderstood that I apologize. Just the general gist of things is “I got a postiivish answer from the CEO so it’s definately happening” when looking at reddit/other social media.
Keep in mind the embed guidelines relate to embeds on a page being obscured by “other page elements in whatever domain context they may appear”. So as I had previously mentioned, if this is for use on a stream, you could render an embed on a page entirely on it’s own, and not have any other element on that page obscure it, and then separately layer other graphical elements that aren’t part of that page on top.
Examples of this are streamers who display embeds of other users livestreams, and have their own facecam still overlayed and covering that embed. There are live tournaments that take in streams from other channels (WoW race to worlds first for example), that include embeds of live streams and separate overlay content, etc…
There’s been a misunderstanding, I didn’t personally ask him. I saw the clip after the fact, I only bring it up to point out that there was an investigation into my specific issue that I have yet to hear an official resolution to.
Thank you for the discussion and I’m glad to provide further context for questions in the comments, and make sure relevant teams are also aware.
This new endpoint enables several use cases that would require access to Clip MP4 files. However, we are aware that it does not provide a one-to-one replacement for all shoutout use cases as direct access to files was previously possible and heavily relied on. We love shoutouts, but streamers should have control over who can download their content which is why scopes are necessary for this endpoint. Programmatic downloads of content is seen differently from the ability to watch clips or even manually download clips one at a time from the clip player.
@sugoidogo, I am somewhat familiar with Clippy and appreciate that you have implemented a consent command and timeout to make sure streamers are ok with their clips being used, so I hope you can understand that our design aims to implement the same level of consent more broadly with OAuth. This means the consent message, as one potential alternative, would need to advise the streamer in chat to go through an OAuth link rather than use a chat command if they haven’t previously interacted with Clippy.
So to confirm, the Get Clips Download API endpoint is the solution we are providing to access clip video files. There are no plans to add file URLs to the Get Clips endpoint that would allow unauthorized access to clip files.
@badoge, a great callout about potential embed improvements. We’ll take this idea to the right team to consider assuming this would be helpful for your use case.
