Skip to main content

Creating renditions from source files

Shotstack provides for a range of transformations that allow you to create transcode your media. A rendition is a new file created from the source file with transformations applied.

We allow for the following transformations:

  • Resizing
  • Changing the aspect ratio
  • Cropping
  • Changing the framerate
  • Change the quality

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, creating a scaled down version of the original (1920px x 1080px).

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 transformation 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.

Other transformations​

As well as creating renditions with different resolutions, you can also apply other transformations to 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://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
    "outputs": {
        "renditions": [
            {
                "size": {
                    "width": 720,
                    "height": 720
                },
                "fps": 30,
                "quality": 50
            }
        ]
    }
}'

The example above will ingest the source video and create a custom resolution, a square video rendition; 720px x 720px. The video aspect ratio will be retained and the portion of the video outside the square area will be cropped.

Also the frame rate will be converted to 30 frames per second. The quality is set to 50 which will create a smaller file size with a small loss in visual quality.

The API reference documentation lists all available rendition transformations.

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.