Create Clips

Learn to create clips using the Twitch API.

We'll cover the following

Create clips from ongoing streams

We can retrieve information regarding clips, but we can also use the Twitch API to programmatically create a clip from a currently ongoing live stream. To do so, we can send a simple POST request to the clips endpoint and pass the ID of a currently streaming channel.

All POST requests to create a clip must be authenticated with a user access token that has the clips:edit scope.

Request parameters

It requires a single query parameter and another optional query parameter. The table below gives an overview of both parameters:

Parameter

Type

Category

Description

broadcaster_id

String

Required

This is the ID of the live channel whose ongoing live stream we want to clip.

has_delay

Boolean

Optional

This indicates whether to wait for a short period before capturing the clip. If it is false, the clip is captured immediately from the live stream. The purpose of this parameter is to account for any time delays between the broadcaster's and the viewer's sides. Its default value is false.

The ID that we pass in the broadcaster_id parameter must be a valid ID, and the corresponding user must be live when we make the request. If the broadcaster is not live, the clip creation will fail.

Let's make a sample call to this endpoint. First, let's query the streams endpoint to retrieve a list of ongoing streams. Next, we'll call the clips endpoint with the ID of a user that is currently live.

Note: The code below extracts a clip ID to be used later, so don't forget to save it. If your access token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/clips");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
const options = {
  method: "POST",
  headers: headerParameters,
};
async function createClip() {
  try {
    const streamsResponse = await getActiveStreams(); // Fetch the list of active streams
    if (!streamsResponse) {
      console.log("Something went wrong while fetching active streams...");
      return;
    }
    const streamsContent = await streamsResponse.json();
    // Using a broadcaster ID from the streams response
    const queryParameters = new URLSearchParams({
      broadcaster_id: streamsContent["data"][0]["user_id"],
    });
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
createClip();

In the code above, we perform the following:

  • Lines 10–13: We set the options for the API call, specifying the HTTP request type as POST and providing the request headers.

  • Lines 15–37: We define a function called createClip to make a call to the clips endpoint.

    • Lines 16–34: Within a try block, we first call the streams endpoint on line 17 to fetch the list of ongoing streams. We then extract the ID of a currently streaming broadcaster, pass it as the broadcaster_id query parameter, and make a call to the clips endpoint.

    • Lines 34–36: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 39: We invoke the createClip function.

Let's make a GET request to the clips endpoint to retrieve the details of the clip we just created:

Note: Clip creation may take some time, so if you don't get the expected response from the following request, try running the code again after a few minutes. If your access token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/clips");
const headerParameters = {
  Authorization: "Bearer {{APP_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing the ID of the clip we created
const queryParameters = new URLSearchParams({
  id: "{{CLIP_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getClipDetails() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getClipDetails();

Response fields

The JSON response from a POST request to the clips endpoint when creating a clip has a single top-level property—data. This property contains an array of objects, with each object representing a clip that was just created. The table below discusses the properties of these objects:

Property

Type

Description

id

String

This is the ID of the clip.

edit_url

String

This is the URL where the created clip can be edited.