Extract frames from a video with the Edit API

What do you do when you want to get an image from a video? You may want to create a thumbnail for your video or a poster image. Or get a still image from the video to include in a blog post.

You can pause the video and take a screenshot. But that wouldn't be an ideal solution. The quality of the screenshot may not be up to what you want. It will also be difficult if you want to extract more frames from the video or automate the process.

In this article, you will learn how to extract frames from a video using an API. You will get greater control over the frames you can extract and can automate the process. We'll first look at the steps to extract the first frame of a video. And then how to extract a frame from a specific timestamp.

About Shotstack and the Edit API

Shotstack is a cloud-based video automation platform for developers. Using Shotstack API's, you can create, edit and render dynamic videos at scale. In this tutorial, we will use the Edit API to extract frames from a video.

The following is a short five-second BMX video we will use for the examples in this tutorial available at the following URL: https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/bmx.mp4****Bold.

Requirements

To follow this tutorial you will need the following:

• A Shotstack API Key, which you get when you sign up for a free developer account.
• A basic understanding of using a command line terminal and running cURL requests.

Extracting the first frame with the Edit API

The JSON below will extract the first frame of the video. Copy this JSON and save it to a file named frame.json.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/bmx.mp4",
                            "trim": 0
                        },
                        "start": 0,
                        "length": 1
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "jpg",
        "resolution": "hd"
    }
}

We're using trim to show where we want to extract the frame. Since the value is 0, we will get the frame at the beginning of the video. The video URL is included in the JSON as a video clip by setting the asset.src parameter. By specifying the output.format as jpg, the API knows to create an image.

Using the frame.json file, make a POST request to the Edit API. Run the following command, replacing YOUR_API_KEY with your Shotstack API key.

curl -X POST \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d @frame.json \
    https://api.shotstack.io/edit/stage/render

You should get a response like the one below if the request is successful.

{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Render Successfully Queued",
        "id": "d3e1d76d-14f0-4353-8f7e-07286ea09e04"
    }
}

Copy the id from the response. We'll use it in the next step to check the render status.

Check the status of the extracted frame

The API will fetch and store your video file before extracting the frame and rendering an image. Give it a few seconds for the whole process to complete. Then, run the command below replacing YOUR_API_KEY. Also, replace RENDER_ID with the id you copied from the previous step.

curl -X GET \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    https://api.shotstack.io/edit/stage/render/RENDER_ID

The response will include relevant details about the frame including the URL and rendering status. If status is "done", you will see a response.url value like the following:

https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/t2siieowih/d3e1d76d-14f0-4353-8f7e-07286ea09e04.jpg

You can view the image in your browser or download it. It should look like this:

Extract frames at a specific timestamp

In this section, we will extract a frame at a given timestamp. Copy and paste the JSON below.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/bmx.mp4",
                            "trim": 1.4
                        },
                        "start": 0,
                        "length": 1
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "jpg",
        "resolution": "hd"
    }
}

Giving trim a value of 1.4 means we want to extract the frame at 1.4 seconds into the video.

Use the same commands from the previous section to do the following:

• Make a POST request to the Edit API with the updated JSON.
• Check the response to get the render ID.
• Make a GET request to get details of the extracted frame.

You should see a URL for the frame in the response to the GET request. This time the image should look like this:

Exporting frames in different formats

The output property allows you to export frames with different settings. You can export frames in different formats, resolutions, and aspect ratios.

Let's see an example by creating a vertical PNG frame using the JSON below. The aspectRatio is what makes the frame vertical. Note also the resolution which is set to mobile, which generates a file 640px x 360px in size.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/bmx.mp4",
                            "trim": 1.4
                        },
                        "start": 0,
                        "length": 1
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "png",
        "resolution": "mobile",
        "aspectRatio": "9:16"
    }
}

Let's see another example by creating a square frame using the JSON below.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/bmx.mp4",
                            "trim": 1.4
                        },
                        "start": 0,
                        "length": 1
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "png",
        "resolution": "sd",
        "aspectRatio": "1:1"
    }
}

What makes this image a square is the aspectRatio of 1:1. Like the previous example, this is also a PNG image. And it has resolution set to sd (1024px x 576px).

Conclusion

You now know what to do whenever you need to extract images from a video. In this guide, we've walked you through the process using the Shotstack Edit API. Check out our developer guides to learn more about what you can do with Shotstack.