Render Asset

v1.0.0

Queue and render the contents of a timeline as a video, image or audio file.

Input

{
  "type": "object",
  "description": "An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format.",
  "required": [
    "output",
    "timeline"
  ],
  "properties": {
    "callback": {
      "type": "string",
      "description": "An optional webhook callback URL used to receive status notifications when a render completes or fails. See [webhooks](https://shotstack.gitbook.io/docs/guides/architecting-an-application/webhooks) for  more details."
    },
    "disk": {
      "type": "string",
      "description": "The disk type to use for storing footage and assets for each render. See [disk types](https://shotstack.gitbook.io/docs/guides/architecting-an-application/disk-types) for more details. <ul>\n  <li>`local` - optimized for high speed rendering with up to 512MB storage</li>\n  <li>`mount` - optimized for larger file sizes and longer videos with 5GB for source footage and 512MB for output render</li>\n</ul>",
      "enum": [
        "local",
        "mount"
      ]
    },
    "output": {
      "type": "object",
      "description": "The output format, render range and type of media to generate.",
      "required": [
        "format"
      ],
      "properties": {
        "aspectRatio": {
          "type": "string",
          "description": "The aspect ratio (shape) of the video or image. Useful for social media output formats. Options are: <ul>\n  <li>`16:9` - regular landscape/horizontal aspect ratio (default)</li>\n  <li>`9:16` - vertical/portrait aspect ratio</li>\n  <li>`1:1` - square aspect ratio</li>\n  <li>`4:5` - short vertical/portrait aspect ratio</li>\n  <li>`4:3` - legacy TV aspect ratio</li>\n</ul>",
          "enum": [
            "16:9",
            "9:16",
            "1:1",
            "4:5",
            "4:3"
          ]
        },
        "destinations": {
          "type": "array",
          "description": "A destination is a location where output files can be sent to for serving or hosting. By default all rendered assets are automatically sent to the Shotstack hosting destination. [DestinationShotstack](/#tocs_shotstackdestination) is currently the only option with plans to add more in the future such as S3, YouTube, Vimeo and Mux. If you do not require hosting you can opt-out using the  `exclude` property.",
          "items": {
            "type": "object"
          }
        },
        "format": {
          "type": "string",
          "description": "The output format and type of media file to generate. <ul>\n  <li>`mp4` - mp4 video file</li>\n  <li>`gif` - animated gif</li>\n  <li>`jpg` - jpg image file</li>\n  <li>`png` - png image file</li>\n  <li>`bmp` - bmp image file</li>\n  <li>`mp3` - mp3 audio file (audio only)</li>\n</ul>",
          "enum": [
            "mp4",
            "gif",
            "mp3",
            "jpg",
            "png",
            "bmp"
          ]
        },
        "fps": {
          "type": "integer",
          "description": "Override the default frames per second. Useful for when the source footage is recorded at 30fps, i.e. on  mobile devices. Lower frame rates can be used to add cinematic quality (24fps) or to create smaller file size/faster render times or animated gifs (12 or 15fps). Default is 25fps. <ul>\n  <li>`12` - 12fps</li>\n  <li>`15` - 15fps</li>\n  <li>`24` - 24fps</li>\n  <li>`25` - 25fps</li>\n  <li>`30` - 30fps</li>\n</ul>",
          "enum": [
            12,
            15,
            24,
            25,
            30
          ]
        },
        "poster": {
          "type": "object",
          "description": "Generate a poster image from a specific point on the timeline.",
          "required": [
            "capture"
          ],
          "properties": {
            "capture": {
              "type": "number",
              "description": "The point on the timeline in seconds to capture a single frame to use as the poster image."
            }
          }
        },
        "quality": {
          "type": "string",
          "description": "Adjust the output quality of the video, image or audio. Adjusting quality affects  render speed, download speeds and storage requirements due to file size. The default `medium` provides the most optimized choice for all three  factors. <ul>\n  <li>`low` - slightly reduced quality, smaller file size</li>\n  <li>`medium` - optimized quality, render speeds and file size</li>\n  <li>`high` - slightly increased quality, larger file size</li>\n</ul>",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        "range": {
          "type": "object",
          "description": "Specify a time range to render, i.e. to render only a portion of a video or audio file. Omit this setting to  export the entire video. Range can also be used to render a frame at a specific time point - setting a range and output format as `jpg` will output a single frame image at the range `start` point.",
          "properties": {
            "length": {
              "type": "number",
              "format": "float",
              "description": "The length of the portion of the video or audio to render - i.e. render 6 seconds of the video."
            },
            "start": {
              "type": "number",
              "format": "float",
              "description": "The point on the timeline, in seconds, to start the render from - i.e. start at second 3."
            }
          }
        },
        "resolution": {
          "type": "string",
          "description": "The output resolution of the video or image. <ul>\n  <li>`preview` - 512px x 288px @ 15fps</li>\n  <li>`mobile` - 640px x 360px @ 25fps</li>\n  <li>`sd` - 1024px x 576px @ 25fps</li>\n  <li>`hd` - 1280px x 720px @ 25fps</li>\n  <li>`1080` - 1920px x 1080px @ 25fps</li>\n</ul>",
          "enum": [
            "preview",
            "mobile",
            "sd",
            "hd",
            "1080"
          ]
        },
        "scaleTo": {
          "type": "string",
          "description": "Override the resolution and scale the video or image to render at a different size. When using scaleTo the asset should be edited at the resolution dimensions, i.e. use font sizes that look best at HD, then use scaleTo to output the file at SD and the text will be scaled to the correct size. This is useful if you want to create multiple asset sizes. <ul>\n  <li>`preview` - 512px x 288px @ 15fps</li>\n  <li>`mobile` - 640px x 360px @ 25fps</li>\n  <li>`sd` - 1024px x 576px @25fps</li>\n  <li>`hd` - 1280px x 720px @25fps</li>\n  <li>`1080` - 1920px x 1080px @25fps</li>\n</ul>",
          "enum": [
            "preview",
            "mobile",
            "sd",
            "hd",
            "1080"
          ]
        },
        "size": {
          "type": "object",
          "description": "Set a custom size for a video or image. When using a custom size omit the `resolution` and `aspectRatio`. Custom sizes must be divisible by 2 based on the encoder specifications.",
          "properties": {
            "height": {
              "type": "integer",
              "description": "Set a custom height for the video or image file. Value must be divisible by 2. Maximum video height is 1920px, maximum image height is 4096px."
            },
            "width": {
              "type": "integer",
              "description": "Set a custom width for the video or image file. Value must be divisible by 2. Maximum video width is 1920px, maximum image width is 4096px."
            }
          }
        },
        "thumbnail": {
          "type": "object",
          "description": "Generate a thumbnail image from a specific point on the timeline.",
          "required": [
            "capture",
            "scale"
          ],
          "properties": {
            "capture": {
              "type": "number",
              "description": "The point on the timeline in seconds to capture a single frame to use as the thumbnail image."
            },
            "scale": {
              "type": "number",
              "description": "Scale the thumbnail size to a fraction of the viewport size - i.e. setting the scale to 0.5 will scale  the thumbnail to half the size of the viewport."
            }
          }
        }
      }
    },
    "timeline": {
      "type": "object",
      "description": "A timeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time.",
      "required": [
        "tracks"
      ],
      "properties": {
        "background": {
          "type": "string",
          "description": "A hexadecimal value for the timeline background colour. Defaults to #000000 (black)."
        },
        "cache": {
          "type": "boolean",
          "description": "Disable the caching of ingested source footage and assets. See  [caching](https://shotstack.gitbook.io/docs/guides/architecting-an-application/caching) for more details."
        },
        "fonts": {
          "type": "array",
          "description": "An array of custom fonts to be downloaded for use by the HTML assets.",
          "items": {
            "type": "object",
            "description": "Download a custom font to use with the HTML asset type, using the font name in the CSS or font tag. See our [custom fonts](https://shotstack.io/learn/html-custom-fonts/) getting started guide for more details.",
            "required": [
              "src"
            ],
            "properties": {
              "src": {
                "type": "string",
                "description": "The URL of the font file. The URL must be publicly accessible or include credentials."
              }
            }
          }
        },
        "soundtrack": {
          "type": "object",
          "description": "A music or audio soundtrack file in mp3 format.",
          "required": [
            "src"
          ],
          "properties": {
            "effect": {
              "type": "string",
              "description": "The effect to apply to the audio file <ul>\n  <li>`fadeIn` - fade volume in only</li>\n  <li>`fadeOut` - fade volume out only</li>\n  <li>`fadeInFadeOut` - fade volume in and out</li>\n</ul>",
              "enum": [
                "fadeIn",
                "fadeOut",
                "fadeInFadeOut"
              ]
            },
            "src": {
              "type": "string",
              "description": "The URL of the mp3 audio file. The URL must be publicly accessible or include credentials."
            },
            "volume": {
              "type": "number",
              "description": "Set the volume for the soundtrack between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1)."
            }
          }
        },
        "tracks": {
          "type": "array",
          "description": "A timeline consists of an array of tracks, each track containing clips. Tracks are layered on top of each other in the same order they are added to the array with the top most track layered over the top of those below it. Ensure that a track containing titles is the top most track so that it is displayed above videos and images.",
          "items": {
            "type": "object",
            "description": "A track contains an array of clips. Tracks are layered on top of each other in the order in the array. The top most track will render on top of those below it.",
            "required": [
              "clips"
            ],
            "properties": {
              "clips": {
                "type": "array",
                "description": "An array of Clips comprising of TitleClip, ImageClip or VideoClip.",
                "items": {
                  "type": "object",
                  "description": "A clip is a container for a specific type of asset, i.e. a title, image, video, audio or html. You use a Clip to define when an asset will display on the timeline, how long it will play for and transitions, filters and effects to apply to it.",
                  "required": [
                    "asset",
                    "start",
                    "length"
                  ],
                  "properties": {
                    "asset": {
                      "description": "The type of asset to display for the duration of this Clip. Value must be one of <b>TitleAsset</b>, <b>ImageAsset</b>, <b>VideoAsset</b>, <b>HtmlAsset</b>, <b>AudioAsset</b> or <b>LumaAsset</b>",
                      "type": "object"
                    },
                    "effect": {
                      "type": "string",
                      "description": "A motion effect to apply to the Clip. <ul>\n  <li>`zoomIn` - slow zoom in</li>\n  <li>`zoomOut` - slow zoom out</li>\n  <li>`slideLeft` - slow slide (pan) left</li>\n  <li>`slideRight` - slow slide (pan) right</li>\n  <li>`slideUp` - slow slide (pan) up</li>\n  <li>`slideDown` - slow slide (pan) down</li>\n</ul>",
                      "enum": [
                        "zoomIn",
                        "zoomOut",
                        "slideLeft",
                        "slideRight",
                        "slideUp",
                        "slideDown"
                      ]
                    },
                    "filter": {
                      "type": "string",
                      "description": "A filter effect to apply to the Clip. <ul>\n  <li>`boost` - boost contrast and saturation</li>\n  <li>`contrast` - increase contrast</li>\n  <li>`darken` - darken the scene</li>\n  <li>`greyscale` - remove colour</li>\n  <li>`lighten` - lighten the scene</li>\n  <li>`muted` - reduce saturation and contrast</li>\n  <li>`invert` - invert colors</li>\n</ul>",
                      "enum": [
                        "boost",
                        "contrast",
                        "darken",
                        "greyscale",
                        "lighten",
                        "muted",
                        "negative"
                      ]
                    },
                    "fit": {
                      "type": "string",
                      "description": "Set how the asset should be scaled to fit the viewport using one of the following options: \n  <ul>\n    <li>`cover` - stretch the asset to fill the viewport without maintaining the aspect ratio.</li>\n    <li>`contain` - fit the entire asset within the viewport while maintaining the original aspect ratio.</li>\n    <li>`crop` - scale the asset to fill the viewport while maintaining the aspect ratio. The asset will be cropped if it exceeds the bounds of the viewport.</li>\n    <li>`none` - preserves the original asset dimensions and does not apply any scaling.</li>\n  </ul>",
                      "enum": [
                        "cover",
                        "contain",
                        "crop",
                        "none"
                      ]
                    },
                    "length": {
                      "type": "number",
                      "description": "The length, in seconds, the Clip should play for."
                    },
                    "offset": {
                      "type": "object",
                      "description": "Offset the location of the asset relative to its position on the viewport. The offset distance is relative to the width of the viewport - for example an x offset of 0.5 will move the asset half the viewport width to the right.",
                      "properties": {
                        "x": {
                          "type": "number",
                          "format": "float",
                          "description": "Offset an asset on the horizontal axis (left or right), range varies from -1 to 1. Positive numbers move the asset right, negative left. For all assets except titles the distance moved is relative to the width  of the viewport - i.e. an X offset of 0.5 will move the asset half the  screen width to the right."
                        },
                        "y": {
                          "type": "number",
                          "format": "float",
                          "description": "Offset an asset on the vertical axis (up or down), range varies from -1 to 1. Positive numbers move the asset up, negative down. For all assets except titles the distance moved is relative to the height  of the viewport - i.e. an Y offset of 0.5 will move the asset up half the  screen height."
                        }
                      }
                    },
                    "opacity": {
                      "type": "number",
                      "description": "Sets the opacity of the Clip where 1 is opaque and 0 is transparent."
                    },
                    "position": {
                      "type": "string",
                      "description": "Place the asset in one of nine predefined positions of the viewport. This is most effective for when the asset is scaled and you want to position the element to a specific position. <ul>\n  <li>`top` - top (center)</li>\n  <li>`topRight` - top right</li>\n  <li>`right` - right (center)</li>\n  <li>`bottomRight` - bottom right</li>\n  <li>`bottom` - bottom (center)</li>\n  <li>`bottomLeft` - bottom left</li>\n  <li>`left` - left (center)</li>\n  <li>`topLeft` - top left</li>\n  <li>`center` - center</li>\n</ul>",
                      "enum": [
                        "top",
                        "topRight",
                        "right",
                        "bottomRight",
                        "bottom",
                        "bottomLeft",
                        "left",
                        "topLeft",
                        "center"
                      ]
                    },
                    "scale": {
                      "type": "number",
                      "description": "Scale the asset to a fraction of the viewport size - i.e. setting the scale to 0.5 will scale asset to half the size of the viewport. This is useful for picture-in-picture video and  scaling images such as logos and watermarks."
                    },
                    "start": {
                      "type": "number",
                      "description": "The start position of the Clip on the timeline, in seconds."
                    },
                    "transition": {
                      "type": "object",
                      "description": "In and out transitions for a clip - i.e. fade in and fade out",
                      "properties": {
                        "in": {
                          "type": "string",
                          "description": "The transition in. Available transitions are:\n  <ul>\n    <li>`fade` - fade in</li>\n    <li>`reveal` - reveal from left to right</li>\n    <li>`wipeLeft` - fade across screen to the left</li>\n    <li>`wipeRight` - fade across screen to the right</li>\n    <li>`slideLeft` - move slightly left and fade in</li>\n    <li>`slideRight` - move slightly right and fade in</li>\n    <li>`slideUp` - move slightly up and fade in</li>\n    <li>`slideDown` - move slightly down and fade in</li>\n    <li>`carouselLeft` - slide in from right to left</li>\n    <li>`carouselRight` - slide in from left to right</li>\n    <li>`carouselUp` - slide in from bottom to top</li>\n    <li>`carouselDown` - slide in from top to bottom</li>\n    <li>`shuffleTopRight` - rotate in from top right</li>\n    <li>`shuffleRightTop` - rotate in from right top</li>\n    <li>`shuffleRightBottom` - rotate in from right bottom</li>\n    <li>`shuffleBottomRight` - rotate in from bottom right</li>\n    <li>`shuffleBottomLeft` - rotate in from bottom left</li>\n    <li>`shuffleLeftBottom` - rotate in from left bottom</li>\n    <li>`shuffleLeftTop` - rotate in from left top</li>\n    <li>`shuffleTopLeft` - rotate in from top left</li>\n    <li>`zoom` - fast zoom in</li>\n  </ul>\nThe transition speed can also be controlled by appending `Fast` or `Slow` to the transition, e.g. `fadeFast` or `CarouselLeftSlow`.",
                          "enum": [
                            "fade",
                            "fadeSlow",
                            "fadeFast",
                            "reveal",
                            "revealSlow",
                            "revealFast",
                            "wipeLeft",
                            "wipeLeftSlow",
                            "wipeLeftFast",
                            "wipeRight",
                            "wipeRightSlow",
                            "wipeRightFast",
                            "slideLeft",
                            "slideLeftSlow",
                            "slideLeftFast",
                            "slideRight",
                            "slideRightSlow",
                            "slideRightFast",
                            "slideUp",
                            "slideUpSlow",
                            "slideUpFast",
                            "slideDown",
                            "slideDownSlow",
                            "slideDownFast",
                            "carouselLeft",
                            "carouselLeftSlow",
                            "carouselLeftFast",
                            "carouselRight",
                            "carouselRightSlow",
                            "carouselRightFast",
                            "carouselUp",
                            "carouselUpSlow",
                            "carouselUpFast",
                            "carouselDown",
                            "carouselDownSlow",
                            "carouselDownFast",
                            "shuffleTopRight",
                            "shuffleTopRightSlow",
                            "shuffleTopRightFast",
                            "shuffleRightTop",
                            "shuffleRightTopSlow",
                            "shuffleRightTopFast",
                            "shuffleRightBottom",
                            "shuffleRightBottomSlow",
                            "shuffleRightBottomFast",
                            "shuffleBottomRight",
                            "shuffleBottomRightSlow",
                            "shuffleBottomRightFast",
                            "shuffleBottomLeft",
                            "shuffleBottomLeftSlow",
                            "shuffleBottomLeftFast",
                            "shuffleLeftBottom",
                            "shuffleLeftBottomSlow",
                            "shuffleLeftBottomFast",
                            "shuffleLeftTop",
                            "shuffleLeftTopSlow",
                            "shuffleLeftTopFast",
                            "shuffleTopLeft",
                            "shuffleTopLeftSlow",
                            "shuffleTopLeftFast",
                            "zoom"
                          ]
                        },
                        "out": {
                          "type": "string",
                          "description": "The transition out. Available transitions are:\n  <ul>\n    <li>`fade` - fade out</li>\n    <li>`reveal` - reveal from right to left</li>\n    <li>`wipeLeft` - fade across screen to the left</li>\n    <li>`wipeRight` - fade across screen to the right</li>\n    <li>`slideLeft` - move slightly left and fade out</li>\n    <li>`slideRight` - move slightly right and fade out</li>\n    <li>`slideUp` - move slightly up and fade out</li>\n    <li>`slideDown` - move slightly down and fade out</li>\n    <li>`carouselLeft` - slide out from right to left</li>\n    <li>`carouselRight` - slide out from left to right</li>\n    <li>`carouselUp` - slide out from bottom to top</li>\n    <li>`carouselDown` - slide out from top  to bottom</li>\n    <li>`shuffleTopRight` - rotate out from top right</li>\n    <li>`shuffleRightTop` - rotate out from right top</li>\n    <li>`shuffleRightBottom` - rotate out from right bottom</li>\n    <li>`shuffleBottomRight` - rotate out from bottom right</li>\n    <li>`shuffleBottomLeft` - rotate out from bottom left</li>\n    <li>`shuffleLeftBottom` - rotate out from left bottom</li>\n    <li>`shuffleLeftTop` - rotate out from left top</li>\n    <li>`shuffleTopLeft` - rotate out from top left</li>\n    <li>`zoom` - fast zoom out</li>\n  </ul>\nThe transition speed can also be controlled by appending `Fast` or `Slow` to the transition, e.g. `fadeFast` or `CarouselLeftSlow`.",
                          "enum": [
                            "fade",
                            "fadeSlow",
                            "fadeFast",
                            "reveal",
                            "revealSlow",
                            "revealFast",
                            "wipeLeft",
                            "wipeLeftSlow",
                            "wipeLeftFast",
                            "wipeRight",
                            "wipeRightSlow",
                            "wipeRightFast",
                            "slideLeft",
                            "slideLeftSlow",
                            "slideLeftFast",
                            "slideRight",
                            "slideRightSlow",
                            "slideRightFast",
                            "slideUp",
                            "slideUpSlow",
                            "slideUpFast",
                            "slideDown",
                            "slideDownSlow",
                            "slideDownFast",
                            "carouselLeft",
                            "carouselLeftSlow",
                            "carouselLeftFast",
                            "carouselRight",
                            "carouselRightSlow",
                            "carouselRightFast",
                            "carouselUp",
                            "carouselUpSlow",
                            "carouselUpFast",
                            "carouselDown",
                            "carouselDownSlow",
                            "carouselDownFast",
                            "shuffleTopRight",
                            "shuffleTopRightSlow",
                            "shuffleTopRightFast",
                            "shuffleRightTop",
                            "shuffleRightTopSlow",
                            "shuffleRightTopFast",
                            "shuffleRightBottom",
                            "shuffleRightBottomSlow",
                            "shuffleRightBottomFast",
                            "shuffleBottomRight",
                            "shuffleBottomRightSlow",
                            "shuffleBottomRightFast",
                            "shuffleBottomLeft",
                            "shuffleBottomLeftSlow",
                            "shuffleBottomLeftFast",
                            "shuffleLeftBottom",
                            "shuffleLeftBottomSlow",
                            "shuffleLeftBottomFast",
                            "shuffleLeftTop",
                            "shuffleLeftTopSlow",
                            "shuffleLeftTopFast",
                            "shuffleTopLeft",
                            "shuffleTopLeftSlow",
                            "shuffleTopLeftFast",
                            "zoom"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Output

{
  "type": "object",
  "description": "The response received after a [render request](#render-asset) is submitted. The render task is queued for rendering and a unique render id is returned.",
  "required": [
    "message",
    "response",
    "success"
  ],
  "properties": {
    "message": {
      "type": "string",
      "description": "`Created`, `Bad Request` or an error message."
    },
    "response": {
      "type": "object",
      "description": "`QueuedResponseData` or an error message.",
      "required": [
        "id",
        "message"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The id of the render task in UUID format."
        },
        "message": {
          "type": "string",
          "description": "Success response message or error details."
        }
      }
    },
    "success": {
      "type": "boolean",
      "description": "`true` if successfully queued, else `false`."
    }
  }
}