Creating renditions from source files

You can use the Ingest API to transfer or upload a source file to Shotstack, ready for using in your edits. You can also create renditions from the source file. A rendition is a new file created from the source file with transformations applied.

Transformations include resizing the video or image, changing the aspect ratio, cropping, changing the framerate and quality. This is useful for providing different versions of the same asset for different devices, applications or use cases.

The examples below show how to ingest a source file and create renditions as soon as the source is ready.

Create a single rendition from a source file

When you transfer or upload a source file you can specify a list of renditions to create:

curl -X POST https://api.shotstack.io/ingest/stage/sources \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf' \
     -d '
{
    "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
    "outputs": {
        "renditions": [
            {
                "resolution": "hd"
            }
        ]
    }
}'

The example above requests the url https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4 be ingested to the stage environment.

Once it is transferred and saved to Shotstack, an HD rendition (1280px x 720px) will be generated. The original source file is FHD (1920px x 1080px) so the HD rendition is a scaled down version.

You receive the same response as when ingesting a source file without renditions:

{
    "data": {
        "type": "source",
        "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2"
    }
}

Create multiple renditions from a source file

You can create multiple renditions from a source file by adding more renditions to the list of renditions:

curl -X POST https://api.shotstack.io/ingest/stage/sources \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf' \
     -d '
{
    "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
    "outputs": {
        "renditions": [
            {
                "resolution": "hd"
            },
            {
                "resolution": "mobile"
            }
        ]
    }
}'

The example above will ingest the source video and create two renditions, one HD (1280px x 720px) and one mobile (640px x 360px) videos. Each video can be used for different use cases within an application.

Create image renditions

Ingesting an image and creating renditions is the same as ingesting a video.

curl -X POST https://api.shotstack.io/ingest/stage/sources \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf' \
     -d '
{
    "url": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/images/wave-barrel.jpg",
    "outputs": {
        "renditions": [
            {
                "size": {
                    "width": 400,
                    "height": 400
                },
                "quality": 70
            }
        ]
    }
}'

The example above will ingest the source jpg image (1920px x 1080px) and create a rendition with a custom size of 400px x 400px. The image will first be scaled and then cropped to a square shape. Finally the quality will be reduced to 70, creating a smaller file size with a small loss in visual quality.

Custom file names

You can create renditions with custom file names by adding a filename property to the rendition. This allows you to identify a rendition by its file name rather than its ID. Not that the filename extension must be omitted and will be added automatically based on the rendition format.

The rendition settings below will create a rendition with a file name of 720p.mp4:

{
  "format": "mp4",
  "size": {
    "width": 1280,
    "height": 720
  },
  "filename": "720p"
}

Create renditions from a direct upload

Creating renditions from a direct upload is the same as creating renditions from a URL. When you make a request for the signed URL you provide a list of renditions to create:

curl -X POST https://api.shotstack.io/ingest/stage/upload \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'
     -d '
{
    "outputs": {
        "renditions": [
            {
                "resolution": "hd"
            }
        ]
    }
}'

When the file is uploaded to the signed URL, a rendition will be created with an HD resolution (1280px x 720px).

Get a rendition files details

Fetching the details of a rendition uses the same endpoint used to check the status of a source file. Call the sources endpoint with it's ID and the response will include the status of any renditions requested:

curl -X GET https://api.shotstack.io/ingest/stage/sources/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2 \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'

The response will look similar to:

{
    "data": {
        "type": "source",
        "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
        "attributes": {
            "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
            "owner": "5ca6hu7s9k",
            "input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
            "source": "https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
            "status": "ready",
            "outputs": {
                "renditions": [
                    {
                        "id": "zzyap2eg-3ae4-8p0o-xxja-5o71wq1vjat3",
                        "status": "ready",
                        "url": "https://shotstack-ingest-api-v1-renditions.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyap2eg-3ae4-8p0o-xxja-5o71wq1vjat3.mp4",
                        "executionTime": 9554.78,
                        "transformation": {
                            "format": "mp4",
                            "fps": 30,
                            "size": {
                                "width": 1280,
                                "height": 720
                            }
                        },
                        "width": 1280,
                        "duration": 25.87,
                        "fps": 30,
                        "height": 720
                    }
                ]
            },
            "width": 1920,
            "height": 1080,
            "duration": 25.86,
            "fps": 23.967,
            "created": "2023-01-02T01:47:18.973Z",
            "updated": "2023-01-02T01:47:37.260Z"
        }
    }
}

The response includes details of the rendition in the data.attributes.outputs.renditions array. The URL in the array is the rendition file saved with Shotstack that you can use when editing videos. If the file is still being transferred or uploaded the status will show as queued or importing. If there is an error the status will be failed. If the source file is still being ingested the status will be waiting.

Creating renditions from source files

Create a single rendition from a source file​

Create multiple renditions from a source file​

Other video transformations​

Create image renditions​

Custom file names​

Create renditions from a direct upload​

Get a rendition files details​