Resize and crop videos using the Edit and Ingest API

With the rise of smartphones and social media platforms there is no longer a standard size for videos. We went from a 4:3 aspect ratio used for television broadcasts and camcorders to the modern widescreen TV, 16:9 aspect ratio we are now familiar with.

With the advent of smartphones, the vertical 9:16 aspect ratio dominated, and then social media networks created their own standards with square 1:1 and 4:5 aspect ratios.

We now live in a world where we might record footage using a digital camera at 16:9, or a mobile phone at 9:16 and then want to repurpose our footage to multiple aspect ratios for multiple channels.

In this article we'll show you how to resize and crop videos using the Shotstack Edit API and Ingest API. Shotstack provides cloud based video editing and processing tools used by developers to automate video centric applications and workflows.

To follow along with this tutorial you will need to sign up to the Shotstack platform and get an API key. The developer sandbox give you free access to all of the Shotstack API's so you can test and experiment for free. Make sure you use the stage API key in the examples and commands below.

Shotstack's API's to crop and resize video

Shotstack offers two API's to crop or resize videos depending on the final output or use case your are aiming for. If you want to perform editing tasks such as adding text, images, transitions, etc..., then you should use the Edit API. If you want to simply resize or crop your video, then you would use the Ingest API.

Using the Edit API to resize and crop videos

With the Edit API you describe a video using JSON. One of the parameters is output which provides a couple of ways to resize and adjust the output videos size and aspect ratio. You can use built in resolutions (i.e. sd, hd, 1080) and aspect ratios (i.e. 16:9, 9:16, 1:1) or you can set a custom width and height to create your own resolutions and aspect ratios.

For this guide we will use cURL to post the JSON to the API, but you can also use other API tools such as Postman or the Shotstack video editor. Eventually you might build an application using one of our video editing SDK's.

Built in resolutions and aspect ratios

To demonstrate resizing and cropping a video using the built in resolutions and aspect ratios we will use a 1080p, 9:16 (vertical) source video and resize and crop it to a 720p 1:1 (square) video.

Here is what the source video looks like:

Create a file named crop.json and then paste the following:

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/car-overead-vertical.mp4"
                        },
                        "start": 0,
                        "length": 9.675
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "resolution": "hd",
        "aspectRatio": "1:1",
        "fps": 30
    }
}

In the above example, we have the URL of a vertical 9:16 mp4 video file with a duration (length) of 9.675 seconds. The output format is set to mp4, the resolution to hd, the aspect ratio to 1:1 and the frames per second to 30. This will generate a video that is square, 720 pixels wide and 720 pixels high. The video will be cropped to fit the square aspect ratio and the top and bottom of the video will be removed.

Post the JSON to the Edit API

Use your terminal/command line to send the crop.json data to the render API endpoint using cURL and replace YOUR_API_KEY with your API key:

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

If successful the response will include the id of the render task:

{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Render Successfully Queued",
        "id": "ad4782ab-ddb4-4830-b408-12f22e4e1441"
    }
}

Check the render status

The video will take a few seconds to render and you can check it's progress using the id and the following cURL command. As before, use your API key and replace RENDER_ID with the id returned in 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 a response.status value indicating the render status. When the status parameter is done a temporary url parameter is also returned which can be used to view or download the final video:

{
    "success": true,
    "message": "OK",
    "response": {
        "id": "ad4782ab-ddb4-4830-b408-12f22e4e1441",
        "owner": "7okmvmdcv8",
        "plan": "sandbox",
        "status": "done",
        "error": "",
        "duration": 9.675,
        "billable": 9.657,
        "renderTime": 3.88,
        "url": "https://shotstack-api-stage-output.s3-ap-southeast-2.amazonaws.com/7okmvmdcv8/ad4782ab-ddb4-4830-b408-12f22e4e1441.mp4",
        "poster": null,
        "thumbnail": null,
        "created": "2023-05-29T16:49:38.486Z",
        "updated": "2023-05-29T16:49:46.559Z"
    }
}

The output video will look like below, a square 720p video cropped from the original 1080p vertical video:

Custom resolutions and aspect ratios

You can also set a custom width and height to create your own resolutions and aspect ratios. For example, a less common aspect ratio that Shotstack does not support out of the box is CinemaScope anamorphic 2.35:1. To create a 1080p video at this aspect ratio you would set the width to 1920 pixels and the height to 817 pixels.

For this example we'll use the following 16:9 source video:

Replace the contents of the crop.json file with the JSON below, then follow the previous API render and status checks we used previously to render the video.

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "video",
                            "src": "https://shotstack-assets.s3.ap-southeast-2.amazonaws.com/footage/drone-over-fields.mp4"
                        },
                        "start": 0,
                        "length": 10
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "size": {
            "width": 1920,
            "height": 817
        },
        "fps": 23.976
    }
}

In this render we used the parameter size instead of resolution and aspectRatio and set the width and height to 1920 x 817. The source video is also 10 seconds long with a 23.976 frame rate.

The rendered video is now resized to 1920 x 817 pixels and the top and bottom of the video is cropped to fit the 2.35:1 aspect ratio:

Using the Ingest API to resize and crop videos

The Edit API is the best choice when you want to edit a video, merge multiple clips and add text, images, transitions, etc... If you simply want to transform a video without adding any other features then the Ingest API is the best choice.

The Ingest API is used to upload a video to the Shotstack platform and perform simple transformations such as resizing, cropping, changing the format, etc... The video is then available to use in the Edit API, download or hosting.

Using the Ingest API is very similar to the Edit API except the API URL and endpoint are different and the JSON is much simpler.

In the example below we will download (ingest) a video directly from Pexels, save the source file and create a rendition that is resized and cropped from 1080p horizontal; 1920px x 1080px to 720p vertical; 720px x 1280px.

Here is the file we will ingest from Pexels:

Again, lets replace the contents of the crop.json file with the JSON below:

{
    "url": "https://player.vimeo.com/external/350245163.hd.mp4?s=c83aaccde18f7a5df9c9960dd0aea41d321f920e&profile_id=175&oauth2_token_id=57447761",
    "outputs": {
        "renditions": [
            {
                "format": "mp4",
                "size":{
                    "width": 720,
                    "height": 1280
                }
            }
        ]
    }
}

In the above JSON, we include the URL of the video to ingest, and an output rendition. The rendition is a copy of the source file with certain transformations applied. In this case we are setting the width to 720 pixels and the height to 1280 pixels. The format is set to mp4 which is the same as the source.

Post the JSON to the Ingest API

Instead of sending our request to the base URL https://api.shotstack.io/edit, we will POST to the https://api.shotstack.io/ingest URL and the sources endpoint.

Run the cURL command below from your terminal:

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

A successful response will look similar to the following and include the id of the source, the file that is being ingested:

{
  "data": {
    "type": "source",
    "id": "zzy7qapx-6xge-wv0v-tpyc-0kwfqd8nuc4i"
  }
}

Check the ingest and rendition status

The video will take a few seconds to ingest and process and you can check it's progress using the id and the following cURL command. As before, use your API key and replace SOURCE_ID with the id returned in the previous step:

curl -X GET https://api.shotstack.io/ingest/stage/sources/SOURCE_ID \
  -H 'Accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

The response will include a status value at data.attributes.status. When this value is ready, it means that the source file has been copied from Pexels and saved to Shotstack at the url provided.

There is also the rendition status at data.attributes.outputs.renditions.status. This is a copy of the source file with transformations applied, in this case, it is resized and cropped to 720px wide by 1280px high. When the rendition status is ready then the resized video can be viewed and downloaded at the URL provided:

{
    "data": {
        "type": "source",
        "id": "zzy7qapx-6xge-wv0v-tpyc-0kwfqd8nuc4i",
        "attributes": {
            "id": "zzy7qapx-6xge-wv0v-tpyc-0kwfqd8nuc4i",
            "owner": "7okmvmdcv8",
            "input": "https://player.vimeo.com/external/350245163.hd.mp4?s=c83aaccde18f7a5df9c9960dd0aea41d321f920e&profile_id=175&oauth2_token_id=57447761",
            "source": "https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/7okmvmdcv8/zzy7qapx-6xge-wv0v-tpyc-0kwfqd8nuc4i/source.mp4",
            "status": "ready",
            "outputs": {
                "renditions": [
                    {
                        "id": "zzy9qapw-8ibr-tk29-nj6p-5ge64b07edoe",
                        "status": "ready",
                        "url": "https://shotstack-ingest-api-stage-renditions.s3.ap-southeast-2.amazonaws.com/7okmvmdcv8/zzy7qapx-6xge-wv0v-tpyc-0kwfqd8nuc4i/zzy9qapw-8ibr-tk29-nj6p-5ge64b07edoe.mp4",
                        "executionTime": 14512.84,
                        "transformation": {
                            "format": "mp4",
                            "size": {
                                "width": 720,
                                "height": 1280
                            }
                        },
                        "width": 720,
                        "duration": 39.58,
                        "fps": 24,
                        "height": 1280
                    }
                ]
            },
            "width": 1920,
            "height": 1080,
            "duration": 39.58,
            "fps": 24,
            "created": "2023-06-14T11:59:38.590Z",
            "updated": "2023-06-14T11:59:48.934Z"
        }
    }
}

The final video will look like below:

And there you go! You have successfully ingested a video from one URL and resized it to the new resolution. Any parts of the video that fall outside the aspect ratio will be cropped and removed.

There are other options to explore that modify how the video is cropped. For example, you can set the fit parameter to contain to ensure the entire video is visible and the aspect ratio is maintained. You can also set the position parameter to top, bottom, left or right to control where the video is cropped from.

To learn more about the available options check out the API reference for the Edit API and Ingest API and see what you can come up with.