Shotstack v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Shotstack is a video, image and audio editing service that allows for the automated generation of videos, images and audio using JSON and a RESTful API.

You arrange and configure an edit and POST it to the API which will render your media and provide a file location when complete.

For more details visit shotstack.io or checkout our getting started documentation.

There are three API's, one for editing and generating assets (Edit API), one for managing hosted assets (Serve API) and one for ingesting and transforming source assets (Ingest API).

Each API has it's own base URL and collection of endpoints. Each API uses the same set of API keys.

Edit API - https://api.shotstack.io/edit/{version}
Edit videos, images and audio assets in the cloud using a simple JSON schema and templates.

Serve API - https://api.shotstack.io/serve/{version}
Inspect and manage the hosting of assets generated by the Edit and Ingest APIs.

Ingest API - https://api.shotstack.io/ingest/{version}
Ingest (upload, store and transform) source footage, images, audio and fonts to be used by the Edit API.

Base URLs:

https://api.shotstack.io/edit/{version}
- version - Set the stage to v1 for production usage without watermarks. Set to stage to use the development sandbox. Default: v1
  - v1
  - stage
https://api.shotstack.io/serve/{version}
- version - Set the stage to v1 for production usage. Set to stage to use the development sandbox. Default: v1
  - v1
  - stage
https://api.shotstack.io/ingest/{version}
- version - Set the stage to v1 for production usage. Set to stage to use the development sandbox. Default: v1
  - v1
  - stage

Authentication

API Key (DeveloperKey)
- Parameter Name: x-api-key, in: header. Set the x-api-key header with your provided key for the correct environment (v1 or stage). Include the header in all calls to the API that are secured with a key.

Edit

The Edit API is used to edit videos, images and audio files in the cloud using a simple to understand JSON schema. Compose an edit using tracks, clips and assets and add transitions, filters, overlays and text. Finally send the JSON to the Edit API to be rendered.

Render Asset

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/render \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/edit/{version}/render HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "timeline": {
    "soundtrack": {
      "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
      "effect": "fadeIn",
      "volume": 0
    },
    "background": "string",
    "fonts": [
      {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
      }
    ],
    "tracks": [
      {
        "clips": [
          {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "asset": {
              "type": "video",
              "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
              "prompt": "Slowly zoom out and orbit left around the object.",
              "model": "seedance-2.0-text-to-video",
              "options": {
                "resolution": "720p",
                "duration": "8",
                "generateAudio": true
              },
              "transcode": false,
              "trim": 2,
              "volume": 0.5,
              "volumeEffect": "none",
              "speed": 1,
              "crop": {
                "top": 0.15,
                "bottom": 0.15,
                "left": 1,
                "right": 1
              },
              "chromaKey": {
                "color": "#00b140",
                "threshold": 150,
                "halo": 100
              }
            },
            "start": 2,
            "length": 5,
            "fit": "cover",
            "scale": 0.5,
            "width": 800,
            "height": 600,
            "position": "top",
            "offset": {
              "x": 0.1,
              "y": -0.2
            },
            "transition": {
              "in": "none",
              "out": "none"
            },
            "effect": "zoomIn",
            "filter": "greyscale",
            "opacity": 0.5,
            "transform": {
              "rotate": {
                "angle": 45
              },
              "skew": {
                "x": 0.5,
                "y": 0.5
              },
              "flip": {
                "horizontal": true,
                "vertical": true
              }
            },
            "alias": "MY_VIDEO_CLIP"
          }
        ]
      }
    ],
    "cache": true
  },
  "output": {
    "format": "mp4",
    "resolution": "hd",
    "aspectRatio": "16:9",
    "size": {
      "width": 1200,
      "height": 800
    },
    "fps": 25,
    "scaleTo": "preview",
    "quality": "medium",
    "repeat": true,
    "mute": false,
    "range": {
      "start": 3,
      "length": 6
    },
    "poster": {
      "capture": 1
    },
    "thumbnail": {
      "capture": 1,
      "scale": 0.3
    },
    "destinations": [
      {
        "provider": "shotstack",
        "exclude": false
      }
    ]
  },
  "merge": [
    {
      "find": "NAME",
      "replace": "Jane"
    }
  ],
  "callback": "https://my-server.com/callback.php",
  "disk": "local",
  "instance": "s1"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/render',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/edit/{version}/render', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/edit/{version}/render',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/edit/{version}/render', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/render");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/render", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /render

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

Rendering Process:

Validation: The edit JSON is validated
Download: All assets are downloaded and cached
Preprocessing: Video assets are automatically processed to fix compatibility issues
Rendering: The timeline is rendered using the processed assets
Output: The final media file is generated and stored

Video Preprocessing: Video assets undergo automatic preprocessing to ensure compatibility. You can force preprocessing by setting "transcode": true on video assets. See Preprocessing for more details.

Base URL: https://api.shotstack.io/edit/{version}

Body parameter

{
  "timeline": {
    "soundtrack": {
      "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
      "effect": "fadeIn",
      "volume": 0
    },
    "background": "string",
    "fonts": [
      {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
      }
    ],
    "tracks": [
      {
        "clips": [
          {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "asset": {
              "type": "video",
              "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
              "prompt": "Slowly zoom out and orbit left around the object.",
              "model": "seedance-2.0-text-to-video",
              "options": {
                "resolution": "720p",
                "duration": "8",
                "generateAudio": true
              },
              "transcode": false,
              "trim": 2,
              "volume": 0.5,
              "volumeEffect": "none",
              "speed": 1,
              "crop": {
                "top": 0.15,
                "bottom": 0.15,
                "left": 1,
                "right": 1
              },
              "chromaKey": {
                "color": "#00b140",
                "threshold": 150,
                "halo": 100
              }
            },
            "start": 2,
            "length": 5,
            "fit": "cover",
            "scale": 0.5,
            "width": 800,
            "height": 600,
            "position": "top",
            "offset": {
              "x": 0.1,
              "y": -0.2
            },
            "transition": {
              "in": "none",
              "out": "none"
            },
            "effect": "zoomIn",
            "filter": "greyscale",
            "opacity": 0.5,
            "transform": {
              "rotate": {
                "angle": 45
              },
              "skew": {
                "x": 0.5,
                "y": 0.5
              },
              "flip": {
                "horizontal": true,
                "vertical": true
              }
            },
            "alias": "MY_VIDEO_CLIP"
          }
        ]
      }
    ],
    "cache": true
  },
  "output": {
    "format": "mp4",
    "resolution": "hd",
    "aspectRatio": "16:9",
    "size": {
      "width": 1200,
      "height": 800
    },
    "fps": 25,
    "scaleTo": "preview",
    "quality": "medium",
    "repeat": true,
    "mute": false,
    "range": {
      "start": 3,
      "length": 6
    },
    "poster": {
      "capture": 1
    },
    "thumbnail": {
      "capture": 1,
      "scale": 0.3
    },
    "destinations": [
      {
        "provider": "shotstack",
        "exclude": false
      }
    ]
  },
  "merge": [
    {
      "find": "NAME",
      "replace": "Jane"
    }
  ],
  "callback": "https://my-server.com/callback.php",
  "disk": "local",
  "instance": "s1"
}

Parameters

Name	In	Type	Required	Description
body	body	Edit	true	The video, image or audio edit specified using JSON.

Example responses

201 Response

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	The queued render details	QueuedResponse

Get Render Status

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/render/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/render/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/render/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/render/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/render/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/render/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/render/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/render/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /render/{id}

Get the rendering status, temporary asset url and details of a render by ID.

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the timeline render task in UUID format
data	query	boolean	false	Include the data parameter in the response. The data parameter includes the original timeline, output and other settings sent to the API. Note: the default is currently `true`, this is deprecated and the default will soon be `false`. If you rely on the data being returned in the response you should explicitly set the parameter to `true`.
merged	query	boolean	false	Used when data is set to true, it will show the merge fields merged in to the data response.

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "response": {
    "status": "rendering",
    "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
    "owner": "5ca6hu7s9k",
    "url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
    "data": {
      "timeline": {
        "soundtrack": {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
          "effect": "fadeInFadeOut"
        },
        "background": "#000000",
        "tracks": [
          {
            "clips": [
              {
                "asset": {
                  "type": "title",
                  "text": "Hello World",
                  "style": "minimal"
                },
                "start": 0,
                "length": 4,
                "transition": {
                  "in": "fade",
                  "out": "fade"
                },
                "effect": "slideRight"
              },
              {
                "asset": {
                  "type": "image",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-image.jpg"
                },
                "start": 3,
                "length": 4,
                "effect": "zoomIn",
                "filter": "greyscale"
              }
            ]
          },
          {
            "clips": [
              {
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-1.mp4",
                  "trim": 10.5,
                  "transcode": true
                },
                "start": 7,
                "length": 4.5
              },
              {
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-2.mp4",
                  "volume": 0.5
                },
                "start": 11.5,
                "length": 5,
                "transition": {
                  "out": "wipeLeft"
                }
              }
            ]
          }
        ]
      },
      "output": {
        "format": "mp4",
        "resolution": "sd"
      }
    },
    "created": "2020-10-30T09:42:29.446Z",
    "updated": "2020-10-30T09:42:39.168Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The render status details	RenderResponse

Create Template

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/templates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/edit/{version}/templates HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "name": "My template",
  "template": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/templates',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/edit/{version}/templates', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/edit/{version}/templates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/edit/{version}/templates', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/templates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /templates

Save an Edit as a re-usable template. Templates can be retrieved and modified in your application before being rendered. Merge fields can be also used to merge data in to a template and render it in a single request.

Base URL: https://api.shotstack.io/edit/{version}

Body parameter

{
  "name": "My template",
  "template": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	Template	true	Create a template with a name and Edit.

Example responses

201 Response

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Template Successfully Created",
    "id": "f5493c17-d01f-445c-bb49-535fae65f219"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	The saved template status including the id	TemplateResponse

List Templates

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/templates \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/templates HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/templates',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/templates', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/templates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/templates', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/templates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /templates

Retrieve a list of templates stored against a users account and stage.

Base URL: https://api.shotstack.io/edit/{version}

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "response": {
    "owner": "5ca6hu7s9k",
    "templates": [
      {
        "id": "f5493c17-d01f-445c-bb49-535fae65f219",
        "name": "My template",
        "created": "2022-06-10T12:50:21.455Z",
        "updated": "2022-06-22T08:24:30.168Z"
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The list of templates stored against a users account	TemplateListResponse

Retrieve Template

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/templates/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/templates/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/templates/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/templates/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/templates/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/templates/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/templates/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /templates/{id}

Retrieve a template by template id.

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the template in UUID format

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "response": {
    "id": "f5493c17-d01f-445c-bb49-535fae65f219",
    "name": "My template",
    "owner": "5ca6hu7s9k",
    "template": {
      "timeline": {
        "soundtrack": {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
          "effect": "fadeIn",
          "volume": 0
        },
        "background": "string",
        "fonts": [
          {
            "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
          }
        ],
        "tracks": [
          {
            "clips": [
              {
                "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                  "prompt": "Slowly zoom out and orbit left around the object.",
                  "model": "seedance-2.0-text-to-video",
                  "options": {
                    "resolution": "720p",
                    "duration": "8",
                    "generateAudio": true
                  },
                  "transcode": false,
                  "trim": 2,
                  "volume": 0.5,
                  "volumeEffect": "none",
                  "speed": 1,
                  "crop": {
                    "top": 0.15,
                    "bottom": 0.15,
                    "left": 1,
                    "right": 1
                  },
                  "chromaKey": {
                    "color": "#00b140",
                    "threshold": 150,
                    "halo": 100
                  }
                },
                "start": 2,
                "length": 5,
                "fit": "cover",
                "scale": 0.5,
                "width": 800,
                "height": 600,
                "position": "top",
                "offset": {
                  "x": 0.1,
                  "y": -0.2
                },
                "transition": {
                  "in": "none",
                  "out": "none"
                },
                "effect": "zoomIn",
                "filter": "greyscale",
                "opacity": 0.5,
                "transform": {
                  "rotate": {
                    "angle": 45
                  },
                  "skew": {
                    "x": 0.5,
                    "y": 0.5
                  },
                  "flip": {
                    "horizontal": true,
                    "vertical": true
                  }
                },
                "alias": "MY_VIDEO_CLIP"
              }
            ]
          }
        ],
        "cache": true
      },
      "output": {
        "format": "mp4",
        "resolution": "hd",
        "aspectRatio": "16:9",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fps": 25,
        "scaleTo": "preview",
        "quality": "medium",
        "repeat": true,
        "mute": false,
        "range": {
          "start": 3,
          "length": 6
        },
        "poster": {
          "capture": 1
        },
        "thumbnail": {
          "capture": 1,
          "scale": 0.3
        },
        "destinations": [
          {
            "provider": "shotstack",
            "exclude": false
          }
        ]
      },
      "merge": [
        {
          "find": "NAME",
          "replace": "Jane"
        }
      ],
      "callback": "https://my-server.com/callback.php",
      "disk": "local",
      "instance": "s1"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The template details including the Edit	TemplateDataResponse

Update Template

Code samples

# You can also use wget
curl -X PUT https://api.shotstack.io/edit/{version}/templates/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

PUT https://api.shotstack.io/edit/{version}/templates/{id} HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "name": "My template",
  "template": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/templates/{id}',
{
  method: 'PUT',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.shotstack.io/edit/{version}/templates/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.put 'https://api.shotstack.io/edit/{version}/templates/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.put('https://api.shotstack.io/edit/{version}/templates/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.shotstack.io/edit/{version}/templates/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /templates/{id}

Update an existing template by template id.

Base URL: https://api.shotstack.io/edit/{version}

Body parameter

{
  "name": "My template",
  "template": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	Template	true	Update an individual templates name and Edit. Both template name and template must be provided. If the template parameter is omitted a blank template will be saved.
id	path	string	true	The id of the template in UUID format

Example responses

200 Response

{
  "success": true,
  "message": "OK",
  "response": {
    "message": "Template Successfully Updated",
    "id": "f5493c17-d01f-445c-bb49-535fae65f219"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Update a templates name and Edit	TemplateResponse

Delete Template

Code samples

# You can also use wget
curl -X DELETE https://api.shotstack.io/edit/{version}/templates/{id} \
  -H 'x-api-key: API_KEY'

DELETE https://api.shotstack.io/edit/{version}/templates/{id} HTTP/1.1
Host: api.shotstack.io

const fetch = require('node-fetch');

const headers = {
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/templates/{id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.shotstack.io/edit/{version}/templates/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'x-api-key' => 'API_KEY'
}

result = RestClient.delete 'https://api.shotstack.io/edit/{version}/templates/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'x-api-key': 'API_KEY'
}

r = requests.delete('https://api.shotstack.io/edit/{version}/templates/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.shotstack.io/edit/{version}/templates/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /templates/{id}

Delete a template by its template id.

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the template in UUID format

Responses

Status	Meaning	Description	Schema
204	No Content	An empty response signifying the template has been deleted	None

Render Template

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/templates/render \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/edit/{version}/templates/render HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "id": "f5493c17-d01f-445c-bb49-535fae65f219",
  "merge": [
    {
      "find": "NAME",
      "replace": "Jane"
    }
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/templates/render',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/edit/{version}/templates/render', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/edit/{version}/templates/render',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/edit/{version}/templates/render', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/render");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/templates/render", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /templates/render

Render an asset from a template id and optional merge fields. Merge fields can be used to replace placeholder variables within the Edit.

Base URL: https://api.shotstack.io/edit/{version}

Body parameter

{
  "id": "f5493c17-d01f-445c-bb49-535fae65f219",
  "merge": [
    {
      "find": "NAME",
      "replace": "Jane"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	TemplateRender	true	Render a template by template id.

Example responses

201 Response

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	The queued status including the render id. Check the status of the render using the id and the render status endpoint.	QueuedResponse

Inspect Media

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/probe/{url} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/probe/{url} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/probe/{url}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/probe/{url}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/probe/{url}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/probe/{url}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/probe/{url}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/probe/{url}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /probe/{url}

Inspects any media asset (image, video, audio) on the internet using a hosted version of FFprobe. The probe endpoint returns useful information about an asset such as width, height, duration, rotation, framerate, etc...

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
url	path	string	true	The URL of the media to inspect, must be URL encoded.

Example responses

200 Response

{
  "success": true,
  "message": "Created",
  "response": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	FFprobe response formatted as JSON.	ProbeResponse

Generate Asset

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/generate \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/edit/{version}/generate HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "asset": {
    "type": "image",
    "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
    "prompt": "A serene landscape with a crystal-clear mountain lake at sunrise.",
    "model": "flux-schnell",
    "options": {
      "resolution": "1K",
      "aspectRatio": "16:9"
    },
    "crop": {
      "top": 0.15,
      "bottom": 0.15,
      "left": 1,
      "right": 1
    }
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/generate',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/edit/{version}/generate', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/edit/{version}/generate',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/edit/{version}/generate', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/generate");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/generate", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /generate

Generate a single image, video or audio asset from a text prompt without rendering a full edit. Submit a prompt-bearing asset; the response is immediate when an identical asset has been generated before (results are cached by prompt, model and options), otherwise the job is queued and can be polled via the status endpoint.

Generation is billed in credits per asset. Identical repeat requests resolve from the cache at no charge.

Base URL: https://api.shotstack.io/edit/{version}

Body parameter

{
  "asset": {
    "type": "image",
    "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
    "prompt": "A serene landscape with a crystal-clear mountain lake at sunrise.",
    "model": "flux-schnell",
    "options": {
      "resolution": "1K",
      "aspectRatio": "16:9"
    },
    "crop": {
      "top": 0.15,
      "bottom": 0.15,
      "left": 1,
      "right": 1
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	A prompt-bearing image, video or audio asset to generate.
» asset	body	any	true	none
»» anonymous	body	ImageAsset	false	The ImageAsset adds an image to a Clip. The image can be sourced from a URL
»»» type	body	string	true	The type of asset - set to `image` for images.
»»» src	body	string	false	The image source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the image is regenerated from the prompt at render time.
»»» prompt	body	string	false	A text prompt to generate the image from. The engine generates an image at render time and fills `src` automatically; an existing `src` is treated as a preview placeholder and replaced. Use `model` to choose the generator and `options` to configure it.
»»» model	body	string	false	The generation model to use when `prompt` is set (e.g. `flux-schnell`, `nano-banana-2`). Defaults to `nano-banana-2` if omitted. Each model's available options are defined by the model registry.
»»» options	body	object	false	Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.
»»» crop	body	Crop	false	Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.
»»»» top	body	number(float)	false	Crop from the top of the asset
»»»» bottom	body	number(float)	false	Crop from the bottom of the asset
»»»» left	body	number(float)	false	Crop from the left of the asset
»»»» right	body	number(float)	false	Crop from the left of the asset
»» anonymous	body	VideoAsset	false	The VideoAsset adds a video to a Clip. The video can be sourced from a URL
»»» type	body	string	true	The type of asset - set to `video` for videos.
»»» src	body	string	false	The video source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the video is regenerated from the prompt at render time.
»»» prompt	body	string	false	A text prompt to generate the video from. The engine generates a video at render time and fills `src` automatically; an existing `src` is treated as a preview placeholder and replaced. Use `model` to choose the generator and `options` to configure it. A starting image goes in `options.inputSrc`, on the models that accept one.
»»» model	body	string	false	The generation model to use when `prompt` is set (e.g. `seedance-2.0-text-to-video`). Defaults to `seedance-2.0-text-to-video` if omitted. `GET /models` lists what is available and the options each accepts.
»»» options	body	object	false	Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.
»»» transcode	body	boolean	false	Set to `true` to force re-encoding of the video during preprocessing. This can help resolve compatibility issues, fix rotation problems, synchronize audio, or convert formats. The video will be processed to ensure optimal compatibility with the rendering engine.
»»» trim	body	number	false	The start trim point of the video clip, in seconds (defaults to 0). Videos will start from the in trim point. The video will play until the file ends or the Clip length is reached.
»»» volume	body	any	false	Set the volume of the video clip. Use a number or an array of Tween objects to create custom volume transitions.
»»»» anonymous	body	number(float)	false	The volume level for the video clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1).
»»»» anonymous	body	[Tween]	false	An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time.
»»»»» from	body	any	false	The initial property value at the start of the animation.
»»»»» to	body	any	false	The final property value at the end of the animation.
»»»»» start	body	number	false	The time in seconds when the animation starts, relative to the clip, not the timeline.
»»»»» length	body	number	false	The duration of the animation in seconds.
»»»»» interpolation	body	string	false	The interpolation method to use for the animation. Available options are:
»»»»» easing	body	string	false	The easing function to use for the animation. Easing controls the rate of change of the animated value, allowing for more natural motion by speeding up or slowing down the animation at different points. Only applicable if interpolation is set to `bezier`.
»»» volumeEffect	body	string	false	Preset volume effects to apply to the video asset
»»» speed	body	number(float)	false	Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire video (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire video (i.e. original length / 2).
»»» crop	body	Crop	false	Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.
»»» chromaKey	body	ChromaKey	false	Chroma key is a technique that replaces a specific color in a video with a different background image or video, enabling seamless integration of diverse environments. Commonly used for green screen and blue screen effects.
»»»» color	body	string	true	The chroma key color as a hex value. Use green (#00b140) for green screens or blue (#0000FF) for blue screens. Any valid hex color can be used as the key color.
»»»» threshold	body	integer	false	Pixels within this distance from the key color are eliminated by setting their alpha values to zero.
»»»» halo	body	integer	false	Pixels within the halo distance from the threshold boundary are given an increasing alpha value based on their distance from the threshold.
»» anonymous	body	AudioAsset	false	The AudioAsset adds audio to a Clip. The audio can be sourced from a URL
»»» type	body	string	true	The type of asset - set to `audio` for audio assets.
»»» src	body	string	false	The audio source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the audio is regenerated from the prompt at render time.
»»» prompt	body	string	false	A text prompt. For text-to-speech models the prompt is the spoken text; for music models it describes the sound to generate. The generated `src` is filled in automatically; an existing `src` is treated as a preview placeholder and replaced.
»»» model	body	string	false	The generation model to use when `prompt` is set (e.g. `polly-neural`, `elevenlabs-tts`, `elevenlabs-music`). Defaults to `elevenlabs-tts` (with a default voice) if omitted. Each model's available options are defined by the model registry.
»»» options	body	object	false	Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.
»»» trim	body	number	false	The start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the in trim point. The audio will play until the file ends or the Clip length is reached.
»»» volume	body	any	false	Set the volume of the audio clip. Use a number or an array of Tween objects to create custom volume transitions.
»»»» anonymous	body	number(float)	false	The volume level for the audio clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1).
»»»» anonymous	body	[Tween]	false	An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time.
»»» speed	body	number(float)	false	Adjust the playback speed of the audio clip between 0 (paused) and 10 (10x normal speed), where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire audio (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire audio (i.e. original length / 2).
»»» effect	body	string	false	The effect to apply to the audio asset

Detailed descriptions

»» anonymous: The ImageAsset adds an image to a Clip. The image can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided.

Source URL: set src to the publicly accessible URL of a jpg or png file.
Generated: set prompt to describe the image. Choose a generator with model and configure it with model-specific options; the engine fills src in automatically.
Both: src acts as a preview placeholder while prompt drives generation — the image is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

»» anonymous: The VideoAsset adds a video to a Clip. The video can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided.

Source URL: set src to the URL of an mp4 (or compatible) video file.
Generated: set prompt to describe the motion. Choose a generator with model and configure it with model-specific options. Models that animate a starting image take it as options.inputSrc; the default model generates from the prompt alone. The generated src is filled in automatically.
Both: src acts as a preview placeholder while prompt drives generation — the video is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

»»»»» interpolation: The interpolation method to use for the animation. Available options are:

`linear` - a linear interpolation between the start and end values.
`bezier` - a bezier curve interpolation between the start and end values.
`constant` - an interpolation where the property instantly jumps from the start to the end value, without any gradual transition.

»»» volumeEffect: Preset volume effects to apply to the video asset

`fadeIn` - fade volume in only
`fadeOut` - fade volume out only
`fadeInFadeOut` - fade volume in and out

»» anonymous: The AudioAsset adds audio to a Clip. The audio can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided.

Source URL: set src to a publicly accessible audio URL (e.g. mp3).
Generated speech: set prompt to the spoken text and choose a text-to-speech model; set the voice via options.
Generated music or SFX: set prompt describing the sound and choose a music generation model.
Both: src acts as a preview placeholder while prompt drives generation — the audio is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.
Use model to choose the generator and options to configure it. The generated src is filled in automatically.

»»» effect: The effect to apply to the audio asset

`fadeIn` - fade volume in only
`fadeOut` - fade volume out only
`fadeInFadeOut` - fade volume in and out

Enumerated Values

Parameter	Value
»»» type	image
»»» type	video
»»»»» interpolation	linear
»»»»» interpolation	bezier
»»»»» interpolation	constant
»»»»» easing	ease
»»»»» easing	easeIn
»»»»» easing	easeOut
»»»»» easing	easeInOut
»»»»» easing	easeInQuad
»»»»» easing	easeInCubic
»»»»» easing	easeInQuart
»»»»» easing	easeInQuint
»»»»» easing	easeInSine
»»»»» easing	easeInExpo
»»»»» easing	easeInCirc
»»»»» easing	easeInBack
»»»»» easing	easeOutQuad
»»»»» easing	easeOutCubic
»»»»» easing	easeOutQuart
»»»»» easing	easeOutQuint
»»»»» easing	easeOutSine
»»»»» easing	easeOutExpo
»»»»» easing	easeOutCirc
»»»»» easing	easeOutBack
»»»»» easing	easeInOutQuad
»»»»» easing	easeInOutCubic
»»»»» easing	easeInOutQuart
»»»»» easing	easeInOutQuint
»»»»» easing	easeInOutSine
»»»»» easing	easeInOutExpo
»»»»» easing	easeInOutCirc
»»»»» easing	easeInOutBack
»»» volumeEffect	none
»»» volumeEffect	fadeIn
»»» volumeEffect	fadeOut
»»» volumeEffect	fadeInFadeOut
»»» type	audio
»»» effect	none
»»» effect	fadeIn
»»» effect	fadeOut
»»» effect	fadeInFadeOut

Example responses

200 Response

```json { "id": "8a1f2c3d-4e5b-5a6c-9d7e-1f2a3b4c5d6e", "status": "done", "url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/owner/8a1f2c3d.png", "error": "string" } ```

Responses

Status	Meaning	Description	Schema
200	OK	The generated asset was already cached and is immediately available.	Inline
202	Accepted	The generation job has been queued. Poll the status endpoint.	Inline

Response Schema

Status Code 200

The status of an on-demand asset generation job. Completed jobs include the public URL of the generated asset.

Name	Type	Required	Restrictions	Description
» id	string	true	none	The generation job id. Deterministic for a given owner and asset payload (or idempotency key), so identical requests return the same job and cached result.
» status	string	true	none	The status of the generation job.
» url	string	false	none	The public URL of the generated asset. Present only when `status` is `done`.
» error	string	false	none	A human readable error message. Present only when `status` is `failed`.

Enumerated Values

Property	Value
status	queued
status	processing
status	done
status	failed

Status Code 202

The status of an on-demand asset generation job. Completed jobs include the public URL of the generated asset.

Name	Type	Required	Restrictions	Description
» id	string	true	none	The generation job id. Deterministic for a given owner and asset payload (or idempotency key), so identical requests return the same job and cached result.
» status	string	true	none	The status of the generation job.
» url	string	false	none	The public URL of the generated asset. Present only when `status` is `done`.
» error	string	false	none	A human readable error message. Present only when `status` is `failed`.

Enumerated Values

Property	Value
status	queued
status	processing
status	done
status	failed

Response Headers

Status	Header	Type	Format	Description
202	Location	string		The relative URL to poll for job status.
202	Retry-After	integer		Suggested seconds to wait before polling.

Get Generation Status

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/generate/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/generate/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/generate/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/generate/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/generate/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/generate/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/generate/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/generate/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /generate/{id}

Get the status of an on-demand asset generation job created with the generate endpoint. Jobs are owner-scoped.

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The generation job id returned by the generate endpoint.

Example responses

200 Response

{
  "id": "8a1f2c3d-4e5b-5a6c-9d7e-1f2a3b4c5d6e",
  "status": "done",
  "url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/owner/8a1f2c3d.png",
  "error": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	The generation job has finished (done or failed).	Inline
202	Accepted	The generation job is still processing.	Inline

Response Schema

Status Code 200

The status of an on-demand asset generation job. Completed jobs include the public URL of the generated asset.

Name	Type	Required	Restrictions	Description
» id	string	true	none	The generation job id. Deterministic for a given owner and asset payload (or idempotency key), so identical requests return the same job and cached result.
» status	string	true	none	The status of the generation job.
» url	string	false	none	The public URL of the generated asset. Present only when `status` is `done`.
» error	string	false	none	A human readable error message. Present only when `status` is `failed`.

Enumerated Values

Property	Value
status	queued
status	processing
status	done
status	failed

Status Code 202

The status of an on-demand asset generation job. Completed jobs include the public URL of the generated asset.

Name	Type	Required	Restrictions	Description
» id	string	true	none	The generation job id. Deterministic for a given owner and asset payload (or idempotency key), so identical requests return the same job and cached result.
» status	string	true	none	The status of the generation job.
» url	string	false	none	The public URL of the generated asset. Present only when `status` is `done`.
» error	string	false	none	A human readable error message. Present only when `status` is `failed`.

Enumerated Values

Property	Value
status	queued
status	processing
status	done
status	failed

List Generation Models

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/models \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/models HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/models',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/models', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/models',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/models', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/models");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/models", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /models

List the generation models available for prompt-bearing image, video and audio assets, with the options each accepts and what it costs in credits.

Use this to populate a model picker and render its option fields, rather than hard coding a model list. A newly launched model appears here without any change on your side. Each entry carries the asset type it generates, so filter the list client side when a picker only needs one kind.

Option schemas are omitted by default. Request them with expand=options.

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
expand	query	string	false	Set to `options` to include each model's option schema in the list. Omitted by default to keep the response small.

Enumerated Values

Parameter	Value
expand	options

Example responses

200 Response

{
  "models": [
    {
      "model": "seedance-2.0-text-to-video",
      "type": "video",
      "pricing": {
        "credits": {
          "480p": 0.9375,
          "720p": 1.8962,
          "1080p": 4.2625
        },
        "tieredBy": {
          "option": "resolution",
          "default": "720p"
        },
        "quantity": {
          "measure": "clipSeconds",
          "per": 60,
          "min": 3,
          "max": 600,
          "default": 30,
          "round": "up"
        },
        "effectiveFrom": "2026-08-13"
      },
      "options": {}
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	The available generation models.	Inline

Response Schema

Status Code 200

The generation models available to this account.

Name	Type	Required	Restrictions	Description
» models	[#/paths/~1models~1%7Bid%7D/get/responses/200/content/application~1json/schema]	true	none	The available models.
»» model	string	true	none	The identifier to set as the asset `model`. Carries no provider name, so routing can change without a public rename.
»» type	string	true	none	The asset type this model generates.
»» pricing	object	false	none	What one generation with this model costs.
»»» credits	any	true	none	Credits per unit. A number when the rate is flat, or an object keyed by the values of the option named in `tieredBy`.

oneOf

Name	Type	Required	Restrictions	Description
»»»» anonymous	number	false	none	none

xor

Name	Type	Required	Restrictions	Description
»»»» anonymous	object	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»» tieredBy	object	false	none	The option whose value selects the rate, and the value assumed when the option is absent. Present only when `credits` is keyed.
»»»» option	string	true	none	none
»»»» default	string	true	none	none
»»» quantity	object	false	none	How many units a generation consumes. Take the value `measure` names, or `default` when the request carries none, hold it within `min` and `max`, divide by `per`, and round up when `round` is `up`. Absent when one generation is one unit.
»»»» measure	string	true	none	What the count is taken from, and the scale it is measured in.
»»»» per	number	true	none	How many of `measure` make one billable unit.
»»»» min	number	false	none	Fewest accepted. A smaller request is charged at this.
»»»» max	number	false	none	Most accepted. A larger request is charged at this.
»»»» default	number	false	none	Assumed when the request carries no value.
»»»» round	string	false	none	Present when a partial unit is charged as a whole one. A 61 second track on a per-minute rate is charged as two minutes.
»»» effectiveFrom	string	true	none	The date this rate took effect, or `legacy` for a rate that predates dated pricing.
»» options	object	false	none	JSON Schema for the model's `options` object. Only returned for a single model, or for a list requested with `expand=options`. Values outside this schema are rejected.

Enumerated Values

Property	Value
type	image
type	video
type	audio
measure	clipSeconds
measure	promptCharacters
round	up

Get Generation Model

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/models/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/edit/{version}/models/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/models/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/edit/{version}/models/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/edit/{version}/models/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/edit/{version}/models/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/models/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/models/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /models/{id}

Get one generation model, including the JSON Schema for the options it accepts and what it costs in credits.

Base URL: https://api.shotstack.io/edit/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The model identifier, as returned by the list endpoint.

Example responses

200 Response

{
  "model": "seedance-2.0-text-to-video",
  "type": "video",
  "pricing": {
    "credits": {
      "480p": 0.9375,
      "720p": 1.8962,
      "1080p": 4.2625
    },
    "tieredBy": {
      "option": "resolution",
      "default": "720p"
    },
    "quantity": {
      "measure": "clipSeconds",
      "per": 60,
      "min": 3,
      "max": 600,
      "default": 30,
      "round": "up"
    },
    "effectiveFrom": "2026-08-13"
  },
  "options": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	The generation model, with its option schema.	Inline
404	Not Found	No model exists with that identifier.	None

Response Schema

Status Code 200

A generation model available to prompt-bearing image, video and audio assets, with the options it accepts and what it costs. Render a model picker and its option fields from this rather than hard coding a model list, so a newly launched model is available without a client release.

Name	Type	Required	Restrictions	Description
» model	string	true	none	The identifier to set as the asset `model`. Carries no provider name, so routing can change without a public rename.
» type	string	true	none	The asset type this model generates.
» pricing	object	false	none	What one generation with this model costs.
»» credits	any	true	none	Credits per unit. A number when the rate is flat, or an object keyed by the values of the option named in `tieredBy`.

oneOf

Name	Type	Required	Restrictions	Description
»»» anonymous	number	false	none	none

xor

Name	Type	Required	Restrictions	Description
»»» anonymous	object	false	none	none

continued

Name	Type	Required	Restrictions	Description
»» tieredBy	object	false	none	The option whose value selects the rate, and the value assumed when the option is absent. Present only when `credits` is keyed.
»»» option	string	true	none	none
»»» default	string	true	none	none
»» quantity	object	false	none	How many units a generation consumes. Take the value `measure` names, or `default` when the request carries none, hold it within `min` and `max`, divide by `per`, and round up when `round` is `up`. Absent when one generation is one unit.
»»» measure	string	true	none	What the count is taken from, and the scale it is measured in.
»»» per	number	true	none	How many of `measure` make one billable unit.
»»» min	number	false	none	Fewest accepted. A smaller request is charged at this.
»»» max	number	false	none	Most accepted. A larger request is charged at this.
»»» default	number	false	none	Assumed when the request carries no value.
»»» round	string	false	none	Present when a partial unit is charged as a whole one. A 61 second track on a per-minute rate is charged as two minutes.
»» effectiveFrom	string	true	none	The date this rate took effect, or `legacy` for a rate that predates dated pricing.
» options	object	false	none	JSON Schema for the model's `options` object. Only returned for a single model, or for a list requested with `expand=options`. Values outside this schema are rejected.

Enumerated Values

Property	Value
type	image
type	video
type	audio
measure	clipSeconds
measure	promptCharacters
round	up

Serve

Assets generated by the Edit API or uploaded via the Ingest API are sent to the Serve API. The Serve API includes a simple hosting service with a CDN or you can send assets to third party services like AWS S3 or Mux. The Serve API includes endpoints to look up assets, where they are hosted and their status.

Get Asset

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/serve/{version}/assets/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/serve/{version}/assets/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/serve/{version}/assets/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/serve/{version}/assets/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/serve/{version}/assets/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/serve/{version}/assets/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/serve/{version}/assets/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/serve/{version}/assets/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /assets/{id}

The Serve API is used to interact with, and delete hosted assets including videos, images, audio files, thumbnails and poster images. Use this endpoint to fetch an asset by asset id. Note that an asset id is unique for each asset and different from the render id.

Base URL: https://api.shotstack.io/serve/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the asset in UUID format

Example responses

200 Response

{
  "data": {
    "type": "asset",
    "attributes": {
      "id": "a4482cbf-e321-42a2-ac8b-947d26886840",
      "owner": "5ca6hu7s9k",
      "region": "au",
      "renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
      "providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
      "filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
      "url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
      "status": "ready",
      "created": "2021-06-30T09:42:29.446Z",
      "updated": "2021-06-30T09:42:30.168Z"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get asset by asset id	AssetResponse

Delete Asset

Code samples

# You can also use wget
curl -X DELETE https://api.shotstack.io/serve/{version}/assets/{id} \
  -H 'x-api-key: API_KEY'

DELETE https://api.shotstack.io/serve/{version}/assets/{id} HTTP/1.1
Host: api.shotstack.io

const fetch = require('node-fetch');

const headers = {
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/serve/{version}/assets/{id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.shotstack.io/serve/{version}/assets/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'x-api-key' => 'API_KEY'
}

result = RestClient.delete 'https://api.shotstack.io/serve/{version}/assets/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'x-api-key': 'API_KEY'
}

r = requests.delete('https://api.shotstack.io/serve/{version}/assets/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/serve/{version}/assets/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.shotstack.io/serve/{version}/assets/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /assets/{id}

Delete an asset by its asset id. If a render creates multiple assets, such as thumbnail and poster images, each asset must be deleted individually by the asset id.

Base URL: https://api.shotstack.io/serve/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the asset in UUID format

Responses

Status	Meaning	Description	Schema
204	No Content	An empty response signifying the asset has been deleted	None

Get Asset by Render ID

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/serve/{version}/assets/render/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/serve/{version}/assets/render/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/serve/{version}/assets/render/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/serve/{version}/assets/render/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/serve/{version}/assets/render/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/serve/{version}/assets/render/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/serve/{version}/assets/render/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/serve/{version}/assets/render/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /assets/render/{id}

A render may generate more than one file, such as a video, thumbnail and poster image. When the assets are created the only known id is the render id returned by the original render request, status request or webhook. This endpoint lets you look up one or more assets by the render id.

Base URL: https://api.shotstack.io/serve/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The render id associated with the asset in UUID format

Example responses

200 Response

{
  "data": [
    {
      "type": "asset",
      "attributes": {
        "id": "a4482cbf-e321-42a2-ac8b-947d26886840",
        "owner": "5ca6hu7s9k",
        "region": "au",
        "renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
        "providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
        "filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
        "url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
        "status": "ready",
        "created": "2021-06-30T09:42:29.446Z",
        "updated": "2021-06-30T09:42:30.168Z"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Get one or more assets by render id	AssetRenderResponse

Transfer Asset

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/serve/{version}/assets \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/serve/{version}/assets HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "url": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
  "id": "018e8937-5015-75ee-aab6-03f214981133",
  "destinations": [
    {
      "provider": "shotstack",
      "exclude": false
    }
  ]
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/serve/{version}/assets',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/serve/{version}/assets', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/serve/{version}/assets',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/serve/{version}/assets', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/serve/{version}/assets");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/serve/{version}/assets", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /assets

Transfer a file from any publicly available URL to one or more Serve API destinations.

Base URL: https://api.shotstack.io/serve/{version}

Body parameter

{
  "url": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
  "id": "018e8937-5015-75ee-aab6-03f214981133",
  "destinations": [
    {
      "provider": "shotstack",
      "exclude": false
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	Transfer	true	Fetch an asset from a URL and send it to one or more destinations.

Example responses

200 Response

{
  "data": {
    "type": "asset",
    "attributes": {
      "id": "018e8937-5015-75ee-aab6-03f214981133",
      "owner": "5ca6hu7s9k",
      "status": "queued",
      "created": "2023-09-28T11:17:32.226Z"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The transfer request details and status	TransferResponse

Ingest

The Ingest API lets you upload and store your source footage and user generated content in close proximity to the Edit API. Instead of hosting your own assets or building your own uploader you can use the Ingest API. The Ingest API provides endpoints to fetch and upload files and check their status and URLs. All ingested files are available directly from an S3 bucket URL or via CDN (Serve API).

Fetch Source

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/ingest/{version}/sources \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/ingest/{version}/sources HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json

const fetch = require('node-fetch');
const inputBody = {
  "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
  "outputs": {
    "renditions": [
      {
        "format": "mp4",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fit": "crop",
        "resolution": "hd",
        "quality": 70,
        "fps": 25,
        "speed": {
          "speed": 1.5,
          "preservePitch": false
        },
        "keyframeInterval": 10,
        "fixOffset": true,
        "fixRotation": true,
        "enhance": {
          "audio": {
            "provider": "dolby",
            "options": {
              "preset": "studio"
            }
          }
        },
        "filename": "my-video"
      }
    ],
    "transcription": {
      "format": "vtt"
    }
  },
  "destinations": {
    "provider": "shotstack",
    "exclude": false
  },
  "callback": "https://my-server.com/callback.php"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/ingest/{version}/sources',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'Accept' => 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/ingest/{version}/sources', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/ingest/{version}/sources',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/ingest/{version}/sources', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/ingest/{version}/sources", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /sources

Queue a source file to be fetched from a URL and stored by Shotstack. Source files can be videos, images, audio files and fonts. Once ingested, new output renditions can be created from the source file.

Base URL: https://api.shotstack.io/ingest/{version}

Body parameter

{
  "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
  "outputs": {
    "renditions": [
      {
        "format": "mp4",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fit": "crop",
        "resolution": "hd",
        "quality": 70,
        "fps": 25,
        "speed": {
          "speed": 1.5,
          "preservePitch": false
        },
        "keyframeInterval": 10,
        "fixOffset": true,
        "fixRotation": true,
        "enhance": {
          "audio": {
            "provider": "dolby",
            "options": {
              "preset": "studio"
            }
          }
        },
        "filename": "my-video"
      }
    ],
    "transcription": {
      "format": "vtt"
    }
  },
  "destinations": {
    "provider": "shotstack",
    "exclude": false
  },
  "callback": "https://my-server.com/callback.php"
}

Parameters

Name	In	Type	Required	Description
body	body	Source	true	Ingest a video, image, audio or font file from the provided URL. Optionally provide a list of output renditions.

Example responses

201 Response

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

Responses

Status	Meaning	Description	Schema
201	Created	The queued source file details	QueuedSourceResponse
400	Bad Request	A list of validation and other errors	IngestErrorResponse

List Sources

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/ingest/{version}/sources \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/ingest/{version}/sources HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/ingest/{version}/sources',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/ingest/{version}/sources', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/ingest/{version}/sources',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/ingest/{version}/sources', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/ingest/{version}/sources", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /sources

Retrieve a list of ingested source files stored against a users account and stage.

Base URL: https://api.shotstack.io/ingest/{version}

Example responses

200 Response

{
  "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-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
        "status": "ready",
        "outputs": {
          "renditions": [
            {
              "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
              "status": "ready",
              "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
              "executionTime": 4120.36,
              "transformation": {
                "format": "mp4",
                "size": {
                  "width": 1200,
                  "height": 800
                },
                "fit": "crop",
                "resolution": "hd",
                "quality": 70,
                "fps": 25,
                "speed": {
                  "speed": 1.5,
                  "preservePitch": false
                },
                "keyframeInterval": 10,
                "fixOffset": true,
                "fixRotation": true,
                "enhance": {
                  "audio": {
                    "provider": "dolby",
                    "options": {}
                  }
                },
                "filename": "my-video"
              },
              "width": 1920,
              "height": 1080,
              "duration": 25.86,
              "fps": 23.967
            }
          ]
        },
        "width": 1920,
        "height": 1080,
        "duration": 25.86,
        "fps": 23.967,
        "created": "2023-01-02T01:47:18.973Z",
        "updated": "2023-01-02T01:47:37.260Z"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	The list of ingested source files stored against a users account	SourceListResponse

Get Source

Code samples

# You can also use wget
curl -X GET https://api.shotstack.io/ingest/{version}/sources/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

GET https://api.shotstack.io/ingest/{version}/sources/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/ingest/{version}/sources/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.shotstack.io/ingest/{version}/sources/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.get 'https://api.shotstack.io/ingest/{version}/sources/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.get('https://api.shotstack.io/ingest/{version}/sources/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.shotstack.io/ingest/{version}/sources/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /sources/{id}

Fetch a source file details and status by its id.

Base URL: https://api.shotstack.io/ingest/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the source file in KSUID format.

Example responses

200 Response

{
  "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-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
      "status": "ready",
      "outputs": {
        "renditions": [
          {
            "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
            "status": "ready",
            "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
            "executionTime": 4120.36,
            "transformation": {
              "format": "mp4",
              "size": {
                "width": 1200,
                "height": 800
              },
              "fit": "crop",
              "resolution": "hd",
              "quality": 70,
              "fps": 25,
              "speed": {
                "speed": 1.5,
                "preservePitch": false
              },
              "keyframeInterval": 10,
              "fixOffset": true,
              "fixRotation": true,
              "enhance": {
                "audio": {
                  "provider": "dolby",
                  "options": {
                    "preset": "studio"
                  }
                }
              },
              "filename": "my-video"
            },
            "width": 1920,
            "height": 1080,
            "duration": 25.86,
            "fps": 23.967
          }
        ]
      },
      "width": 1920,
      "height": 1080,
      "duration": 25.86,
      "fps": 23.967,
      "created": "2023-01-02T01:47:18.973Z",
      "updated": "2023-01-02T01:47:37.260Z"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	Get source file details by id	SourceResponse

Delete Source

Code samples

# You can also use wget
curl -X DELETE https://api.shotstack.io/ingest/{version}/sources/{id} \
  -H 'x-api-key: API_KEY'

DELETE https://api.shotstack.io/ingest/{version}/sources/{id} HTTP/1.1
Host: api.shotstack.io

const fetch = require('node-fetch');

const headers = {
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/ingest/{version}/sources/{id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.shotstack.io/ingest/{version}/sources/{id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'x-api-key' => 'API_KEY'
}

result = RestClient.delete 'https://api.shotstack.io/ingest/{version}/sources/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'x-api-key': 'API_KEY'
}

r = requests.delete('https://api.shotstack.io/ingest/{version}/sources/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.shotstack.io/ingest/{version}/sources/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /sources/{id}

Delete an ingested source file by its id.

Base URL: https://api.shotstack.io/ingest/{version}

Parameters

Name	In	Type	Required	Description
id	path	string	true	The id of the source file in KSUID format.

Responses

Status	Meaning	Description	Schema
204	No Content	An empty response signifying the ingested source file has been deleted.	None

Direct Upload

Code samples

# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/upload \
  -H 'Accept: application/json' \
  -H 'x-api-key: API_KEY'

POST https://api.shotstack.io/edit/{version}/upload HTTP/1.1
Host: api.shotstack.io
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{version}/upload',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

 'application/json',
    'x-api-key' => 'API_KEY',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.shotstack.io/edit/{version}/upload', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'x-api-key' => 'API_KEY'
}

result = RestClient.post 'https://api.shotstack.io/edit/{version}/upload',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': 'API_KEY'
}

r = requests.post('https://api.shotstack.io/edit/{version}/upload', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{version}/upload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "x-api-key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/upload", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /upload

Request a signed URL to upload a file to. The response returns a signed URL that you use to upload the file to. The signed URL looks similar to:

https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV7UWDMGTZLHTXP&Expires=1677209777&Signature=PKR4dGDDdOuMTAQmDASzLGmLOeo%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEGMaDmFwLX......56osBGByztm7WZdbmXzO09KR

In a separate API call, use this signed URL to send a PUT request with the binary file. Using cURL you can use a command like:

curl -X PUT -T video.mp4 {data.attributes.url}

Where video.mp4 is the file you want to upload and {data.attributes.url} is the signed URL returned in the response. The request must be a PUT type.

The SDK does not currently support the PUT request. You can use the SDK to make the request for the signed URL and then use cURL to make the PUT request.

Base URL: https://api.shotstack.io/ingest/{version}

Example responses

200 Response

{
  "data": {
    "type": "upload",
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
    "attributes": {
      "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
      "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
      "expires": "2023-01-02T02:47:37.260Z"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The id and signed URL to upload to.	UploadResponse

Schemas

Edit

{
  "timeline": {
    "soundtrack": {
      "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
      "effect": "fadeIn",
      "volume": 0
    },
    "background": "string",
    "fonts": [
      {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
      }
    ],
    "tracks": [
      {
        "clips": [
          {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "asset": {
              "type": "video",
              "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
              "prompt": "Slowly zoom out and orbit left around the object.",
              "model": "seedance-2.0-text-to-video",
              "options": {
                "resolution": "720p",
                "duration": "8",
                "generateAudio": true
              },
              "transcode": false,
              "trim": 2,
              "volume": 0.5,
              "volumeEffect": "none",
              "speed": 1,
              "crop": {
                "top": 0.15,
                "bottom": 0.15,
                "left": 1,
                "right": 1
              },
              "chromaKey": {
                "color": "#00b140",
                "threshold": 150,
                "halo": 100
              }
            },
            "start": 2,
            "length": 5,
            "fit": "cover",
            "scale": 0.5,
            "width": 800,
            "height": 600,
            "position": "top",
            "offset": {
              "x": 0.1,
              "y": -0.2
            },
            "transition": {
              "in": "none",
              "out": "none"
            },
            "effect": "zoomIn",
            "filter": "greyscale",
            "opacity": 0.5,
            "transform": {
              "rotate": {
                "angle": 45
              },
              "skew": {
                "x": 0.5,
                "y": 0.5
              },
              "flip": {
                "horizontal": true,
                "vertical": true
              }
            },
            "alias": "MY_VIDEO_CLIP"
          }
        ]
      }
    ],
    "cache": true
  },
  "output": {
    "format": "mp4",
    "resolution": "hd",
    "aspectRatio": "16:9",
    "size": {
      "width": 1200,
      "height": 800
    },
    "fps": 25,
    "scaleTo": "preview",
    "quality": "medium",
    "repeat": true,
    "mute": false,
    "range": {
      "start": 3,
      "length": 6
    },
    "poster": {
      "capture": 1
    },
    "thumbnail": {
      "capture": 1,
      "scale": 0.3
    },
    "destinations": [
      {
        "provider": "shotstack",
        "exclude": false
      }
    ]
  },
  "merge": [
    {
      "find": "NAME",
      "replace": "Jane"
    }
  ],
  "callback": "https://my-server.com/callback.php",
  "disk": "local",
  "instance": "s1"
}

An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format. Video assets are automatically preprocessed to fix common compatibility issues before rendering. You can control preprocessing behavior using the transcode flag on video assets.

Properties

Name	Type	Required	Restrictions	Description
timeline	Timeline	true	none	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.
output	Output	true	none	The output format, render range and type of media to generate. For all formats except `mp3`, either `resolution` or `size` (with both `width` and `height`) must be specified.
merge	[MergeField]	false	none	An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder `{{NAME}}` and replace it with the value `Jane`.
callback	string	false	none	An optional webhook callback URL used to receive status notifications when a render completes or fails. Notifications are also sent when a rendered video is sent to an output destination. See webhooks for more details.
disk	string	false	none	Notice: This option is now deprecated and will be removed. Disk types are handled automatically. Setting a disk type has no effect. The disk type to use for storing footage and assets for each render. See disk types for more details. `local` - optimized for high speed rendering with up to 512MB storage `mount` - optimized for larger file sizes and longer videos with 5GB for source footage and 512MB for output render
instance	string	false	none	The render instance type to use for processing the edit. `s1` - standard instance (default) `s2` - standard instance with more resources `a1` - accelerated instance for faster rendering

Enumerated Values

Property	Value
disk	local
disk	mount
instance	s1
instance	s2
instance	a1

Timeline

{
  "soundtrack": {
    "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
    "effect": "fadeIn",
    "volume": 0
  },
  "background": "string",
  "fonts": [
    {
      "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
    }
  ],
  "tracks": [
    {
      "clips": [
        {
          "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
          "asset": {
            "type": "video",
            "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
            "prompt": "Slowly zoom out and orbit left around the object.",
            "model": "seedance-2.0-text-to-video",
            "options": {
              "resolution": "720p",
              "duration": "8",
              "generateAudio": true
            },
            "transcode": false,
            "trim": 2,
            "volume": 0.5,
            "volumeEffect": "none",
            "speed": 1,
            "crop": {
              "top": 0.15,
              "bottom": 0.15,
              "left": 1,
              "right": 1
            },
            "chromaKey": {
              "color": "#00b140",
              "threshold": 150,
              "halo": 100
            }
          },
          "start": 2,
          "length": 5,
          "fit": "cover",
          "scale": 0.5,
          "width": 800,
          "height": 600,
          "position": "top",
          "offset": {
            "x": 0.1,
            "y": -0.2
          },
          "transition": {
            "in": "none",
            "out": "none"
          },
          "effect": "zoomIn",
          "filter": "greyscale",
          "opacity": 0.5,
          "transform": {
            "rotate": {
              "angle": 45
            },
            "skew": {
              "x": 0.5,
              "y": 0.5
            },
            "flip": {
              "horizontal": true,
              "vertical": true
            }
          },
          "alias": "MY_VIDEO_CLIP"
        }
      ]
    }
  ],
  "cache": true
}

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.

Properties

Name	Type	Required	Restrictions	Description
soundtrack	Soundtrack	false	none	A music or audio soundtrack file in mp3 format. Deprecated - use an AudioAsset clip on its own track instead.
background	string	false	none	A hexadecimal value for the timeline background colour. Defaults to #000000 (black).
fonts	[Font]	false	none	An array of custom fonts to be downloaded for use by the HTML assets.
tracks	[Track]	true	none	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.
cache	boolean	false	none	Disable the caching of ingested source footage and assets. See caching for more details.

Soundtrack

{
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
  "effect": "fadeIn",
  "volume": 0
}

Notice: The Soundtrack is deprecated, use an AudioAsset clip on its own track instead. This type continues to function; no behaviour change for existing integrations. A music or audio file in mp3 format that plays for the duration of the rendered video or the length of the audio file, which ever is shortest.

Properties

Name	Type	Required	Restrictions	Description
src	string	true	none	The URL of the mp3 audio file. The URL must be publicly accessible or include credentials.
effect	string	false	none	The effect to apply to the audio file `fadeIn` - fade volume in only `fadeOut` - fade volume out only `fadeInFadeOut` - fade volume in and out
volume	number	false	none	Set the volume for the soundtrack between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1).

Enumerated Values

Property	Value
effect	fadeIn
effect	fadeOut
effect	fadeInFadeOut

Font

{
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}

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 getting started guide for more details.

Properties

Name	Type	Required	Restrictions	Description
src	string	true	none	The URL of the font file. The URL must be publicly accessible or include credentials.

Track

{
  "clips": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "asset": {
        "type": "video",
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
        "prompt": "Slowly zoom out and orbit left around the object.",
        "model": "seedance-2.0-text-to-video",
        "options": {
          "resolution": "720p",
          "duration": "8",
          "generateAudio": true
        },
        "transcode": false,
        "trim": 2,
        "volume": 0.5,
        "volumeEffect": "none",
        "speed": 1,
        "crop": {
          "top": 0.15,
          "bottom": 0.15,
          "left": 1,
          "right": 1
        },
        "chromaKey": {
          "color": "#00b140",
          "threshold": 150,
          "halo": 100
        }
      },
      "start": 2,
      "length": 5,
      "fit": "cover",
      "scale": 0.5,
      "width": 800,
      "height": 600,
      "position": "top",
      "offset": {
        "x": 0.1,
        "y": -0.2
      },
      "transition": {
        "in": "none",
        "out": "none"
      },
      "effect": "zoomIn",
      "filter": "greyscale",
      "opacity": 0.5,
      "transform": {
        "rotate": {
          "angle": 45
        },
        "skew": {
          "x": 0.5,
          "y": 0.5
        },
        "flip": {
          "horizontal": true,
          "vertical": true
        }
      },
      "alias": "MY_VIDEO_CLIP"
    }
  ]
}

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.

Properties

Name	Type	Required	Restrictions	Description
clips	[Clip]	true	none	An array of Clips comprising of TitleClip, ImageClip or VideoClip.

Clip

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "asset": {
    "type": "video",
    "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
    "prompt": "Slowly zoom out and orbit left around the object.",
    "model": "seedance-2.0-text-to-video",
    "options": {
      "resolution": "720p",
      "duration": "8",
      "generateAudio": true
    },
    "transcode": false,
    "trim": 2,
    "volume": 0.5,
    "volumeEffect": "none",
    "speed": 1,
    "crop": {
      "top": 0.15,
      "bottom": 0.15,
      "left": 1,
      "right": 1
    },
    "chromaKey": {
      "color": "#00b140",
      "threshold": 150,
      "halo": 100
    }
  },
  "start": 2,
  "length": 5,
  "fit": "cover",
  "scale": 0.5,
  "width": 800,
  "height": 600,
  "position": "top",
  "offset": {
    "x": 0.1,
    "y": -0.2
  },
  "transition": {
    "in": "none",
    "out": "none"
  },
  "effect": "zoomIn",
  "filter": "greyscale",
  "opacity": 0.5,
  "transform": {
    "rotate": {
      "angle": 45
    },
    "skew": {
      "x": 0.5,
      "y": 0.5
    },
    "flip": {
      "horizontal": true,
      "vertical": true
    }
  },
  "alias": "MY_VIDEO_CLIP"
}

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.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	Optional client-generated identifier. Used by client SDKs (e.g. the Shotstack Studio SDK) to reference a clip across edits without relying on its position in the timeline. The render API does not use this field and it does not appear in render output.
asset	Asset	true	none	The type of asset to display for the duration of the Clip, i.e. a video clip or an image. Choose from one of the available asset types below.
start	any	true	none	The start position of the Clip on the timeline.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number	false	none	The start position of the Clip on the timeline, in seconds. For example, to start the Clip at 2 seconds, set the start value to 2.

xor

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	The start position using a smart clip property. Set to `auto` to automatically play the clip after the previous clip finishes. Use `alias://clip-name` to inherit the start time from the referenced clip.

continued

Name	Type	Required	Restrictions	Description
length	any	true	none	The duration the Clip should play for.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number	false	none	The duration the Clip should play for, in seconds. For example, to play the Clip for 5 seconds, set the length value to 5.

xor

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	The duration the Clip should play for using a smart clip property. Set to `auto` to play the Clip for the duration of the asset. Set to `end` to display or play the clip to the end of the timeline. Use `alias://clip-name` to inherit the length from the referenced clip.

continued

Name	Type	Required	Restrictions	Description
fit	string	false	none	Set how the asset should be scaled to fit the viewport using one of the following options: `crop` (default) - 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. `cover` - stretch the asset to fill the viewport without maintaining the aspect ratio. `contain` - fit the entire asset within the viewport while maintaining the original aspect ratio. `none` - preserves the original asset dimensions and does not apply any scaling.
scale	any	false	none	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. Use a number or an array of Tween objects to create a custom animation.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	Scale the asset to a fraction of the viewport size. For example, 0.5 will scale the asset to half the size of the viewport.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the scale of an asset over time.

continued

Name	Type	Required	Restrictions	Description
width	number(float)	false	none	Set the width of the clip bounding box in pixels. This constrains the width of the clip, overriding the default behavior where clips fill the viewport width.
height	number(float)	false	none	Set the height of the clip bounding box in pixels. This constrains the height of the clip, overriding the default behavior where clips fill the viewport height.
position	string	false	none	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. `top` - top (center) `topRight` - top right `right` - right (center) `bottomRight` - bottom right `bottom` - bottom (center) `bottomLeft` - bottom left `left` - left (center) `topLeft` - top left `center` - center
offset	Offset	false	none	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.
transition	Transition	false	none	In and out transitions for a clip - i.e. fade in and fade out
effect	string	false	none	A motion effect to apply to the Clip. `zoomIn` - slow zoom in `zoomOut` - slow zoom out `slideLeft` - slow slide (pan) left `slideRight` - slow slide (pan) right `slideUp` - slow slide (pan) up `slideDown` - slow slide (pan) down The motion effect speed can also be controlled by appending `Fast` or `Slow` to the effect, e.g. `zoomInFast` or `slideRightSlow`.
filter	string	false	none	A filter effect to apply to the Clip. `none` - no filter applied `blur` - blur the scene `boost` - boost contrast and saturation `contrast` - increase contrast `darken` - darken the scene `greyscale` - remove colour `lighten` - lighten the scene `muted` - reduce saturation and contrast `negative` - negative colors
opacity	any	false	none	Offset an asset on the horizontal axis (left or right). Use a number or an array of Tween objects to create a custom animation.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number	false	none	Sets the opacity of the Clip where 1 is opaque and 0 is transparent.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the opacity of an asset over time.

continued

Name	Type	Required	Restrictions	Description
transform	Transformation	false	none	A transformation lets you modify the visual properties of a clip. Available transformations are rotate, skew and flip. Transformations can be combined to create interesting new shapes and effects.
alias	string	false	none	A unique identifier for this clip that can be used to reference it from other clips using the `alias://` protocol in asset sources. This is useful for features like auto-captioning where a caption asset needs to reference the audio from another clip.

Enumerated Values

Property	Value
fit	cover
fit	contain
fit	crop
fit	none
position	top
position	topRight
position	right
position	bottomRight
position	bottom
position	bottomLeft
position	left
position	topLeft
position	center
effect	zoomIn
effect	zoomInSlow
effect	zoomInFast
effect	zoomOut
effect	zoomOutSlow
effect	zoomOutFast
effect	slideLeft
effect	slideLeftSlow
effect	slideLeftFast
effect	slideRight
effect	slideRightSlow
effect	slideRightFast
effect	slideUp
effect	slideUpSlow
effect	slideUpFast
effect	slideDown
effect	slideDownSlow
effect	slideDownFast
filter	none
filter	blur
filter	boost
filter	contrast
filter	darken
filter	greyscale
filter	lighten
filter	muted
filter	negative

Asset

{
  "type": "video",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
  "prompt": "Slowly zoom out and orbit left around the object.",
  "model": "seedance-2.0-text-to-video",
  "options": {
    "resolution": "720p",
    "duration": "8",
    "generateAudio": true
  },
  "transcode": false,
  "trim": 2,
  "volume": 0.5,
  "volumeEffect": "none",
  "speed": 1,
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 1,
    "right": 1
  },
  "chromaKey": {
    "color": "#00b140",
    "threshold": 150,
    "halo": 100
  }
}

The type of asset to display for the duration of the Clip, i.e. a video clip or an image. Choose from one of the available asset types below.

Properties

oneOf

Name	Type	Required	Restrictions	Description
anonymous	VideoAsset	false	none	The VideoAsset adds a video to a Clip. The video can be sourced from a URL (`src`), generated from a text prompt (`prompt`), or both. At least one of `src` or `prompt` must be provided. - Source URL: set `src` to the URL of an mp4 (or compatible) video file. - Generated: set `prompt` to describe the motion. Choose a generator with `model` and configure it with model-specific `options`. Models that animate a starting image take it as `options.inputSrc`; the default model generates from the prompt alone. The generated `src` is filled in automatically. - Both: `src` acts as a preview placeholder while `prompt` drives generation — the video is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

xor

Name	Type	Required	Restrictions	Description
anonymous	ImageAsset	false	none	The ImageAsset adds an image to a Clip. The image can be sourced from a URL (`src`), generated from a text prompt (`prompt`), or both. At least one of `src` or `prompt` must be provided. - Source URL: set `src` to the publicly accessible URL of a jpg or png file. - Generated: set `prompt` to describe the image. Choose a generator with `model` and configure it with model-specific `options`; the engine fills `src` in automatically. - Both: `src` acts as a preview placeholder while `prompt` drives generation — the image is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

xor

Name	Type	Required	Restrictions	Description
anonymous	TextAsset	false	none	Notice: The TextAsset is deprecated, use the RichTextAsset instead. This type continues to function; no behaviour change for existing integrations. The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom Fonts. You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported.

xor

Name	Type	Required	Restrictions	Description
anonymous	RichTextAsset	false	none	The RichTextAsset provides advanced text rendering with support for custom fonts, gradients, shadows, strokes, animations, and styling options. It offers more flexibility and visual effects than the basic TextAsset.

xor

Name	Type	Required	Restrictions	Description
anonymous	AudioAsset	false	none	The AudioAsset adds audio to a Clip. The audio can be sourced from a URL (`src`), generated from a text prompt (`prompt`), or both. At least one of `src` or `prompt` must be provided. - Source URL: set `src` to a publicly accessible audio URL (e.g. mp3). - Generated speech: set `prompt` to the spoken text and choose a text-to-speech `model`; set the voice via `options`. - Generated music or SFX: set `prompt` describing the sound and choose a music generation `model`. - Both: `src` acts as a preview placeholder while `prompt` drives generation — the audio is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache. - Use `model` to choose the generator and `options` to configure it. The generated `src` is filled in automatically.

xor

Name	Type	Required	Restrictions	Description
anonymous	LumaAsset	false	none	The LumaAsset is used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.

xor

Name	Type	Required	Restrictions	Description
anonymous	CaptionAsset	false	none	Notice: The CaptionAsset is deprecated, use the RichCaptionAsset instead. The CaptionAsset is used to add captions (subtitles) to a video. It uses a supplied SRT or VTT file which will be read and burnt to the video. Captions can be applied independently from a video or audio file for greater flexibility with styling and layout. For example you can scale, position or crop a video without modifying the captions. To sync captions with a video or audio file use a Video or Audio with matching start and end time.

xor

Name	Type	Required	Restrictions	Description
anonymous	RichCaptionAsset	false	none	The RichCaptionAsset provides word-level caption animations with rich-text styling. It supports karaoke-style highlighting, word-by-word animations, and advanced typography. Captions can be sourced from SRT/VTT/TTML subtitle files, from audio/video media URLs (auto-transcribed), or from alias references to other clips in the same timeline.

xor

Name	Type	Required	Restrictions	Description
anonymous	HtmlAsset	false	none	Notice: The HtmlAsset is deprecated, use the RichTextAsset instead. The HtmlAsset clip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box.

xor

Name	Type	Required	Restrictions	Description
anonymous	Html5Asset	false	none	The Html5Asset renders full HTML5/CSS3/JS.

xor

Name	Type	Required	Restrictions	Description
anonymous	TitleAsset	false	none	Notice: The TitleAsset is deprecated, use the RichTextAsset instead. The TitleAsset clip type lets you create video titles from a text string and apply styling and positioning.

xor

Name	Type	Required	Restrictions	Description
anonymous	ShapeAsset	false	none	The ShapeAsset is used to add shapes to a video. The shape can be styled with a fill and a stroke. You can manipulate properties such as rotation to create dynamic effects like a diamond shape or stripes.

xor

Name	Type	Required	Restrictions	Description
anonymous	SvgAsset	false	none	The SvgAsset is used to add scalable vector graphics (SVG) to a video using raw SVG markup. Supported elements: `,` , `,` , `,` , `` Automatically extracted from SVG markup: - Path data (converted to a single combined path) - Fill color (from `fill` attribute or `style`) - Stroke color and width (from attributes or `style`) - Dimensions (from `width`/`height` or `viewBox`) - Opacity (from `opacity` attribute) See W3C SVG 2 Specification for path data syntax.

xor

Name	Type	Required	Restrictions	Description
anonymous	TextToImageAsset	false	none	Notice: TextToImageAsset is deprecated. Use ImageAsset with `prompt` instead. This type continues to function and is internally rewritten to ImageAsset; no behaviour change for existing integrations. The TextToImageAsset lets you create a dynamic image from a text prompt.

xor

Name	Type	Required	Restrictions	Description
anonymous	ImageToVideoAsset	false	none	Notice: ImageToVideoAsset is deprecated. Use VideoAsset with `prompt`, a `model` that accepts a starting image, and that image in `options.inputSrc` — for example `seedance-2.0-image-to-video`. This type continues to function and is internally rewritten to VideoAsset; no behaviour change for existing integrations. The ImageToVideoAsset lets you create a video from an image and a text prompt.

xor

Name	Type	Required	Restrictions	Description
anonymous	TextToSpeechAsset	false	none	Notice: TextToSpeechAsset is deprecated. Use AudioAsset with `prompt` (the spoken text) and `voice` instead. This type continues to function and is internally rewritten to AudioAsset; no behaviour change for existing integrations. The TextToSpeechAsset lets you generate a voice over from text using a text-to-speech service. The generated audio can be trimmed, faded and have its volume and speed adjusted using the same properties available on the AudioAsset.

VideoAsset

{
  "type": "video",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
  "prompt": "Slowly zoom out and orbit left around the object.",
  "model": "seedance-2.0-text-to-video",
  "options": {
    "resolution": "720p",
    "duration": "8",
    "generateAudio": true
  },
  "transcode": false,
  "trim": 2,
  "volume": 0.5,
  "volumeEffect": "none",
  "speed": 1,
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 1,
    "right": 1
  },
  "chromaKey": {
    "color": "#00b140",
    "threshold": 150,
    "halo": 100
  }
}

The VideoAsset adds a video to a Clip. The video can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided.

Source URL: set src to the URL of an mp4 (or compatible) video file.
Generated: set prompt to describe the motion. Choose a generator with model and configure it with model-specific options. Models that animate a starting image take it as options.inputSrc; the default model generates from the prompt alone. The generated src is filled in automatically.
Both: src acts as a preview placeholder while prompt drives generation — the video is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `video` for videos.
src	string	false	none	The video source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the video is regenerated from the prompt at render time.
prompt	string	false	none	A text prompt to generate the video from. The engine generates a video at render time and fills `src` automatically; an existing `src` is treated as a preview placeholder and replaced. Use `model` to choose the generator and `options` to configure it. A starting image goes in `options.inputSrc`, on the models that accept one.
model	string	false	none	The generation model to use when `prompt` is set (e.g. `seedance-2.0-text-to-video`). Defaults to `seedance-2.0-text-to-video` if omitted. `GET /models` lists what is available and the options each accepts.
options	object	false	none	Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.
transcode	boolean	false	none	Set to `true` to force re-encoding of the video during preprocessing. This can help resolve compatibility issues, fix rotation problems, synchronize audio, or convert formats. The video will be processed to ensure optimal compatibility with the rendering engine.
trim	number	false	none	The start trim point of the video clip, in seconds (defaults to 0). Videos will start from the in trim point. The video will play until the file ends or the Clip length is reached.
volume	any	false	none	Set the volume of the video clip. Use a number or an array of Tween objects to create custom volume transitions.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	The volume level for the video clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1).

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time.

continued

Name	Type	Required	Restrictions	Description
volumeEffect	string	false	none	Preset volume effects to apply to the video asset `fadeIn` - fade volume in only `fadeOut` - fade volume out only `fadeInFadeOut` - fade volume in and out
speed	number(float)	false	none	Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire video (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire video (i.e. original length / 2).
crop	Crop	false	none	Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.
chromaKey	ChromaKey	false	none	Chroma key is a technique that replaces a specific color in a video with a different background image or video, enabling seamless integration of diverse environments. Commonly used for green screen and blue screen effects.

Enumerated Values

Property	Value
type	video
volumeEffect	none
volumeEffect	fadeIn
volumeEffect	fadeOut
volumeEffect	fadeInFadeOut

ImageAsset

{
  "type": "image",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
  "prompt": "A serene landscape with a crystal-clear mountain lake at sunrise.",
  "model": "flux-schnell",
  "options": {
    "resolution": "1K",
    "aspectRatio": "16:9"
  },
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 1,
    "right": 1
  }
}

The ImageAsset adds an image to a Clip. The image can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided.

Source URL: set src to the publicly accessible URL of a jpg or png file.
Generated: set prompt to describe the image. Choose a generator with model and configure it with model-specific options; the engine fills src in automatically.
Both: src acts as a preview placeholder while prompt drives generation — the image is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `image` for images.
src	string	false	none	The image source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the image is regenerated from the prompt at render time.
prompt	string	false	none	A text prompt to generate the image from. The engine generates an image at render time and fills `src` automatically; an existing `src` is treated as a preview placeholder and replaced. Use `model` to choose the generator and `options` to configure it.
model	string	false	none	The generation model to use when `prompt` is set (e.g. `flux-schnell`, `nano-banana-2`). Defaults to `nano-banana-2` if omitted. Each model's available options are defined by the model registry.
options	object	false	none	Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.
crop	Crop	false	none	Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.

Enumerated Values

Property	Value
type	image

TextAsset

{
  "type": "text",
  "text": "Hello World",
  "width": 400,
  "height": 200,
  "font": {
    "family": "Open Sans",
    "color": "#ffffff",
    "opacity": 0.8,
    "size": 24,
    "weight": 400,
    "lineHeight": 0.85
  },
  "background": {
    "color": "#000000",
    "opacity": 0.8,
    "padding": 10,
    "borderRadius": 5,
    "wrap": false
  },
  "alignment": {
    "horizontal": "center",
    "vertical": "center"
  },
  "stroke": {
    "width": 2,
    "color": "#000000"
  },
  "animation": {
    "preset": "typewriter",
    "duration": 2
  },
  "ellipsis": "..."
}

Notice: The TextAsset is deprecated, use the RichTextAsset instead. This type continues to function; no behaviour change for existing integrations.

The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom Fonts. You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `text` for text.
text	string	true	none	The text string to display.
width	integer	false	none	Set the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box.
height	integer	false	none	Set the width of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the height of the bounding box.
font	TextFont	false	none	Font styling properties.
background	TextBackground	false	none	Background styling properties.
alignment	TextAlignment	false	none	Alignment properties.
stroke	object	false	none	Text stroke (outline) properties.
» width	number	false	none	The width of the stroke in pixels.
» color	string	false	none	The stroke color using hexadecimal color notation.
animation	object	false	none	Animation properties for text entrance effects.
» preset	string	true	none	The animation preset to apply. `typewriter` - typewriter effect where characters appear one at a time
» duration	number	false	none	The duration of the animation in seconds.
ellipsis	string	false	none	The string to display when text overflows its bounding box. Set to an ellipsis character or custom string to indicate truncated text.

Enumerated Values

Property	Value
type	text
preset	typewriter

RichTextAsset

{
  "type": "rich-text",
  "text": "Hello World",
  "font": {
    "family": "Open Sans",
    "size": 48,
    "weight": "400",
    "style": "italic",
    "color": "#ff0000",
    "opacity": 0.9,
    "background": "#000000",
    "stroke": {
      "width": 2,
      "color": "#000000",
      "opacity": 0.8
    }
  },
  "style": {
    "letterSpacing": 2,
    "wordSpacing": 10,
    "lineHeight": 1.5,
    "textTransform": "uppercase",
    "textDecoration": "underline",
    "gradient": {
      "type": "linear",
      "angle": 45,
      "stops": [
        {
          "offset": 0.5,
          "color": "#ff0000"
        },
        {
          "offset": 0.5,
          "color": "#ff0000"
        }
      ]
    }
  },
  "stroke": {
    "width": 2,
    "color": "#000000",
    "opacity": 0.8
  },
  "shadow": {
    "offsetX": 4,
    "offsetY": 4,
    "blur": 8,
    "color": "#000000",
    "opacity": 0.7
  },
  "background": {
    "color": "#000000",
    "opacity": 0.5,
    "borderRadius": 10,
    "wrap": true,
    "padding": 12
  },
  "border": {
    "width": 2,
    "color": "#ff0000",
    "opacity": 0.8,
    "radius": 10
  },
  "padding": 10,
  "align": {
    "horizontal": "center",
    "vertical": "middle"
  },
  "animation": {
    "preset": "shift",
    "duration": 2,
    "style": "character",
    "direction": "up"
  }
}

The RichTextAsset provides advanced text rendering with support for custom fonts, gradients, shadows, strokes, animations, and styling options. It offers more flexibility and visual effects than the basic TextAsset.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `rich-text` for rich text.
text	string	true	none	The text string to display. Maximum 5000 characters.
font	RichTextFont	false	none	Font styling properties.
style	RichTextStyle	false	none	Text style properties including spacing, line height, and transformations.
stroke	RichTextStroke	false	none	Text stroke (outline) properties.
shadow	RichTextShadow	false	none	Text shadow properties.
background	RichTextBackground	false	none	Background styling properties for the text bounding box.
border	object	false	none	Border styling properties for the text bounding box.
» width	number	false	none	The width of the border in pixels. Must be 0 or greater.
» color	string	false	none	The border color using hexadecimal color notation.
» opacity	number	false	none	The opacity of the border where 1 is opaque and 0 is transparent.
» radius	number	false	none	The border radius in pixels for rounded corners. Must be 0 or greater.
padding	any	false	none	Padding inside the text bounding box. Can be a single number (applied to all sides) or an object with individual sides.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number	false	none	Padding in pixels applied to all sides.

xor

Name	Type	Required	Restrictions	Description
» anonymous	object	false	none	Padding properties for individual sides of the text bounding box.
»» top	number	false	none	Top padding in pixels.
»» right	number	false	none	Right padding in pixels.
»» bottom	number	false	none	Bottom padding in pixels.
»» left	number	false	none	Left padding in pixels.

continued

Name	Type	Required	Restrictions	Description
align	RichTextAlignment	false	none	Text alignment properties (horizontal and vertical).
animation	RichTextAnimation	false	none	Animation properties for text entrance effects.

Enumerated Values

Property	Value
type	rich-text

AudioAsset

{
  "type": "audio",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/sound.mp3",
  "prompt": "Welcome to today's broadcast.",
  "model": "polly-neural",
  "options": {
    "voice": "Matthew",
    "language": "en-US"
  },
  "trim": 0,
  "volume": 0.5,
  "speed": 1,
  "effect": "none"
}

The AudioAsset adds audio to a Clip. The audio can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided.

Source URL: set src to a publicly accessible audio URL (e.g. mp3).
Generated speech: set prompt to the spoken text and choose a text-to-speech model; set the voice via options.
Generated music or SFX: set prompt describing the sound and choose a music generation model.
Both: src acts as a preview placeholder while prompt drives generation — the audio is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.
Use model to choose the generator and options to configure it. The generated src is filled in automatically.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `audio` for audio assets.
src	string	false	none	The audio source URL. The URL must be publicly accessible or include credentials. When `prompt` is also set, `src` serves as a preview placeholder and the audio is regenerated from the prompt at render time.
prompt	string	false	none	A text prompt. For text-to-speech models the prompt is the spoken text; for music models it describes the sound to generate. The generated `src` is filled in automatically; an existing `src` is treated as a preview placeholder and replaced.
model	string	false	none	The generation model to use when `prompt` is set (e.g. `polly-neural`, `elevenlabs-tts`, `elevenlabs-music`). Defaults to `elevenlabs-tts` (with a default voice) if omitted. Each model's available options are defined by the model registry.
options	object	false	none	Model-specific generation settings. Valid keys and values depend on the chosen `model` and are defined by the model registry. Omitted options use the model's defaults. Unknown or invalid options are rejected.
trim	number	false	none	The start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the in trim point. The audio will play until the file ends or the Clip length is reached.
volume	any	false	none	Set the volume of the audio clip. Use a number or an array of Tween objects to create custom volume transitions.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	The volume level for the audio clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1).

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time.

continued

Name	Type	Required	Restrictions	Description
speed	number(float)	false	none	Adjust the playback speed of the audio clip between 0 (paused) and 10 (10x normal speed), where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire audio (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire audio (i.e. original length / 2).
effect	string	false	none	The effect to apply to the audio asset `fadeIn` - fade volume in only `fadeOut` - fade volume out only `fadeInFadeOut` - fade volume in and out

Enumerated Values

Property	Value
type	audio
effect	none
effect	fadeIn
effect	fadeOut
effect	fadeInFadeOut

ShapeAsset

{
  "type": "shape",
  "shape": "rectangle",
  "width": 800,
  "height": 800,
  "fill": {
    "color": "#ffffff",
    "opacity": 1
  },
  "stroke": {
    "color": "#000000",
    "width": 0.8
  },
  "rectangle": {
    "width": 800,
    "height": 800,
    "cornerRadius": 20
  },
  "circle": {
    "radius": 800
  },
  "line": {
    "length": 100,
    "thickness": 4
  }
}

The ShapeAsset is used to add shapes to a video. The shape can be styled with a fill and a stroke. You can manipulate properties such as rotation to create dynamic effects like a diamond shape or stripes.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `shape` for shape.
shape	string	true	none	The shape to display.
width	integer	false	none	Sets the width of the bounding box in pixels. This value should be larger than the shape's width. If omitted, the entire viewport width and height will be used.
height	integer	false	none	Sets the height of the bounding box in pixels. This value should be larger than the shape's height. If omitted, the entire viewport width and height will be used.
fill	object	false	none	Specifies the fill style of the shape.
» color	string	false	none	The color of the fill using hexadecimal color notation.
» opacity	number	false	none	The opacity of the fill where 1 is opaque and 0 is transparent.
stroke	object	false	none	Specifies the stroke style of the shape.
» color	string	false	none	The stroke color of the font using hexadecimal color notation.
» width	number	false	none	The width of the stroke in pixels.
rectangle	object	false	none	Configuration settings for the rectangle shape. Required when `shape` is set to `rectangle`.
» width	integer	true	none	Set the width of the rectangle shape in pixels.
» height	integer	true	none	Set the height of the rectangle shape in pixels.
» cornerRadius	integer	false	none	Set the corner radius of the rectangle shape.
circle	object	false	none	Configuration settings for the circle shape. Required when `shape` is set to `circle`.
» radius	integer	true	none	Set the radius of the circle shape in pixels.
line	object	false	none	Configuration settings for the line shape. Required when `shape` is set to `line`.
» length	integer	true	none	Set the length of the line shape in pixels.
» thickness	integer	true	none	Set the thickness of the line in pixels.

Enumerated Values

Property	Value
type	shape
shape	rectangle
shape	circle
shape	line

LumaAsset

{
  "type": "luma",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/mask.mp4",
  "trim": 0
}

The LumaAsset is used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `luma` for luma mattes.
src	string	true	none	The luma matte source URL. The URL must be publicly accessible or include credentials.
trim	number	false	none	The start trim point of the luma matte clip, in seconds (defaults to 0). Videos will start from the in trim point. A luma matte video will play until the file ends or the Clip length is reached.

Enumerated Values

Property	Value
type	luma

CaptionAsset

{
  "type": "caption",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/captions.srt",
  "font": {
    "family": "Open Sans",
    "color": "#ffffff",
    "opacity": 0.8,
    "size": 24,
    "lineHeight": 0.85,
    "stroke": "#ff6600",
    "strokeWidth": 0.8
  },
  "background": {
    "color": "#000000",
    "opacity": 0.4,
    "padding": 30,
    "borderRadius": 18
  },
  "margin": {
    "top": 0.25,
    "left": 0.05,
    "right": 0.45
  },
  "trim": 2,
  "speed": 1
}

Notice: The CaptionAsset is deprecated, use the RichCaptionAsset instead.

The CaptionAsset is used to add captions (subtitles) to a video. It uses a supplied SRT or VTT file which will be read and burnt to the video.

Captions can be applied independently from a video or audio file for greater flexibility with styling and layout. For example you can scale, position or crop a video without modifying the captions.

To sync captions with a video or audio file use a Video or Audio with matching start and end time.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `caption` for captions.
src	string	true	none	The URL to an SRT or VTT subtitles file, or an alias reference to auto-generate captions from an audio or video clip. For file URLs, the URL must be publicly accessible or include credentials. For auto-captioning, use the format `alias://clip-name` where clip-name is the alias of an audio, video, or text-to-speech clip. The system will automatically transcribe the audio and detect the language.
font	CaptionFont	false	none	Font styling properties.
background	CaptionBackground	false	none	Background styling properties.
margin	CaptionMargin	false	none	Margin properties.
trim	number	false	none	The start trim point of the captions, in seconds (defaults to 0). Remove the trim length from the start of the captions and allow it to be synced with video or audio. The captions will play until the file ends or the Clip length is reached.
speed	number(float)	false	none	Adjust the playback speed of the captions between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire captions (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire captions (i.e. original length / 2).

Enumerated Values

Property	Value
type	caption

RichCaptionAsset

{
  "type": "rich-caption",
  "src": "alias://audio",
  "font": {
    "family": "Roboto",
    "size": 48,
    "weight": "400",
    "style": "italic",
    "color": "#ffffff",
    "opacity": 0.9,
    "background": "#000000"
  },
  "style": {
    "letterSpacing": 2,
    "lineHeight": 1.5,
    "textTransform": "uppercase",
    "size": 120,
    "textDecoration": "underline",
    "gradient": {
      "type": "linear",
      "angle": 45,
      "stops": [
        {
          "offset": 0.5,
          "color": "#ff0000"
        },
        {
          "offset": 0.5,
          "color": "#ff0000"
        }
      ]
    }
  },
  "stroke": {
    "width": 2,
    "color": "#000000",
    "opacity": 0.8
  },
  "shadow": {
    "offsetX": 4,
    "offsetY": 4,
    "blur": 8,
    "color": "#000000",
    "opacity": 0.7
  },
  "background": {
    "color": "#000000",
    "opacity": 0.5,
    "borderRadius": 10,
    "wrap": true,
    "padding": 12
  },
  "border": {
    "width": 2,
    "color": "#ff0000",
    "opacity": 0.8,
    "radius": 10
  },
  "padding": 10,
  "align": {
    "horizontal": "center",
    "vertical": "middle"
  },
  "active": {
    "font": {
      "family": "Roboto",
      "weight": "400",
      "color": "#C96741",
      "background": "#000000",
      "opacity": 1,
      "size": 120,
      "textDecoration": "underline"
    },
    "stroke": {
      "width": 2,
      "color": "#000000",
      "opacity": 0.8
    },
    "shadow": {
      "offsetX": 4,
      "offsetY": 4,
      "blur": 8,
      "color": "#000000",
      "opacity": 0.7
    }
  },
  "animation": {
    "style": "highlight",
    "direction": "up"
  }
}

The RichCaptionAsset provides word-level caption animations with rich-text styling. It supports karaoke-style highlighting, word-by-word animations, and advanced typography. Captions can be sourced from SRT/VTT/TTML subtitle files, from audio/video media URLs (auto-transcribed), or from alias references to other clips in the same timeline.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `rich-caption` for rich captions.
src	string	true	none	Source for the caption words. Accepts three formats: (1) the URL to a subtitle file (`.srt`, `.vtt`, `.ttml`, or `.dfxp`) which is parsed directly; (2) the URL to an audio or video media file (`.mp4`, `.mov`, `.webm`, `.mp3`, `.wav`, `.m4a`, `.flac`, `.aac`, `.ogg`, and related formats) which is auto-transcribed; (3) an alias reference in the form `alias://clip-name` where `clip-name` is the alias of another audio, video, or text-to-speech clip in the same timeline — the referenced clip's source is auto-transcribed. For file URLs, the URL must be publicly accessible or include credentials. Content is classified at runtime and unsupported content types (HTML, PDF, images, archives) are rejected with a structured error.
font	object	false	none	Font styling properties for inactive words.
» family	string	false	none	The font family name. This must be the Family name embedded in the font, i.e. "Roboto".
» size	integer	false	none	The size of the font in pixels (px). Must be between 1 and 500.
» weight	any	false	none	The weight of the font. Can be a number (100-900) or a string ('normal', 'bold', etc.). 100 is lightest, 900 is heaviest (boldest).
» style	string	false	none	The font style.
» color	string	false	none	The text color using hexadecimal color notation.
» opacity	number	false	none	The opacity of the text where 1 is opaque and 0 is transparent.
» background	string	false	none	The background color behind the text using hexadecimal color notation.
style	object	false	none	Text style properties including spacing, line height, and transformations.
» letterSpacing	number	false	none	Additional spacing between letters in pixels. Can be negative for tighter spacing.
» lineHeight	number	false	none	The line height as a multiplier of the font size. Must be between 0 and 10.
» textTransform	string	false	none	Text transformation to apply.
» size	number	false	none	The font size in pixels. Can be used as an alternative to font.size.
» textDecoration	string	false	none	Text decoration to apply.
» gradient	RichTextGradient	false	none	Gradient fill for text instead of solid color.
stroke	RichTextStroke	false	none	Text stroke (outline) properties for inactive words.
shadow	RichTextShadow	false	none	Text shadow properties.
background	RichTextBackground	false	none	Background styling properties for the caption bounding box.
border	RichTextAsset/properties/border	false	none	Border styling properties for the caption bounding box.
padding	any	false	none	Padding inside the caption bounding box. Can be a single number (applied to all sides) or an object with individual sides.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number	false	none	Padding in pixels applied to all sides.

xor

Name	Type	Required	Restrictions	Description
» anonymous	RichTextAsset/properties/padding/oneOf/1	false	none	Padding properties for individual sides of the text bounding box.

continued

Name	Type	Required	Restrictions	Description
align	RichTextAlignment	false	none	Text alignment properties (horizontal and vertical).
active	RichCaptionActive	false	none	Styling properties for the active/highlighted word. These override the base styling when a word is being spoken.
animation	RichCaptionAnimation	false	none	Word-level animation properties controlling how words are highlighted or revealed.

Enumerated Values

Property	Value
type	rich-caption
style	normal
style	italic
textTransform	none
textTransform	uppercase
textTransform	lowercase
textTransform	capitalize
textDecoration	none
textDecoration	underline
textDecoration	line-through

RichCaptionActiveFont

{
  "family": "Roboto",
  "weight": "400",
  "color": "#C96741",
  "background": "#000000",
  "opacity": 1,
  "size": 120,
  "textDecoration": "underline"
}

Font properties for the active/highlighted word.

Properties

Name	Type	Required	Restrictions	Description
family	string	false	none	The font family for the active word. Inherits from the base font.family when not set.
weight	any	false	none	The weight of the font for the active word. Can be a number (100-900) or a string. Inherits from the base font.weight when not set.
color	string	false	none	The active word color using hexadecimal color notation.
background	string	false	none	The background color behind the active word using hexadecimal color notation.
opacity	number	false	none	The opacity of the active word where 1 is opaque and 0 is transparent.
size	number	false	none	The font size of the active word in pixels.
textDecoration	string	false	none	Text decoration to apply to the active word.

Enumerated Values

Property	Value
textDecoration	none
textDecoration	underline
textDecoration	line-through

RichCaptionActive

{
  "font": {
    "family": "Roboto",
    "weight": "400",
    "color": "#C96741",
    "background": "#000000",
    "opacity": 1,
    "size": 120,
    "textDecoration": "underline"
  },
  "stroke": {
    "width": 2,
    "color": "#000000",
    "opacity": 0.8
  },
  "shadow": {
    "offsetX": 4,
    "offsetY": 4,
    "blur": 8,
    "color": "#000000",
    "opacity": 0.7
  }
}

Styling properties for the active/highlighted word.

Properties

Name	Type	Required	Restrictions	Description
font	RichCaptionActiveFont	false	none	Font properties for the active word.
stroke	any	false	none	Stroke properties for the active word. Set to "none" to explicitly remove the base stroke on the active word.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	RichTextStroke	false	none	Text stroke (outline) properties.

xor

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

continued

Name	Type	Required	Restrictions	Description
shadow	any	false	none	Shadow properties for the active word. Set to "none" to explicitly remove the base shadow on the active word.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	RichTextShadow	false	none	Text shadow properties.

xor

Name	Type	Required	Restrictions	Description
» anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	none
anonymous	none

RichCaptionAnimation

{
  "style": "highlight",
  "direction": "up"
}

Word-level animation properties for caption effects.

Properties

Name	Type	Required	Restrictions	Description
style	string	true	none	The animation style to apply to words: `karaoke` - Word-by-word color fill as spoken (shows all words, highlights active) `highlight` - Word changes to active color when spoken (shows all words) `pop` - Each word scales up when active `fade` - Gradual opacity transition per word `slide` - Words slide in from a direction `bounce` - Spring animation on word appearance `typewriter` - Words appear one by one and stay visible `none` - No animation, all words visible immediately
direction	string	false	none	Direction for directional animations (slide). Only applicable when style is `slide`.

Enumerated Values

Property	Value
style	karaoke
style	highlight
style	pop
style	fade
style	slide
style	bounce
style	typewriter
style	none
direction	left
direction	right
direction	up
direction	down

TextToImageAsset

{
  "type": "text-to-image",
  "prompt": "A serene landscape featuring a crystal-clear mountain lake at sunrise. The water reflects the pink and orange sky like a mirror. In the foreground, a majestic pine tree stands tall, its branches framing the view. Snow-capped peaks rise in the distance, their edges softened by a light morning mist. A pair of deer drink from the lake's edge, creating gentle ripples on the otherwise still surface.",
  "width": 512,
  "height": 512,
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 1,
    "right": 1
  }
}

Notice: TextToImageAsset is deprecated. Use ImageAsset with prompt instead. This type continues to function and is internally rewritten to ImageAsset; no behaviour change for existing integrations.

The TextToImageAsset lets you create a dynamic image from a text prompt.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset to generate - set to `text-to-image` for text-to-image.
prompt	string	true	none	The text prompt to generate an image from.
width	integer	false	none	The width of the image in pixels.
height	integer	false	none	The height of the image in pixels.
crop	Crop	false	none	Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.

Enumerated Values

Property	Value
type	text-to-image

ImageToVideoAsset

{
  "type": "image-to-video",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
  "prompt": "Slowly zoom out and orbit left around the object.",
  "aspectRatio": "16:9",
  "speed": 1,
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 1,
    "right": 1
  }
}

Notice: ImageToVideoAsset is deprecated. Use VideoAsset with prompt, a model that accepts a starting image, and that image in options.inputSrc — for example seedance-2.0-image-to-video. This type continues to function and is internally rewritten to VideoAsset; no behaviour change for existing integrations.

The ImageToVideoAsset lets you create a video from an image and a text prompt.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset to generate - set to `image-to-video` for image-to-video.
src	string	true	none	The image source URL. The URL must be publicly accessible or include credentials.
prompt	string	false	none	The instructions for modifying the image into a video sequence.
aspectRatio	string	false	none	The aspect ratio (shape) of the video output.
speed	number(float)	false	none	Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire video (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire video (i.e. original length / 2).
crop	Crop	false	none	Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.

Enumerated Values

Property	Value
type	image-to-video
aspectRatio	1:1
aspectRatio	4:3
aspectRatio	16:9
aspectRatio	9:16
aspectRatio	3:4
aspectRatio	21:9
aspectRatio	9:21

TextToSpeechAsset

{
  "type": "text-to-speech",
  "text": "This is a text to speech example generated by Shotstack",
  "voice": "Matthew",
  "language": "en-US",
  "newscaster": false,
  "trim": 0,
  "volume": 0.5,
  "speed": 1,
  "effect": "none"
}

Notice: TextToSpeechAsset is deprecated. Use AudioAsset with prompt (the spoken text) and voice instead. This type continues to function and is internally rewritten to AudioAsset; no behaviour change for existing integrations.

The TextToSpeechAsset lets you generate a voice over from text using a text-to-speech service. The generated audio can be trimmed, faded and have its volume and speed adjusted using the same properties available on the AudioAsset.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `text-to-speech` for text-to-speech.
text	string	true	none	The text to convert to speech.
voice	string	true	none	The voice to use for the text-to-speech conversion.
language	string	false	none	The language code for the text-to-speech conversion.
newscaster	boolean	false	none	Set the voice to newscaster mode.
trim	number	false	none	The start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the trim point. The audio will play until the file ends or the Clip length is reached.
volume	any	false	none	Set the volume of the audio clip. Use a number or an array of Tween objects to create custom volume transitions.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	The volume level for the audio clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1).

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time.

continued

Name	Type	Required	Restrictions	Description
speed	number(float)	false	none	Adjust the playback speed of the audio clip between 0 (paused) and 10 (10x normal speed), where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length.
effect	string	false	none	The effect to apply to the audio asset `fadeIn` - fade volume in only `fadeOut` - fade volume out only `fadeInFadeOut` - fade volume in and out

Enumerated Values

Property	Value
type	text-to-speech
effect	none
effect	fadeIn
effect	fadeOut
effect	fadeInFadeOut

HtmlAsset

{
  "type": "html",
  "html": "<p>Hello <b>World</b></p>",
  "css": "p { color: #ffffff; } b { color: #ffff00; }",
  "width": 400,
  "height": 200,
  "background": "string",
  "position": "top"
}

Notice: The HtmlAsset is deprecated, use the RichTextAsset instead.

The HtmlAsset clip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `html` for HTML.
html	string	true	none	The HTML text string. See list of supported HTML tags.
css	string	false	none	The CSS text string to apply styling to the HTML. See list of support CSS properties.
width	integer	false	none	Set the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box.
height	integer	false	none	Set the width of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the height of the bounding box.
background	string	false	none	Apply a background color behind the HTML bounding box using. Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency.
position	string	false	none	Place the HTML in one of nine predefined positions within the HTML area. `top` - top (center) `topRight` - top right `right` - right (center) `bottomRight` - bottom right `bottom` - bottom (center) `bottomLeft` - bottom left `left` - left (center) `topLeft` - top left `center` - center

Enumerated Values

Property	Value
type	html
position	top
position	topRight
position	right
position	bottomRight
position	bottom
position	bottomLeft
position	left
position	topLeft
position	center

Html5Asset

{
  "type": "html5",
  "html": "<div class="card"><h1>{{title}}</h1></div>",
  "css": ".card { font-family: 'Inter'; padding: 32px; }",
  "js": "gsap.to('.card', { x: 200, duration: 1 });"
}

The Html5Asset renders full HTML5/CSS3/JS.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `html5` for HTML5/CSS3/JS.
html	string	true	none	The HTML markup for the asset. Max 1,000,000 characters.
css	string	false	none	The CSS string applied to the HTML. Max 500,000 characters.
js	string	false	none	Optional JavaScript. Use for chart libraries, animations, or DOM manipulation. `gsap`, `d3`, `anime` and `lottie` are always available. CSS animations, transitions, and `Element.animate()` are also captured automatically. Max 500,000 characters.

Enumerated Values

Property	Value
type	html5

TitleAsset

{
  "type": "title",
  "text": "Hello World",
  "style": "minimal",
  "color": "string",
  "size": "xx-small",
  "background": "#000000",
  "position": "top",
  "offset": {
    "x": 0.1,
    "y": -0.2
  }
}

Notice: The TitleAsset is deprecated, use the RichTextAsset instead.

The TitleAsset clip type lets you create video titles from a text string and apply styling and positioning.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to `title` for titles.
text	string	true	none	The title text string - i.e. "My Title".
style	string	false	none	Uses a preset to apply font properties and styling to the title. `minimal` `blockbuster` `vogue` `sketchy` `skinny` `chunk` `chunkLight` `marker` `future` `subtitle`
color	string	false	none	Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency.
size	string	false	none	Set the relative size of the text using predefined sizes from xx-small to xx-large. `xx-small` `x-small` `small` `medium` `large` `x-large` `xx-large`
background	string	false	none	Apply a background color behind the text. Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency. Omit to use transparent background.
position	string	false	none	Place the title in one of nine predefined positions of the viewport. `top` - top (center) `topRight` - top right `right` - right (center) `bottomRight` - bottom right `bottom` - bottom (center) `bottomLeft` - bottom left `left` - left (center) `topLeft` - top left `center` - center
offset	Offset	false	none	Offset the location of the title relative to its position on the screen.

Enumerated Values

Property	Value
type	title
style	minimal
style	blockbuster
style	vogue
style	sketchy
style	skinny
style	chunk
style	chunkLight
style	marker
style	future
style	subtitle
size	xx-small
size	x-small
size	small
size	medium
size	large
size	x-large
size	xx-large
position	top
position	topRight
position	right
position	bottomRight
position	bottom
position	bottomLeft
position	left
position	topLeft
position	center

SvgAsset

{
  "type": "svg",
  "src": ""
}

The SvgAsset is used to add scalable vector graphics (SVG) to a video using raw SVG markup.

Supported elements: , , , , , , ``

Automatically extracted from SVG markup:

Path data (converted to a single combined path)
Fill color (from fill attribute or style)
Stroke color and width (from attributes or style)
Dimensions (from width/height or viewBox)
Opacity (from opacity attribute)

See W3C SVG 2 Specification for path data syntax.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The asset type - set to `svg` for SVG assets.
src	string	true	none	Raw SVG markup string. The SVG must contain valid SVG elements. The shape, fill, stroke, dimensions and opacity are automatically extracted from the SVG content.

Enumerated Values

Property	Value
type	svg

Transition

{
  "in": "none",
  "out": "none"
}

In and out transitions for a clip - i.e. fade in and fade out

Properties

Name	Type	Required	Restrictions	Description
in	string	false	none	The transition in. Available transitions are: `fade` - fade in `reveal` - reveal from left to right `wipeLeft` - fade across screen to the left `wipeRight` - fade across screen to the right `slideLeft` - move slightly left and fade in `slideRight` - move slightly right and fade in `slideUp` - move slightly up and fade in `slideDown` - move slightly down and fade in `carouselLeft` - slide in from right to left `carouselRight` - slide in from left to right `carouselUp` - slide in from bottom to top `carouselDown` - slide in from top to bottom `shuffleTopRight` - rotate in from top right `shuffleRightTop` - rotate in from right top `shuffleRightBottom` - rotate in from right bottom `shuffleBottomRight` - rotate in from bottom right `shuffleBottomLeft` - rotate in from bottom left `shuffleLeftBottom` - rotate in from left bottom `shuffleLeftTop` - rotate in from left top `shuffleTopLeft` - rotate in from top left `zoom` - fast zoom in The transition speed can also be controlled by appending `Fast` or `Slow` to the transition, e.g. `fadeFast` or `CarouselLeftSlow`.
out	string	false	none	The transition out. Available transitions are: `fade` - fade out `reveal` - reveal from right to left `wipeLeft` - fade across screen to the left `wipeRight` - fade across screen to the right `slideLeft` - move slightly left and fade out `slideRight` - move slightly right and fade out `slideUp` - move slightly up and fade out `slideDown` - move slightly down and fade out `carouselLeft` - slide out from right to left `carouselRight` - slide out from left to right `carouselUp` - slide out from bottom to top `carouselDown` - slide out from top to bottom `shuffleTopRight` - rotate out from top right `shuffleRightTop` - rotate out from right top `shuffleRightBottom` - rotate out from right bottom `shuffleBottomRight` - rotate out from bottom right `shuffleBottomLeft` - rotate out from bottom left `shuffleLeftBottom` - rotate out from left bottom `shuffleLeftTop` - rotate out from left top `shuffleTopLeft` - rotate out from top left `zoom` - fast zoom out The transition speed can also be controlled by appending `Fast` or `Slow` to the transition, e.g. `fadeFast` or `CarouselLeftSlow`.

Enumerated Values

Property	Value
in	none
in	fade
in	fadeSlow
in	fadeFast
in	reveal
in	revealSlow
in	revealFast
in	wipeLeft
in	wipeLeftSlow
in	wipeLeftFast
in	wipeRight
in	wipeRightSlow
in	wipeRightFast
in	slideLeft
in	slideLeftSlow
in	slideLeftFast
in	slideRight
in	slideRightSlow
in	slideRightFast
in	slideUp
in	slideUpSlow
in	slideUpFast
in	slideDown
in	slideDownSlow
in	slideDownFast
in	carouselLeft
in	carouselLeftSlow
in	carouselLeftFast
in	carouselRight
in	carouselRightSlow
in	carouselRightFast
in	carouselUp
in	carouselUpSlow
in	carouselUpFast
in	carouselDown
in	carouselDownSlow
in	carouselDownFast
in	shuffleTopRight
in	shuffleTopRightSlow
in	shuffleTopRightFast
in	shuffleRightTop
in	shuffleRightTopSlow
in	shuffleRightTopFast
in	shuffleRightBottom
in	shuffleRightBottomSlow
in	shuffleRightBottomFast
in	shuffleBottomRight
in	shuffleBottomRightSlow
in	shuffleBottomRightFast
in	shuffleBottomLeft
in	shuffleBottomLeftSlow
in	shuffleBottomLeftFast
in	shuffleLeftBottom
in	shuffleLeftBottomSlow
in	shuffleLeftBottomFast
in	shuffleLeftTop
in	shuffleLeftTopSlow
in	shuffleLeftTopFast
in	shuffleTopLeft
in	shuffleTopLeftSlow
in	shuffleTopLeftFast
in	zoom
out	none
out	fade
out	fadeSlow
out	fadeFast
out	reveal
out	revealSlow
out	revealFast
out	wipeLeft
out	wipeLeftSlow
out	wipeLeftFast
out	wipeRight
out	wipeRightSlow
out	wipeRightFast
out	slideLeft
out	slideLeftSlow
out	slideLeftFast
out	slideRight
out	slideRightSlow
out	slideRightFast
out	slideUp
out	slideUpSlow
out	slideUpFast
out	slideDown
out	slideDownSlow
out	slideDownFast
out	carouselLeft
out	carouselLeftSlow
out	carouselLeftFast
out	carouselRight
out	carouselRightSlow
out	carouselRightFast
out	carouselUp
out	carouselUpSlow
out	carouselUpFast
out	carouselDown
out	carouselDownSlow
out	carouselDownFast
out	shuffleTopRight
out	shuffleTopRightSlow
out	shuffleTopRightFast
out	shuffleRightTop
out	shuffleRightTopSlow
out	shuffleRightTopFast
out	shuffleRightBottom
out	shuffleRightBottomSlow
out	shuffleRightBottomFast
out	shuffleBottomRight
out	shuffleBottomRightSlow
out	shuffleBottomRightFast
out	shuffleBottomLeft
out	shuffleBottomLeftSlow
out	shuffleBottomLeftFast
out	shuffleLeftBottom
out	shuffleLeftBottomSlow
out	shuffleLeftBottomFast
out	shuffleLeftTop
out	shuffleLeftTopSlow
out	shuffleLeftTopFast
out	shuffleTopLeft
out	shuffleTopLeftSlow
out	shuffleTopLeftFast
out	zoom

Offset

{
  "x": 0.1,
  "y": -0.2
}

Offsets the position of an asset horizontally or vertically by a relative distance.

Properties

Name	Type	Required	Restrictions	Description
x	any	false	none	Offset an asset on the horizontal axis (left or right). Use a number or an array of Tween objects to create a custom animation.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	Range varies from -10 to 10. Positive numbers move the asset right, negative left. 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.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the X offset of an asset over time.

continued

Name	Type	Required	Restrictions	Description
y	any	false	none	Offset an asset on the vertical axis (up or down). Use a number or an array of Tween objects to create a custom animation.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	Range varies from -10 to 10. Positive numbers move the asset up, negative down. The distance moved is relative to the height of the viewport - i.e. an Y offset of 0.5 will move the asset half the screen height up.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the Y offset of an asset over time.

Crop

{
  "top": 0.15,
  "bottom": 0.15,
  "left": 1,
  "right": 1
}

Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.

Properties

Name	Type	Required	Restrictions	Description
top	number(float)	false	none	Crop from the top of the asset
bottom	number(float)	false	none	Crop from the bottom of the asset
left	number(float)	false	none	Crop from the left of the asset
right	number(float)	false	none	Crop from the left of the asset

Transformation

{
  "rotate": {
    "angle": 45
  },
  "skew": {
    "x": 0.5,
    "y": 0.5
  },
  "flip": {
    "horizontal": true,
    "vertical": true
  }
}

Apply one or more transformations to a clip. Transformations alter the visual properties of a clip and can be combined to create new shapes and effects.

Properties

Name	Type	Required	Restrictions	Description
rotate	RotateTransformation	false	none	Rotate a clip by the specified angle in degrees. Rotation origin is set based on the clips `position`.
skew	SkewTransformation	false	none	Skew a clip so its edges are sheared at an angle. Use values between -100 and 100. Values over 3 or under -3 will skew the clip almost flat.
flip	FlipTransformation	false	none	Flip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.

RotateTransformation

{
  "angle": 45
}

Rotate a clip by the specified angle in degrees. Rotation origin is set based on the clips position.

Properties

Name	Type	Required	Restrictions	Description
angle	any	false	none	Rotate a clip by the specified angle in degrees. Use a number or an array of Tween objects to create a custom animation.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	The angle to rotate the clip. Can be 0 to 360, or 0 to -360. Using a positive number rotates the clip clockwise, negative numbers counter-clockwise.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the rotation of an asset over time.

SkewTransformation

{
  "x": 0.5,
  "y": 0.5
}

Skew a clip so its edges are sheared at an angle. Use values between -100 and 100. Values over 3 or under -3 will skew the clip almost flat.

Properties

Name	Type	Required	Restrictions	Description
x	any	false	none	Skew the clip along it's x axis.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	Range varies from -100 to 100. Positive numbers skew the asset right, negative left. The distance moved is relative to the width of the viewport - i.e. an X skew of 0.5 will skew the asset half the screen width to the right.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the X skew of an asset over time.

continued

Name	Type	Required	Restrictions	Description
y	any	false	none	Skew the clip along it's y axis.

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	number(float)	false	none	Range varies from -100 to 100. Positive numbers skew the asset up, negative down. The distance moved is relative to the height of the viewport - i.e. an Y skew of 0.5 will skew the asset half the screen height up.

xor

Name	Type	Required	Restrictions	Description
» anonymous	[Tween]	false	none	An array of Tween objects used to create a custom animation. Animate the Y skew of an asset over time.

FlipTransformation

{
  "horizontal": true,
  "vertical": true
}

Flip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.

Properties

Name	Type	Required	Restrictions	Description
horizontal	boolean	false	none	Flip a clip horizontally.
vertical	boolean	false	none	Flip a clip vertically.

TextFont

{
  "family": "Open Sans",
  "color": "#ffffff",
  "opacity": 0.8,
  "size": 24,
  "weight": 400,
  "lineHeight": 0.85
}

Font properties for text.

Properties

Name	Type	Required	Restrictions	Description
family	string	false	none	The font family name. This must be Family name embedded in the font, i.e. "Open Sans".
color	string	false	none	The text color using hexadecimal color notation.
opacity	number	false	none	The opacity of the text where 1 is opaque and 0 is transparent.
size	integer	false	none	The size of the font in pixels (px).
weight	integer	false	none	The weight of the font. 100 is lightest, 900 is heaviest (boldest).
lineHeight	number	false	none	The line height of the font as a ratio of the font size.

TextBackground

{
  "color": "#000000",
  "opacity": 0.8,
  "padding": 10,
  "borderRadius": 5,
  "wrap": false
}

Displays a background box behind the text.

Properties

Name	Type	Required	Restrictions	Description
color	string	false	none	The background color using hexadecimal color notation.
opacity	number	false	none	The opacity of the background where 1 is opaque and 0 is transparent.
padding	number	false	none	Padding inside the background box in pixels.
borderRadius	number	false	none	The border radius of the background box in pixels for rounded corners.
wrap	boolean	false	none	Not supported on legacy `text` assets. Accepted here only so validators can emit a clear migration error pointing users to `rich-text` or `rich-caption`, which support background wrapping natively.

TextAlignment

{
  "horizontal": "center",
  "vertical": "center"
}

Horizontal and vertical alignment properties for text.

Properties

Name	Type	Required	Restrictions	Description
horizontal	string	false	none	The horizontal alignment of the text. Value must be one of: `left` `center` `right`
vertical	string	false	none	The vertical alignment of the text. Value must be one of: `top` `center` `bottom`

Enumerated Values

Property	Value
horizontal	left
horizontal	center
horizontal	right
vertical	top
vertical	center
vertical	bottom

RichTextFont

{
  "family": "Open Sans",
  "size": 48,
  "weight": "400",
  "style": "italic",
  "color": "#ff0000",
  "opacity": 0.9,
  "background": "#000000",
  "stroke": {
    "width": 2,
    "color": "#000000",
    "opacity": 0.8
  }
}

Font properties for rich text.

Properties

Name	Type	Required	Restrictions	Description
family	string	false	none	The font family name. This must be the Family name embedded in the font, i.e. "Open Sans".
size	integer	false	none	The size of the font in pixels (px). Must be between 1 and 500.
weight	any	false	none	The weight of the font. Can be a number (100-900) or a string ('normal', 'bold', etc.). 100 is lightest, 900 is heaviest (boldest).
style	string	false	none	The font style.
color	string	false	none	The text color using hexadecimal color notation.
opacity	number	false	none	The opacity of the text where 1 is opaque and 0 is transparent.
background	string	false	none	The background color behind the text using hexadecimal color notation.
stroke	RichTextStroke	false	none	Text stroke (outline) properties.

Enumerated Values

Property	Value
style	normal
style	italic

RichTextStyle

{
  "letterSpacing": 2,
  "wordSpacing": 10,
  "lineHeight": 1.5,
  "textTransform": "uppercase",
  "textDecoration": "underline",
  "gradient": {
    "type": "linear",
    "angle": 45,
    "stops": [
      {
        "offset": 0.5,
        "color": "#ff0000"
      },
      {
        "offset": 0.5,
        "color": "#ff0000"
      }
    ]
  }
}

Text style properties including spacing, line height, and transformations.

Properties

Name	Type	Required	Restrictions	Description
letterSpacing	number	false	none	Additional spacing between letters in pixels. Can be negative for tighter spacing.
wordSpacing	number	false	none	Additional spacing between words in pixels. A value of 0 uses the font's natural space width.
lineHeight	number	false	none	The line height as a multiplier of the font size. Must be between 0 and 10.
textTransform	string	false	none	Text transformation to apply.
textDecoration	string	false	none	Text decoration to apply.
gradient	RichTextGradient	false	none	Gradient fill for text instead of solid color.

Enumerated Values

Property	Value
textTransform	none
textTransform	uppercase
textTransform	lowercase
textTransform	capitalize
textDecoration	none
textDecoration	underline
textDecoration	line-through

RichTextGradient

{
  "type": "linear",
  "angle": 45,
  "stops": [
    {
      "offset": 0.5,
      "color": "#ff0000"
    },
    {
      "offset": 0.5,
      "color": "#ff0000"
    }
  ]
}

Gradient properties for text fill.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	The type of gradient.
angle	number	false	none	The angle of the gradient in degrees (for linear gradients). Must be between 0 and 360.
stops	[object]	true	none	Gradient color stops. Must have at least 2 stops.
» offset	number	true	none	Position of the color stop between 0 (start) and 1 (end).
» color	string	true	none	Color at this stop using hexadecimal color notation.

Enumerated Values

Property	Value
type	linear
type	radial

RichTextStroke

{
  "width": 2,
  "color": "#000000",
  "opacity": 0.8
}

Text stroke (outline) properties.

Properties

Name	Type	Required	Restrictions	Description
width	number	false	none	The width of the stroke in pixels. Must be 0 or greater.
color	string	false	none	The stroke color using hexadecimal color notation.
opacity	number	false	none	The opacity of the stroke where 1 is opaque and 0 is transparent.

RichTextShadow

{
  "offsetX": 4,
  "offsetY": 4,
  "blur": 8,
  "color": "#000000",
  "opacity": 0.7
}

Text shadow properties.

Properties

Name	Type	Required	Restrictions	Description
offsetX	number	false	none	Horizontal offset of the shadow in pixels. Positive values move right, negative left.
offsetY	number	false	none	Vertical offset of the shadow in pixels. Positive values move down, negative up.
blur	number	false	none	The blur radius of the shadow in pixels. Must be 0 or greater.
color	string	false	none	The shadow color using hexadecimal color notation.
opacity	number	false	none	The opacity of the shadow where 1 is opaque and 0 is transparent.

RichTextBackground

{
  "color": "#000000",
  "opacity": 0.5,
  "borderRadius": 10,
  "wrap": true,
  "padding": 12
}

Background styling properties for the text bounding box.

Properties

Name	Type	Required	Restrictions	Description
color	string	false	none	The background color using hexadecimal color notation.
opacity	number	false	none	The opacity of the background where 1 is opaque and 0 is transparent.
borderRadius	number	false	none	The border radius of the background box in pixels. Must be 0 or greater.
wrap	boolean	false	none	When true, the background pill shrinks to fit the rendered text bounding box plus the asset's padding (and stroke width, if present), producing a pill or badge effect. When false (default), the background fills the full asset content area. Available on rich-text and rich-caption assets only; not supported on legacy `type: text`.
padding	integer	false	none	Inner padding in pixels between the wrap pill edge and the rendered text. Only takes effect when `wrap: true`. When omitted, the renderer applies a sensible default proportional to the font size (approximately 12% of the active page font size on rich-caption assets). Set to 0 for a pill that hugs the text exactly. Available on rich-text and rich-caption assets only.

RichTextAlignment

{
  "horizontal": "center",
  "vertical": "middle"
}

Text alignment properties (horizontal and vertical).

Properties

Name	Type	Required	Restrictions	Description
horizontal	string	false	none	The horizontal alignment of the text.
vertical	string	false	none	The vertical alignment of the text within the bounding box.

Enumerated Values

Property	Value
horizontal	left
horizontal	center
horizontal	right
vertical	top
vertical	middle
vertical	bottom

RichTextAnimation

{
  "preset": "shift",
  "duration": 2,
  "style": "character",
  "direction": "up"
}

Animation properties for text entrance effects.

Properties

Name	Type	Required	Restrictions	Description
preset	string	true	none	The animation preset to apply. Available presets: `fadeIn` - fadeIn in animation `slideIn` - slide in from a direction `typewriter` - typewriter effect `ascend` - ascend from a direction `shift` - shift in from a direction `movingLetters` - letters move in from a direction
duration	number	false	none	Override animation duration in seconds. Must be between 0.1 and 30 seconds.
style	string	false	none	Animation style - animate by character or by word. Only applicable for typewriter and shift animations.
direction	string	false	none	Direction for directional animations. Required for slideIn, ascend, shift, and movingLetters presets. `ascend` - supports: up, down `shift` - supports: left, right, up, down `slideIn` - supports: left, right, up, down `movingLetters` - supports: left, right, up, down

Enumerated Values

Property	Value
preset	fadeIn
preset	slideIn
preset	typewriter
preset	ascend
preset	shift
preset	movingLetters
style	character
style	word
direction	left
direction	right
direction	up
direction	down

CaptionFont

{
  "family": "Open Sans",
  "color": "#ffffff",
  "opacity": 0.8,
  "size": 24,
  "lineHeight": 0.85,
  "stroke": "#ff6600",
  "strokeWidth": 0.8
}

Font properties for captions text.

Properties

Name	Type	Required	Restrictions	Description
family	string	false	none	The font family name. This must be Family name embedded in the font, i.e. "Open Sans".
color	string	false	none	The text color using hexadecimal color notation.
opacity	number	false	none	The opacity of the text where 1 is opaque and 0 is transparent.
size	integer	false	none	The size of the font in pixels (px).
lineHeight	number	false	none	The line height of the font as a ratio of the font size.
stroke	string	false	none	The stroke color of the font using hexadecimal color notation.
strokeWidth	number	false	none	The width of the stroke in pixels.

CaptionBackground

{
  "color": "#000000",
  "opacity": 0.4,
  "padding": 30,
  "borderRadius": 18
}

Displays a background box behind the caption text.

Properties

Name	Type	Required	Restrictions	Description
color	string	false	none	The background color using hexadecimal color notation.
opacity	number	false	none	The opacity of the background color.
padding	integer	false	none	The padding inside the background box in pixels.
borderRadius	integer	false	none	The border radius of the background box in pixels.

CaptionMargin

{
  "top": 0.25,
  "left": 0.05,
  "right": 0.45
}

The margin properties for captions. Margins are used to position the caption text and background on the screen.

Properties

Name	Type	Required	Restrictions	Description
top	number	false	none	The margin above the text. Pushes captions down the screen.
left	number	false	none	The margin to the left of the text. Pushes captions to the right.
right	number	false	none	The margin to the right of the text. Pushes captions to the left.

ChromaKey

{
  "color": "#00b140",
  "threshold": 150,
  "halo": 100
}

Chroma key is a technique that replaces a specific color in a video with a different background image or video, enabling seamless integration of diverse environments. Commonly used for green screen and blue screen effects.

Properties

Name	Type	Required	Restrictions	Description
color	string	true	none	The chroma key color as a hex value. Use green (#00b140) for green screens or blue (#0000FF) for blue screens. Any valid hex color can be used as the key color.
threshold	integer	false	none	Pixels within this distance from the key color are eliminated by setting their alpha values to zero.
halo	integer	false	none	Pixels within the halo distance from the threshold boundary are given an increasing alpha value based on their distance from the threshold.

Tween

{
  "from": 0,
  "to": 1,
  "start": 0,
  "length": 3,
  "interpolation": "bezier",
  "easing": "ease"
}

Use a Tween to animate properties over time. The following properties are currently supported and can be animated:

Opacity - animate the transparency of a clip.
Offset - animate the x and y position of a clip.
Rotation - animate the rotation of a clip.
Skew - animate the horizontal and vertical shearing effect.
Volume - animate the audio volume of a clip.

Properties

Name	Type	Required	Restrictions	Description
from	any	false	none	The initial property value at the start of the animation.
to	any	false	none	The final property value at the end of the animation.
start	number	false	none	The time in seconds when the animation starts, relative to the clip, not the timeline.
length	number	false	none	The duration of the animation in seconds.
interpolation	string	false	none	The interpolation method to use for the animation. Available options are: `linear` - a linear interpolation between the start and end values. `bezier` - a bezier curve interpolation between the start and end values. `constant` - an interpolation where the property instantly jumps from the start to the end value, without any gradual transition.
easing	string	false	none	The easing function to use for the animation. Easing controls the rate of change of the animated value, allowing for more natural motion by speeding up or slowing down the animation at different points. Only applicable if interpolation is set to `bezier`.

Enumerated Values

Property	Value
interpolation	linear
interpolation	bezier
interpolation	constant
easing	ease
easing	easeIn
easing	easeOut
easing	easeInOut
easing	easeInQuad
easing	easeInCubic
easing	easeInQuart
easing	easeInQuint
easing	easeInSine
easing	easeInExpo
easing	easeInCirc
easing	easeInBack
easing	easeOutQuad
easing	easeOutCubic
easing	easeOutQuart
easing	easeOutQuint
easing	easeOutSine
easing	easeOutExpo
easing	easeOutCirc
easing	easeOutBack
easing	easeInOutQuad
easing	easeInOutCubic
easing	easeInOutQuart
easing	easeInOutQuint
easing	easeInOutSine
easing	easeInOutExpo
easing	easeInOutCirc
easing	easeInOutBack

MergeField

{
  "find": "NAME",
  "replace": "Jane"
}

A merge field consists of a key; find, and a value; replace. Merge fields can be used to replace placeholders within the JSON edit to create re-usable templates. Placeholders should be a string with double brace delimiters, i.e. "{{NAME}}". A placeholder can be used for any value within the JSON edit.

Properties

Name	Type	Required	Restrictions	Description
find	string	true	none	The string to find without delimiters.
replace	any	true	none	The replacement value. The replacement can be any valid JSON type - string, boolean, number, etc...

Output

{
  "format": "mp4",
  "resolution": "hd",
  "aspectRatio": "16:9",
  "size": {
    "width": 1200,
    "height": 800
  },
  "fps": 25,
  "scaleTo": "preview",
  "quality": "medium",
  "repeat": true,
  "mute": false,
  "range": {
    "start": 3,
    "length": 6
  },
  "poster": {
    "capture": 1
  },
  "thumbnail": {
    "capture": 1,
    "scale": 0.3
  },
  "destinations": [
    {
      "provider": "shotstack",
      "exclude": false
    }
  ]
}

The output format, render range and type of media to generate. For all formats except mp3, either resolution or size (with both width and height) must be specified.

Properties

Name	Type	Required	Restrictions	Description
format	string	true	none	The output format and type of media file to generate. `mp4` - mp4 video file `gif` - animated gif `jpg` - jpg image file `png` - png image file `bmp` - bmp image file `mp3` - mp3 audio file (audio only)
resolution	string	false	none	The preset output resolution of the video or image. For custom sizes use the `size` property. Either `resolution` or `size` (with both `width` and `height`) must be specified for all formats except `mp3`. `preview` - 512px x 288px @ 15fps `mobile` - 640px x 360px @ 25fps `sd` - 1024px x 576px @ 25fps `hd` - 1280px x 720px @ 25fps `1080` - 1920px x 1080px @ 25fps `4k` - 3840px x 2160px @ 25fps
aspectRatio	string	false	none	The aspect ratio (shape) of the video or image. Useful for social media output formats. Options are: `16:9` (default) - regular landscape/horizontal aspect ratio `9:16` - vertical/portrait aspect ratio `1:1` - square aspect ratio `4:5` - short vertical/portrait aspect ratio `4:3` - legacy TV aspect ratio
size	Size	false	none	Set a custom size for a video or image in pixels. When using a custom size omit the `resolution` and `aspectRatio`. Custom sizes must be divisible by 2 based on the encoder specifications.
fps	number	false	none	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. `12` - 12fps `15` - 15fps `24` - 24fps `23.976` - 23.976fps `25` (default) - 25fps `29.97` - 29.97fps `30` - 30fps `48` - 48fps `50` - 50fps `59.94` - 59.94fps `60` - 60fps
scaleTo	string	false	none	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. `preview` - 512px x 288px @ 15fps `mobile` - 640px x 360px @ 25fps `sd` - 1024px x 576px @25fps `hd` - 1280px x 720px @25fps `1080` - 1920px x 1080px @25fps
quality	string	false	none	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. `verylow` - reduced quality, smallest file size `low` - slightly reduced quality, smaller file size `medium` (default) - optimized quality, render speeds and file size `high` - slightly increased quality, larger file size `veryhigh` - highest quality, largest file size
repeat	boolean	false	none	Loop settings for gif files. Set to `true` to loop, `false` to play only once.
mute	boolean	false	none	Mute the audio track of the output video. Set to `true` to mute, `false` to un-mute.
range	Range	false	none	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.
poster	Poster	false	none	Generate a poster image from a specific point on the timeline.
thumbnail	Thumbnail	false	none	Generate a thumbnail image from a specific point on the timeline.
destinations	[Destinations]	false	none	Specify the storage locations and hosting services to send rendered videos to.

Enumerated Values

Property	Value
format	mp4
format	gif
format	mp3
format	jpg
format	png
format	bmp
resolution	preview
resolution	mobile
resolution	sd
resolution	hd
resolution	1080
resolution	4k
aspectRatio	16:9
aspectRatio	9:16
aspectRatio	1:1
aspectRatio	4:5
aspectRatio	4:3
fps	12
fps	15
fps	23.976
fps	24
fps	25
fps	29.97
fps	30
fps	48
fps	50
fps	59.94
fps	60
scaleTo	preview
scaleTo	mobile
scaleTo	sd
scaleTo	hd
scaleTo	1080
scaleTo	4k
quality	verylow
quality	low
quality	medium
quality	high
quality	veryhigh

Size

{
  "width": 1200,
  "height": 800
}

Set a custom size for a video or image in pixels. When using a custom size omit the resolution and aspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications.

Properties

Name	Type	Required	Restrictions	Description
width	integer	false	none	Set a custom width for the video or image file in pixels. Value must be divisible by 2. Maximum video width is 1920px, maximum image width is 4096px.
height	integer	false	none	Set a custom height for the video or image file in pixels. Value must be divisible by 2. Maximum video height is 1920px, maximum image height is 4096px.

Range

{
  "start": 3,
  "length": 6
}

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

Name	Type	Required	Restrictions	Description
start	number(float)	false	none	The point on the timeline, in seconds, to start the render from - i.e. start at second 3.
length	number(float)	false	none	The length of the portion of the video or audio to render - i.e. render 6 seconds of the video.

Poster

{
  "capture": 1
}

Generate a poster image for the video at a specific point from the timeline. The poster image size will match the size of the output video.

Properties

Name	Type	Required	Restrictions	Description
capture	number	true	none	The point on the timeline in seconds to capture a single frame to use as the poster image.

Thumbnail

{
  "capture": 1,
  "scale": 0.3
}

Generate a thumbnail image for the video or image at a specific point from the timeline.

Properties

Name	Type	Required	Restrictions	Description
capture	number	true	none	The point on the timeline in seconds to capture a single frame to use as the thumbnail image.
scale	number	true	none	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.

Destinations

{
  "provider": "shotstack",
  "exclude": false
}

A destination is a location where assets can be sent to for serving or hosting. Videos, images and audio files that are rendered by the Edit API and source and rendition files generated by the Ingest API can be sent to destinations. You can also fetch a file from any public URL and transfer it to a destination. A file can be sent to one or more destinations including 3rd party destinations.

By default all ingested and generated assets are automatically sent to the Shotstack hosting destination. You can opt-out from by setting the Shotstack destination exclude property to true.

Properties

anyOf

Name	Type	Required	Restrictions	Description
anonymous	ShotstackDestination	false	none	Send videos and assets to the Shotstack hosting and CDN service. This destination is enabled by default.

Name	Type	Required	Restrictions	Description
anonymous	MuxDestination	false	none	Send videos to the Mux video hosting and streaming service. Mux credentials are required and added via the dashboard, not in the request.

Name	Type	Required	Restrictions	Description
anonymous	S3Destination	false	none	Send videos and assets to an Amazon S3 bucket. Send files to any region with your own prefix and filename. AWS credentials are required and added via the dashboard, not in the request.

Name	Type	Required	Restrictions	Description
anonymous	GoogleCloudStorageDestination	false	none	Send videos and assets to a Google Cloud Storage bucket. Send files with your own prefix and filename. Google Cloud credentials are required and added via the dashboard, not in the request.

Name	Type	Required	Restrictions	Description
anonymous	GoogleDriveDestination	false	none	Send rendered videos and assets to the Google Drive cloud storage service. Google Drive uses OAuth and you must authenticate and link your Google account via dashboard, not in the request.

Name	Type	Required	Restrictions	Description
anonymous	VimeoDestination	false	none	Send videos to Vimeo video hosting and streaming service. Vimeo credentials are required and added via the dashboard, not in the request.

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	Send videos to TikTok. TikTok credentials are required and added via the dashboard, not in the request.
» provider	string	true	none	The destination to send video to - set to `tiktok` for TikTok.
» options	object	false	none	Additional TikTok configuration options.
»» title	string	false	none	A title for the video that will be displayed on TikTok.
»» privacyLevel	string	false	none	The privacy level for the video. Options are: `public` - video is visible to everyone `friends` - video is visible to friends only `private` - video is only visible to you
»» disableDuet	boolean	false	none	Disable the Duet feature for this video.
»» disableStitch	boolean	false	none	Disable the Stitch feature for this video.
»» disableComment	boolean	false	none	Disable comments on this video.

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	Send videos and assets to Akamai NetStorage. Send files to your NetStorage upload directory with a custom path and filename. Akamai credentials are required and added via the dashboard, not in the request.
» provider	string	true	none	The destination to send assets to - set to `akamai-netstorage` for Akamai NetStorage.
» options	object	false	none	Additional Akamai NetStorage configuration options.
»» host	string	true	none	The Akamai NetStorage hostname, i.e. `example-nsu.akamaihd.net`.
»» cpCode	string	true	none	The Content Provider code (CP code) for the NetStorage upload directory.
»» path	string¦null	false	none	A remote directory path/prefix for the file being sent, i.e. `videos` or `customerId/videos`.
»» filename	string¦null	false	none	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.

Name	Type	Required	Restrictions	Description
anonymous	object	false	none	Send videos and assets to Azure Blob Storage. Send files to any container with a custom prefix and filename. Azure credentials are required and added via the dashboard, not in the request.
» provider	string	true	none	The destination to send assets to - set to `azure-blob-storage` for Azure Blob Storage.
» options	object	false	none	Additional Azure Blob Storage configuration options.
»» accountName	string	true	none	The Azure Storage account name.
»» container	string	true	none	The Blob container name. The container must exist in the Azure Storage account before files can be sent.
»» prefix	string¦null	false	none	A virtual directory prefix for the blob being sent, i.e. `videos` or `customerId/videos`.
»» filename	string¦null	false	none	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.

Enumerated Values

Property	Value
privacyLevel	public
privacyLevel	friends
privacyLevel	private

ShotstackDestination

{
  "provider": "shotstack",
  "exclude": false
}

Send videos and assets to the Shotstack hosting and CDN service. This destination is enabled by default.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The destination to send assets to - set to `shotstack` for Shotstack hosting and CDN.
exclude	boolean	false	none	Set to `true` to opt-out from the Shotstack hosting and CDN service. All files must be downloaded within 24 hours of rendering.

MuxDestination

{
  "provider": "mux",
  "options": {
    "playbackPolicy": [
      "public"
    ],
    "passthrough": "string"
  }
}

Send videos to the Mux video hosting and streaming service. Mux credentials are required and added via the dashboard, not in the request.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The destination to send video to - set to `mux` for Mux.
options	MuxDestinationOptions	false	none	Additional Mux configuration and features.

MuxDestinationOptions

{
  "playbackPolicy": [
    "public"
  ],
  "passthrough": "string"
}

Pass additional options to control how Mux processes video. Currently supports playback_policy and passthrough options.

Properties

Name	Type	Required	Restrictions	Description
playbackPolicy	[string]	false	none	Sets the Mux `playback_policy` option. Value is an array of strings - use `public`, `signed`, or both.
passthrough	string	false	none	Sets the Mux `passthrough` option. Max 255 characters.

S3Destination

{
  "provider": "s3",
  "options": {
    "region": "us-east-1",
    "bucket": "my-bucket",
    "prefix": "my-renders",
    "filename": "my-file",
    "acl": "public-read"
  }
}

Send videos and assets to an Amazon S3 bucket. Send files to any region with your own prefix and filename. AWS credentials are required and added via the dashboard, not in the request.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The destination to send assets to - set to `s3` for S3.
options	S3DestinationOptions	false	none	Additional S3 configuration options.

S3DestinationOptions

{
  "region": "us-east-1",
  "bucket": "my-bucket",
  "prefix": "my-renders",
  "filename": "my-file",
  "acl": "public-read"
}

Pass additional options to control how files are stored in S3.

Properties

Name	Type	Required	Restrictions	Description
region	string	true	none	Choose the region to send the file to. Must be a valid AWS region string like `us-east-1` or `ap-southeast-2`.
bucket	string	true	none	The bucket name to send files to. The bucket must exist in the AWS account before files can be sent.
prefix	string	false	none	A prefix for the file being sent. This is typically a folder name, i.e. `videos` or `customerId/videos`.
filename	string	false	none	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.
acl	string	false	none	Sets the S3 Access Control List (acl) permissions. Default is `private`. Must use a valid S3 Canned ACL.

GoogleCloudStorageDestination

{
  "provider": "google-cloud-storage",
  "options": {
    "bucket": "my-bucket",
    "prefix": "my-renders",
    "filename": "my-file"
  }
}

Send videos and assets to a Google Cloud Storage bucket. Send files with your own prefix and filename. Google Cloud credentials are required and added via the dashboard, not in the request.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The destination to send assets to - set to `google-cloud-storage` for Google Cloud Storage.
options	GoogleCloudStorageDestinationOptions	false	none	Additional Google Cloud Storage configuration options.

GoogleCloudStorageDestinationOptions

{
  "bucket": "my-bucket",
  "prefix": "my-renders",
  "filename": "my-file"
}

Pass additional options to control how files are stored in Google Cloud Storage.

Properties

Name	Type	Required	Restrictions	Description
bucket	string	true	none	The bucket name to send files to. The bucket must exist in the Google Cloud Storage account before files can be sent.
prefix	string	false	none	A prefix for the file being sent. This is typically a folder name, i.e. `videos` or `customerId/videos`.
filename	string	false	none	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.

GoogleDriveDestination

{
  "provider": "google-drive",
  "options": {
    "folderId": "1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A",
    "filename": "my-file"
  }
}

Send rendered videos and assets to the Google Drive cloud storage service. Google Drive uses OAuth and you must authenticate and link your Google account via dashboard, not in the request.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The destination to send assets to - set to `google-drive` for Google Drive.
options	GoogleDriveDestinationOptions	false	none	Additional Google Drive configuration and features. If omitted, files are saved to the root of My Drive using the default Shotstack filename.

GoogleDriveDestinationOptions

{
  "folderId": "1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A",
  "filename": "my-file"
}

Pass the folder ID and options to configure how assets are stored in Google Drive.

Properties

Name	Type	Required	Restrictions	Description
folderId	string	false	none	The Google Drive folder ID where the asset will be stored. If omitted, the asset is saved to the root of My Drive. The folder ID can be retrieved from the URL when logged in to Google Drive, e.g. https://drive.google.com/drive/u/0/folders/1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A.
filename	string	false	none	Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also `-poster.jpg` and `-thumb.jpg` will be appended for poster and thumbnail images.

VimeoDestination

{
  "provider": "vimeo",
  "options": {
    "name": "string",
    "description": "string",
    "privacy": {
      "view": "anybody",
      "embed": "public",
      "comments": "anybody",
      "download": true,
      "add": true
    },
    "folderUri": "/users/12345678/projects/87654321"
  }
}

Send videos to Vimeo video hosting and streaming service. Vimeo credentials are required and added via the dashboard, not in the request.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The destination to send video to - set to `vimeo` for Vimeo.
options	VimeoDestinationOptions	false	none	Additional Vimeo configuration and features.

VimeoDestinationOptions

{
  "name": "string",
  "description": "string",
  "privacy": {
    "view": "anybody",
    "embed": "public",
    "comments": "anybody",
    "download": true,
    "add": true
  },
  "folderUri": "/users/12345678/projects/87654321"
}

Pass additional options to control how Vimeo publishes video, including name, description and privacy settings.

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	A name or title for the video that will be displayed on the Vimeo website.
description	string	false	none	A description of the video that will be displayed on the Vimeo website.
privacy	VimeoDestinationPrivacyOptions	false	none	Options to control the visibility of videos and privacy features.
folderUri	string	false	none	The Vimeo folder URI to upload the video to. The folder must already exist in your Vimeo account.

VimeoDestinationPrivacyOptions

{
  "view": "anybody",
  "embed": "public",
  "comments": "anybody",
  "download": true,
  "add": true
}

Options to control the visibility of videos and privacy features.

Properties

Name	Type	Required	Restrictions	Description
view	string	false	none	Set who can view the videos. Available options are: `anybody` - Anyone can view the video. `nobody` - Only the video owner can view the video. `contacts` - Only contacts can view the video. `password` - A password is required to view the video. `unlisted` - The video is not listed on Vimeo.
embed	string	false	none	Set who can embed the video. Available options are: `public` - Anyone can embed the video. `private` - Only the video owner can embed the video. `whitelist` - Only whitelisted domains can embed the video.
comments	string	false	none	Set who can comment on the video. Available options are: `anybody` - Anyone can comment on the video. `nobody` - Only the video owner can comment on the video. `contacts` - Only contacts can comment on the video.
download	boolean	false	none	Set whether the video can be downloaded.
add	boolean	false	none	Set whether other users can add the video to their collections.

Enumerated Values

Property	Value
view	anybody
view	nobody
view	contacts
view	password
view	unlisted
embed	public
embed	private
embed	whitelist
comments	anybody
comments	nobody
comments	contacts

Template

{
  "name": "My template",
  "template": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  }
}

A template is a saved Edit than can be loaded and re-used.

Properties

Name	Type	Required	Restrictions	Description
name	string	true	none	The template name
template	Edit	false	none	An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format. Video assets are automatically preprocessed to fix common compatibility issues before rendering. You can control preprocessing behavior using the `transcode` flag on video assets.

TemplateRender

{
  "id": "f5493c17-d01f-445c-bb49-535fae65f219",
  "merge": [
    {
      "find": "NAME",
      "replace": "Jane"
    }
  ]
}

Configure the id and optional merge fields to render a template by id.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The id of the template to render in UUID format.
merge	[MergeField]	false	none	An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder `{{NAME}}` and replace it with the value `Jane`.

Source

{
  "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
  "outputs": {
    "renditions": [
      {
        "format": "mp4",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fit": "crop",
        "resolution": "hd",
        "quality": 70,
        "fps": 25,
        "speed": {
          "speed": 1.5,
          "preservePitch": false
        },
        "keyframeInterval": 10,
        "fixOffset": true,
        "fixRotation": true,
        "enhance": {
          "audio": {
            "provider": "dolby",
            "options": {
              "preset": "studio"
            }
          }
        },
        "filename": "my-video"
      }
    ],
    "transcription": {
      "format": "vtt"
    }
  },
  "destinations": {
    "provider": "shotstack",
    "exclude": false
  },
  "callback": "https://my-server.com/callback.php"
}

The details of the file to be ingested and any transformations to be applied. Once the source file has been ingested, new renditions can be created from it. The renditions are specified in the outputs property. A rendition is a new version, generated from the source. This can be used to create new sizes and aspect ratios tht serve different purposes within an application.

Properties

Name	Type	Required	Restrictions	Description
url	string	false	none	The URL of the file to be ingested. The URL must be publicly accessible or include credentials.
outputs	Outputs	false	none	The output renditions and transformations that should be generated from the source file.
destinations	Destinations	false	none	A destination is a location where assets can be sent to for serving or hosting. Videos, images and audio files that are rendered by the Edit API and source and rendition files generated by the Ingest API can be sent to destinations. You can also fetch a file from any public URL and transfer it to a destination. A file can be sent to one or more destinations including 3rd party destinations. By default all ingested and generated assets are automatically sent to the Shotstack hosting destination. You can opt-out from by setting the Shotstack destination exclude property to true.
callback	string	false	none	An optional webhook callback URL used to receive status notifications when sources are uploaded and renditions processed.

Outputs

{
  "renditions": [
    {
      "format": "mp4",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fit": "crop",
      "resolution": "hd",
      "quality": 70,
      "fps": 25,
      "speed": {
        "speed": 1.5,
        "preservePitch": false
      },
      "keyframeInterval": 10,
      "fixOffset": true,
      "fixRotation": true,
      "enhance": {
        "audio": {
          "provider": "dolby",
          "options": {
            "preset": "studio"
          }
        }
      },
      "filename": "my-video"
    }
  ],
  "transcription": {
    "format": "vtt"
  }
}

The output renditions and transformations that should be generated from the source file.

Properties

Name	Type	Required	Restrictions	Description
renditions	[Rendition]	false	none	The output renditions and transformations that should be generated from the source file.
transcription	Transcription	false	none	The transcription settings for the output file.

Rendition

{
  "format": "mp4",
  "size": {
    "width": 1200,
    "height": 800
  },
  "fit": "crop",
  "resolution": "hd",
  "quality": 70,
  "fps": 25,
  "speed": {
    "speed": 1.5,
    "preservePitch": false
  },
  "keyframeInterval": 10,
  "fixOffset": true,
  "fixRotation": true,
  "enhance": {
    "audio": {
      "provider": "dolby",
      "options": {
        "preset": "studio"
      }
    }
  },
  "filename": "my-video"
}

A rendition is a new output file that is generated from the source. The rendition can be encoded to a different format and have transformations applied to it such as resizing, cropping, etc...

Properties

Name	Type	Required	Restrictions	Description
format	string	false	none	The output format to encode the file to. You can only encode a file to the same type, i.e. a video to a video or an image to an image. You can't encode a video as an image. The following formats are available: `mp4` - mp4 video file (video only) `webm` - webm video file (video only) `mov` - mov video file (video only) `avi` - avi video file (video only) `mkv` - mkv video file (video only) `ogv` - ogv video file (video only) `wmv` - wmv video file (video only) `avif` - avif video file (video only) `gif` - animated gif file (video only) `jpg` - jpg image file (image only) `png` - png image file (image only) `webp` - webp image file (image only) `tif` - tif image file (image only) `mp3` - mp3 audio file (audio only) `wav` - wav audio file (audio only)
size	Size	false	none	Set a custom size for a video or image in pixels. When using a custom size omit the `resolution` and `aspectRatio`. Custom sizes must be divisible by 2 based on the encoder specifications.
fit	string	false	none	Set how the rendition should be scaled and cropped when using a size with an aspect ratio that is different from the source. Fit applies to both videos and images. `crop` (default) - scale the rendition to fill the output area while maintaining the aspect ratio. The rendition will be cropped if it exceeds the bounds of the output. `cover` - stretch the rendition to fill the output without maintaining the aspect ratio. `contain` - fit the entire rendition within the output while maintaining the original aspect ratio.
resolution	any	false	none	The preset output resolution of the video or image. This is a convenience property that sets the width and height based on industry standard resolutions. The following resolutions are available: `preview` - 512px x 288px `mobile` - 640px x 360px `sd` - 1024px x 576px `hd` - 1280px x 720px `fhd` - 1920px x 1080px
quality	integer	false	none	Adjust the visual quality of the video or image. The higher the value, the sharper the image quality but the larger file size and slower the encoding process. When specifying quality, the goal is to balance file size vs visual quality. Quality is a value between 1 and 100 where 1 is fully compressed with low image quality and 100 is close to lossless with high image quality and large file size. Sane values are between 50 and 75. Omitting the quality parameter will result in an asset optimised for encoding speed, file size and visual quality.
fps	number	false	none	Change the frame rate of a video asset. `12` - 12fps `15` - 15fps `24` - 24fps `23.976` - 23.976fps `25` (default) - 25fps `29.97` - 29.97fps `30` - 30fps `48` - 48fps `50` - 50fps `59.94` - 59.94fps `60` - 60fps
speed	Speed	false	none	Set the playback speed of a video or audio file. Allows you to preserve the pitch of the audio so that it is sped up without sounding too high pitched or too low.
keyframeInterval	integer	false	none	The keyframe interval is useful to optimize playback, seeking and smoother scrubbing in browsers. The value sets the number of frames between a keyframe. The lower the number, the larger the file. Try a value between 10 and 25 for smooth scrubbing.
fixOffset	boolean	false	none	Attempt to fix audio and video sync issues. This can occur when recording devices, such as smartphones and web cams use compression techniques like Variable Frame Rate (VFR) which can cause audio and video to go out of sync. This option will attempt to fix the sync issues.
fixRotation	boolean	false	none	Automatically reset the rotation of the video based on the orientation metadata in the video file. This is useful for videos recorded on smartphones that have orientation metadata that may not work correctly with certain video editing software, including the Shotstack Edit API.
enhance	Enhancements	false	none	Apply media processing enhancements to the rendition using a third party provider. Currently only Dolby.io audio enhancement is available.
filename	string	false	none	A custom name for the generated rendition file. The file extension will be automatically added based on the format of the rendition. If no filename is provided, the rendition ID will be used.

Enumerated Values

Property	Value
format	mp4
format	webm
format	mov
format	avi
format	mkv
format	ogv
format	wmv
format	avif
format	gif
format	mp3
format	wav
format	jpg
format	png
format	webp
format	tif
fit	cover
fit	contain
fit	crop
resolution	preview
resolution	mobile
resolution	sd
resolution	hd
resolution	fhd
fps	12
fps	15
fps	23.976
fps	24
fps	25
fps	29.97
fps	30
fps	48
fps	50
fps	59.94
fps	60

Transcription

{
  "format": "vtt"
}

Generate a transcription of the audio in the video. The transcription can be output as a file in SRT or VTT format.

Properties

Name	Type	Required	Restrictions	Description
format	string	false	none	The output format of the transcription file. The following formats are available: `srt` - SRT captions format `vtt` - VTT captions format

Enumerated Values

Property	Value
format	srt
format	vtt

Speed

{
  "speed": 1.5,
  "preservePitch": false
}

Set the playback speed of a video or audio file. Allows you to preserve the pitch of the audio so that it is sped up without sounding too high pitched or too low.

Properties

Name	Type	Required	Restrictions	Description
speed	number(float)	false	none	Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Set values less than 1 to slow down the playback speed, i.e. set speed to 0.5 to play back at half speed. Set values greater than 1 to speed up the playback speed, i.e. set speed to 2 to play back at double speed.
preservePitch	boolean	false	none	Set whether to adjust the audio pitch or not. Set to false to make the audio sound higher or lower pitched. By default the pitch is preserved.

Enhancements

{
  "audio": {
    "provider": "dolby",
    "options": {
      "preset": "studio"
    }
  }
}

Enhancements that can be applied to a rendition. Currently only supports the Dolby audio enhancement.

Properties

Name	Type	Required	Restrictions	Description
audio	AudioEnhancement	false	none	An audio enhancement that can be applied to the audio content of the rendition.

AudioEnhancement

{
  "provider": "dolby",
  "options": {
    "preset": "studio"
  }
}

An audio enhancement that can be applied to the audio content of a rendition. The following providers are available:

DolbyEnhancement

Properties

None

DolbyEnhancement

{
  "provider": "dolby",
  "options": {
    "preset": "studio"
  }
}

Dolby.io audio enhancement provider. Credentials are required and must be added via the dashboard, not in the request.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The enhancement provider to use - set to `dolby` for Dolby.
options	DolbyEnhancementOptions	true	none	Additional Dolby configuration and features.

DolbyEnhancementOptions

{
  "preset": "studio"
}

Options for the Dolby.io audio enhancement provider.

Properties

Name	Type	Required	Restrictions	Description
preset	string	true	none	The preset to use for the audio enhancement. The following presets are available: `conference` - Conference `interview` - Interview `lecture` - Lecture `meeting` - Meeting `mobile_phone` - Mobile Phone `music` - Music `podcast` - Podcast `studio` - Studio `voice_over` - Voice Over

Enumerated Values

Property	Value
preset	conference
preset	interview
preset	lecture
preset	meeting
preset	mobile_phone
preset	music
preset	podcast
preset	studio
preset	voice_over

Transfer

{
  "url": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
  "id": "018e8937-5015-75ee-aab6-03f214981133",
  "destinations": [
    {
      "provider": "shotstack",
      "exclude": false
    }
  ]
}

The asset URL to fetch and transfer to a destination.

Properties

Name	Type	Required	Restrictions	Description
url	string	true	none	The file URL to fetch and transfer.
id	string	true	none	An identifier for the asset which must be provided by the client. The identifier does not need to be unique.
destinations	[Destinations]	true	none	Specify the storage locations and hosting services to send the file to.

QueuedResponse

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7"
  }
}

The response received after a render request or template render is submitted. The render task is queued for rendering and a unique render id is returned.

Properties

Name	Type	Required	Restrictions	Description
success	boolean	true	none	`true` if successfully queued, else `false`.
message	string	true	none	`Created`, `Bad Request` or an error message.
response	QueuedResponseData	true	none	`QueuedResponseData` or an error message.

QueuedResponseData

{
  "message": "Render Successfully Queued",
  "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7"
}

The response data returned with the QueuedResponse.

Properties

Name	Type	Required	Restrictions	Description
message	string	true	none	Success response message or error details.
id	string	true	none	The id of the render task in UUID format.

RenderResponse

{
  "success": true,
  "message": "OK",
  "response": {
    "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
    "owner": "5ca6hu7s9k",
    "plan": "basic",
    "status": "done",
    "error": "",
    "duration": 8.5,
    "renderTime": 9433.44,
    "url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
    "poster": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7-poster.jpg",
    "thumbnail": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7-thumb.jpg",
    "data": {
      "timeline": {
        "soundtrack": {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
          "effect": "fadeIn",
          "volume": 0
        },
        "background": "string",
        "fonts": [
          {
            "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
          }
        ],
        "tracks": [
          {
            "clips": [
              {
                "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                  "prompt": "Slowly zoom out and orbit left around the object.",
                  "model": "seedance-2.0-text-to-video",
                  "options": {
                    "resolution": "720p",
                    "duration": "8",
                    "generateAudio": true
                  },
                  "transcode": false,
                  "trim": 2,
                  "volume": 0.5,
                  "volumeEffect": "none",
                  "speed": 1,
                  "crop": {
                    "top": 0.15,
                    "bottom": 0.15,
                    "left": 1,
                    "right": 1
                  },
                  "chromaKey": {
                    "color": "#00b140",
                    "threshold": 150,
                    "halo": 100
                  }
                },
                "start": 2,
                "length": 5,
                "fit": "cover",
                "scale": 0.5,
                "width": 800,
                "height": 600,
                "position": "top",
                "offset": {
                  "x": 0.1,
                  "y": -0.2
                },
                "transition": {
                  "in": "none",
                  "out": "none"
                },
                "effect": "zoomIn",
                "filter": "greyscale",
                "opacity": 0.5,
                "transform": {
                  "rotate": {
                    "angle": 45
                  },
                  "skew": {
                    "x": 0.5,
                    "y": 0.5
                  },
                  "flip": {
                    "horizontal": true,
                    "vertical": true
                  }
                },
                "alias": "MY_VIDEO_CLIP"
              }
            ]
          }
        ],
        "cache": true
      },
      "output": {
        "format": "mp4",
        "resolution": "hd",
        "aspectRatio": "16:9",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fps": 25,
        "scaleTo": "preview",
        "quality": "medium",
        "repeat": true,
        "mute": false,
        "range": {
          "start": 3,
          "length": 6
        },
        "poster": {
          "capture": 1
        },
        "thumbnail": {
          "capture": 1,
          "scale": 0.3
        },
        "destinations": [
          {
            "provider": "shotstack",
            "exclude": false
          }
        ]
      },
      "merge": [
        {
          "find": "NAME",
          "replace": "Jane"
        }
      ],
      "callback": "https://my-server.com/callback.php",
      "disk": "local",
      "instance": "s1"
    },
    "created": "2020-10-30T09:42:29.446Z",
    "updated": "2020-10-30T09:42:39.168Z"
  }
}

The response received after a render status request is submitted. The response includes details about status of a render and the output URL.

Properties

Name	Type	Required	Restrictions	Description
success	boolean	true	none	`true` if status available, else `false`.
message	string	true	none	`OK` or an error message.
response	RenderResponseData	true	none	`RenderResponse` or an error message.

RenderResponseData

{
  "id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
  "owner": "5ca6hu7s9k",
  "plan": "basic",
  "status": "done",
  "error": "",
  "duration": 8.5,
  "renderTime": 9433.44,
  "url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
  "poster": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7-poster.jpg",
  "thumbnail": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7-thumb.jpg",
  "data": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  },
  "created": "2020-10-30T09:42:29.446Z",
  "updated": "2020-10-30T09:42:39.168Z"
}

The response data returned with the RenderResponse including status and URL.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The id of the render task in UUID format.
owner	string	true	none	The owner id of the render task.
plan	string	false	none	The customer subscription plan.
status	string	true	none	The status of the render task. `queued` - render is queued waiting to be rendered `fetching` - assets are being fetched `preprocessing` - video assets are being processed for compatibility `rendering` - the asset is being rendered `generating` - AI/media generation is in progress `saving` - the final asset is being saved to storage `done` - the asset is ready to be downloaded `failed` - there was an error rendering the asset
error	string	false	none	An error message, only displayed if an error occurred.
duration	number	false	none	The output video or audio length in seconds.
renderTime	number	false	none	The time taken to render the asset in milliseconds.
url	string	false	none	The URL of the final asset. This will only be available if status is done. This is a temporary URL and will be deleted after 24 hours. By default all assets are copied to the Shotstack hosting and CDN destination.
poster	string¦null	false	none	The URL of the poster image if requested. This will only be available if status is done.
thumbnail	string¦null	false	none	The URL of the thumbnail image if requested. This will only be available if status is done.
data	Edit	false	none	The timeline and output data to be rendered.
created	string	false	none	The time the render task was initially queued.
updated	string	false	none	The time the render status was last updated.

Enumerated Values

Property	Value
status	queued
status	fetching
status	preprocessing
status	rendering
status	generating
status	saving
status	done
status	failed

TemplateResponse

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Template Successfully Created",
    "id": "f5493c17-d01f-445c-bb49-535fae65f219"
  }
}

The response received after a template is submitted. The template is saved and a unique template id is returned.

Properties

Name	Type	Required	Restrictions	Description
success	boolean	true	none	`true` if successfully created, else `false`.
message	string	true	none	`Created`, `Bad Request` or an error message.
response	TemplateResponseData	true	none	`TemplateResponseData` or an error message.

TemplateResponseData

{
  "message": "Template Successfully Created",
  "id": "f5493c17-d01f-445c-bb49-535fae65f219"
}

The response data returned with the TemplateResponse.

Properties

Name	Type	Required	Restrictions	Description
message	string	true	none	Success response message or error details.
id	string	true	none	The unique id of the template in UUID format.

TemplateDataResponse

{
  "success": true,
  "message": "OK",
  "response": {
    "id": "f5493c17-d01f-445c-bb49-535fae65f219",
    "name": "My template",
    "owner": "5ca6hu7s9k",
    "template": {
      "timeline": {
        "soundtrack": {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
          "effect": "fadeIn",
          "volume": 0
        },
        "background": "string",
        "fonts": [
          {
            "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
          }
        ],
        "tracks": [
          {
            "clips": [
              {
                "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                  "prompt": "Slowly zoom out and orbit left around the object.",
                  "model": "seedance-2.0-text-to-video",
                  "options": {
                    "resolution": "720p",
                    "duration": "8",
                    "generateAudio": true
                  },
                  "transcode": false,
                  "trim": 2,
                  "volume": 0.5,
                  "volumeEffect": "none",
                  "speed": 1,
                  "crop": {
                    "top": 0.15,
                    "bottom": 0.15,
                    "left": 1,
                    "right": 1
                  },
                  "chromaKey": {
                    "color": "#00b140",
                    "threshold": 150,
                    "halo": 100
                  }
                },
                "start": 2,
                "length": 5,
                "fit": "cover",
                "scale": 0.5,
                "width": 800,
                "height": 600,
                "position": "top",
                "offset": {
                  "x": 0.1,
                  "y": -0.2
                },
                "transition": {
                  "in": "none",
                  "out": "none"
                },
                "effect": "zoomIn",
                "filter": "greyscale",
                "opacity": 0.5,
                "transform": {
                  "rotate": {
                    "angle": 45
                  },
                  "skew": {
                    "x": 0.5,
                    "y": 0.5
                  },
                  "flip": {
                    "horizontal": true,
                    "vertical": true
                  }
                },
                "alias": "MY_VIDEO_CLIP"
              }
            ]
          }
        ],
        "cache": true
      },
      "output": {
        "format": "mp4",
        "resolution": "hd",
        "aspectRatio": "16:9",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fps": 25,
        "scaleTo": "preview",
        "quality": "medium",
        "repeat": true,
        "mute": false,
        "range": {
          "start": 3,
          "length": 6
        },
        "poster": {
          "capture": 1
        },
        "thumbnail": {
          "capture": 1,
          "scale": 0.3
        },
        "destinations": [
          {
            "provider": "shotstack",
            "exclude": false
          }
        ]
      },
      "merge": [
        {
          "find": "NAME",
          "replace": "Jane"
        }
      ],
      "callback": "https://my-server.com/callback.php",
      "disk": "local",
      "instance": "s1"
    }
  }
}

The template data including the template name and Edit.

Properties

Name	Type	Required	Restrictions	Description
success	boolean	true	none	`true` if successfully returned, else `false`.
message	string	true	none	`OK`, `Bad Request` or an error message.
response	TemplateDataResponseData	true	none	`TemplateDataResponseData` or an error message.

TemplateDataResponseData

{
  "id": "f5493c17-d01f-445c-bb49-535fae65f219",
  "name": "My template",
  "owner": "5ca6hu7s9k",
  "template": {
    "timeline": {
      "soundtrack": {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
        "effect": "fadeIn",
        "volume": 0
      },
      "background": "string",
      "fonts": [
        {
          "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
        }
      ],
      "tracks": [
        {
          "clips": [
            {
              "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "prompt": "Slowly zoom out and orbit left around the object.",
                "model": "seedance-2.0-text-to-video",
                "options": {
                  "resolution": "720p",
                  "duration": "8",
                  "generateAudio": true
                },
                "transcode": false,
                "trim": 2,
                "volume": 0.5,
                "volumeEffect": "none",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 1,
                  "right": 1
                },
                "chromaKey": {
                  "color": "#00b140",
                  "threshold": 150,
                  "halo": 100
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0.5,
              "width": 800,
              "height": 600,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "none",
                "out": "none"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0.5,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              },
              "alias": "MY_VIDEO_CLIP"
            }
          ]
        }
      ],
      "cache": true
    },
    "output": {
      "format": "mp4",
      "resolution": "hd",
      "aspectRatio": "16:9",
      "size": {
        "width": 1200,
        "height": 800
      },
      "fps": 25,
      "scaleTo": "preview",
      "quality": "medium",
      "repeat": true,
      "mute": false,
      "range": {
        "start": 3,
        "length": 6
      },
      "poster": {
        "capture": 1
      },
      "thumbnail": {
        "capture": 1,
        "scale": 0.3
      },
      "destinations": [
        {
          "provider": "shotstack",
          "exclude": false
        }
      ]
    },
    "merge": [
      {
        "find": "NAME",
        "replace": "Jane"
      }
    ],
    "callback": "https://my-server.com/callback.php",
    "disk": "local",
    "instance": "s1"
  }
}

The response data returned with the TemplateDataResponse.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The unique id of the template in UUID format.
name	string	true	none	The template name.
owner	string	true	none	The owner id of the templates.
template	Edit	true	none	The Edit template.

TemplateListResponse

{
  "success": true,
  "message": "OK",
  "response": {
    "owner": "5ca6hu7s9k",
    "templates": [
      {
        "id": "f5493c17-d01f-445c-bb49-535fae65f219",
        "name": "My template",
        "created": "2022-06-10T12:50:21.455Z",
        "updated": "2022-06-22T08:24:30.168Z"
      }
    ]
  }
}

A list of previously saved templates.

Properties

Name	Type	Required	Restrictions	Description
success	boolean	true	none	`true` if successfully returned, else `false`.
message	string	true	none	`OK`, `Bad Request` or an error message.
response	TemplateListResponseData	true	none	`TemplateListResponseData` or an error message.

TemplateListResponseData

{
  "owner": "5ca6hu7s9k",
  "templates": [
    {
      "id": "f5493c17-d01f-445c-bb49-535fae65f219",
      "name": "My template",
      "created": "2022-06-10T12:50:21.455Z",
      "updated": "2022-06-22T08:24:30.168Z"
    }
  ]
}

The response data returned with the TemplateListResponse.

Properties

Name	Type	Required	Restrictions	Description
owner	string	true	none	The owner id of the templates.
templates	[TemplateListResponseItem]	true	none	The list of templates.

TemplateListResponseItem

{
  "id": "f5493c17-d01f-445c-bb49-535fae65f219",
  "name": "My template",
  "created": "2022-06-10T12:50:21.455Z",
  "updated": "2022-06-22T08:24:30.168Z"
}

The individual template item returned with the TemplateListResponseData templates list.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The unique id of the template in UUID format.
name	string	true	none	The template name
created	string	false	none	The time the template was created.
updated	string	false	none	The time the template was last updated.

ProbeResponse

{
  "success": true,
  "message": "Created",
  "response": {}
}

The response received after a probe request is submitted. The probe requests returns data from FFprobe formatted as JSON.

Properties

Name	Type	Required	Restrictions	Description
success	boolean	true	none	`true` if media successfully read, else `false`.
message	string	true	none	`Created`, `Bad Request` or an error message.
response	object	true	none	The response from FFprobe in JSON format.

AssetResponse

{
  "data": {
    "type": "asset",
    "attributes": {
      "id": "a4482cbf-e321-42a2-ac8b-947d26886840",
      "owner": "5ca6hu7s9k",
      "region": "au",
      "renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
      "providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
      "filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
      "url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
      "status": "ready",
      "created": "2021-06-30T09:42:29.446Z",
      "updated": "2021-06-30T09:42:30.168Z"
    }
  }
}

The response returned by the Serve API get asset request. Includes details of a hosted video, image, audio file, thumbnail or poster image. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	AssetResponseData	true	none	An asset resource.

AssetRenderResponse

{
  "data": [
    {
      "type": "asset",
      "attributes": {
        "id": "a4482cbf-e321-42a2-ac8b-947d26886840",
        "owner": "5ca6hu7s9k",
        "region": "au",
        "renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
        "providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
        "filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
        "url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
        "status": "ready",
        "created": "2021-06-30T09:42:29.446Z",
        "updated": "2021-06-30T09:42:30.168Z"
      }
    }
  ]
}

The response returned by the Serve API get asset by render id request. The response is an array of asset resources, including video, image, audio, thumbnail and poster image. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	[AssetResponseData]	true	none	An array of asset resources grouped by render id.

AssetResponseData

{
  "type": "asset",
  "attributes": {
    "id": "a4482cbf-e321-42a2-ac8b-947d26886840",
    "owner": "5ca6hu7s9k",
    "region": "au",
    "renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
    "providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
    "filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
    "url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
    "status": "ready",
    "created": "2021-06-30T09:42:29.446Z",
    "updated": "2021-06-30T09:42:30.168Z"
  }
}

The type of resource (an asset) and attributes of the asset.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of resource, in this case it is an assets.
attributes	AssetResponseAttributes	true	none	The asset attributes including render id, url, filename, file size, etc...

AssetResponseAttributes

{
  "id": "a4482cbf-e321-42a2-ac8b-947d26886840",
  "owner": "5ca6hu7s9k",
  "region": "au",
  "renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
  "providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
  "filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
  "url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
  "status": "ready",
  "created": "2021-06-30T09:42:29.446Z",
  "updated": "2021-06-30T09:42:30.168Z"
}

The list of asset attributes and their values.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The unique id of the hosted asset in UUID format.
owner	string	true	none	The owner id of the asset.
region	string	false	none	The region the asset is hosted, currently only `au` (Australia).
renderId	string	false	none	The original render id that created the asset in UUID format. Multiple assets can share the same render id.
providerId	string	false	none	The third party id of an asset transferred to an external provider, i.e. Mux, YouTube or S3. If the provider is Shotstack, the providerID is the same as the asset id.
filename	string	false	none	The asset file name.
url	string	false	none	The asset file name.
status	string	true	none	The status of the asset. `importing` - the asset is being copied to the hosting service `ready` - the asset is ready to be served to users `failed` - the asset failed to copy or delete `deleted` - the asset has been deleted
created	string	false	none	The time the asset was created.
updated	string	false	none	The time the asset status was last updated.

Enumerated Values

Property	Value
status	importing
status	ready
status	failed
status	deleted

TransferResponse

{
  "data": {
    "type": "asset",
    "attributes": {
      "id": "018e8937-5015-75ee-aab6-03f214981133",
      "owner": "5ca6hu7s9k",
      "status": "queued",
      "created": "2023-09-28T11:17:32.226Z"
    }
  }
}

The response returned by the Serve API transfer asset request. The response includes the ID and transfer status. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	TransferResponseData	true	none	An asset transfer resource.

TransferResponseData

{
  "type": "asset",
  "attributes": {
    "id": "018e8937-5015-75ee-aab6-03f214981133",
    "owner": "5ca6hu7s9k",
    "status": "queued",
    "created": "2023-09-28T11:17:32.226Z"
  }
}

The type of resource (an asset) and the transfer attributes. Returned with TransferResponse.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	The type of resource, in this case it is an asset.
attributes	TransferResponseAttributes	false	none	The attributes of the asset transfer including the status.

TransferResponseAttributes

{
  "id": "018e8937-5015-75ee-aab6-03f214981133",
  "owner": "5ca6hu7s9k",
  "status": "queued",
  "created": "2023-09-28T11:17:32.226Z"
}

The transfer request attributes inlcudling the user specified ID and status. Returned with TransferResponseData.

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	The user provided ID for the asset
owner	string	false	none	The attributes of the asset transfer including the status.
status	string	false	none	The status of the asset transfer. `queued` - the transfer request has been queued `failed` - the transfer request failed
created	string	false	none	The time the asset transfer was created.

Enumerated Values

Property	Value
status	queued
status	failed

QueuedSourceResponse

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

The response returned by the Ingest API fetch source request. Includes the id of the source file. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	QueuedSourceResponseData	true	none	A source resource.

QueuedSourceResponseData

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

The type of resource (a source) and the newly created source id. Returned with QueuedSourceResponse.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of resource, in this case it is a source.
id	string	true	none	The source id.

SourceListResponse

{
  "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-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
        "status": "ready",
        "outputs": {
          "renditions": [
            {
              "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
              "status": "ready",
              "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
              "executionTime": 4120.36,
              "transformation": {
                "format": "mp4",
                "size": {
                  "width": 1200,
                  "height": 800
                },
                "fit": "crop",
                "resolution": "hd",
                "quality": 70,
                "fps": 25,
                "speed": {
                  "speed": 1.5,
                  "preservePitch": false
                },
                "keyframeInterval": 10,
                "fixOffset": true,
                "fixRotation": true,
                "enhance": {
                  "audio": {
                    "provider": "dolby",
                    "options": {}
                  }
                },
                "filename": "my-video"
              },
              "width": 1920,
              "height": 1080,
              "duration": 25.86,
              "fps": 23.967
            }
          ]
        },
        "width": 1920,
        "height": 1080,
        "duration": 25.86,
        "fps": 23.967,
        "created": "2023-01-02T01:47:18.973Z",
        "updated": "2023-01-02T01:47:37.260Z"
      }
    }
  ]
}

A list of all ingested source files fetched or uploaded to a users account.

Properties

Name	Type	Required	Restrictions	Description
data	[SourceResponseData]	true	none	An array of ingested source files.

SourceResponse

{
  "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-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
      "status": "ready",
      "outputs": {
        "renditions": [
          {
            "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
            "status": "ready",
            "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
            "executionTime": 4120.36,
            "transformation": {
              "format": "mp4",
              "size": {
                "width": 1200,
                "height": 800
              },
              "fit": "crop",
              "resolution": "hd",
              "quality": 70,
              "fps": 25,
              "speed": {
                "speed": 1.5,
                "preservePitch": false
              },
              "keyframeInterval": 10,
              "fixOffset": true,
              "fixRotation": true,
              "enhance": {
                "audio": {
                  "provider": "dolby",
                  "options": {
                    "preset": "studio"
                  }
                }
              },
              "filename": "my-video"
            },
            "width": 1920,
            "height": 1080,
            "duration": 25.86,
            "fps": 23.967
          }
        ]
      },
      "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 returned by the Ingest API get source request. Includes details of the ingested source file. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	SourceResponseData	true	none	A source resource.

SourceResponseData

{
  "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-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
    "status": "ready",
    "outputs": {
      "renditions": [
        {
          "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
          "status": "ready",
          "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
          "executionTime": 4120.36,
          "transformation": {
            "format": "mp4",
            "size": {
              "width": 1200,
              "height": 800
            },
            "fit": "crop",
            "resolution": "hd",
            "quality": 70,
            "fps": 25,
            "speed": {
              "speed": 1.5,
              "preservePitch": false
            },
            "keyframeInterval": 10,
            "fixOffset": true,
            "fixRotation": true,
            "enhance": {
              "audio": {
                "provider": "dolby",
                "options": {
                  "preset": "studio"
                }
              }
            },
            "filename": "my-video"
          },
          "width": 1920,
          "height": 1080,
          "duration": 25.86,
          "fps": 23.967
        }
      ]
    },
    "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 type of resource (a source), it's id and attributes of the source file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of resource, in this case it is a source.
id	string	true	none	The source file id.
attributes	SourceResponseAttributes	true	none	The source attributes including its url, status, width, height, duration, etc...

SourceResponseAttributes

{
  "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-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
  "status": "ready",
  "outputs": {
    "renditions": [
      {
        "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
        "status": "ready",
        "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
        "executionTime": 4120.36,
        "transformation": {
          "format": "mp4",
          "size": {
            "width": 1200,
            "height": 800
          },
          "fit": "crop",
          "resolution": "hd",
          "quality": 70,
          "fps": 25,
          "speed": {
            "speed": 1.5,
            "preservePitch": false
          },
          "keyframeInterval": 10,
          "fixOffset": true,
          "fixRotation": true,
          "enhance": {
            "audio": {
              "provider": "dolby",
              "options": {
                "preset": "studio"
              }
            }
          },
          "filename": "my-video"
        },
        "width": 1920,
        "height": 1080,
        "duration": 25.86,
        "fps": 23.967
      }
    ]
  },
  "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 id and attributes of the source file.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The source id.
owner	string	true	none	The owner id of the source file.
input	string	false	none	The original URL of an ingested source file, where it originated. Only displayed for files ingested using the fetch source endpoint. Not displayed for direct uploads.
source	string	false	none	The URL of the source file hosted by Shotstack. The file at the URL can be used by the Edit API. Source file URL's consist of a base URL (AWS bucket), owner id, source id and a file named source. The extension varies depending on the type of file ingested.
status	any	false	none	The status of the source file ingestion task. `queued` - ingestion task is queued waiting to be fetched `importing` - the source file is being downloaded `ready` - the source file has been ingested and stored `failed` - there was an error ingesting the source file `deleted` - the source file has been deleted
outputs	OutputsResponse	false	none	The list of outputs generated from the source file. Currently supports renditions which are versions of the source file with different transformations applied.
width	integer	false	none	The width in pixels of the ingested source file, if a video or image.
height	integer	false	none	The height in pixels of the ingested source file, if a video or image.
duration	number(float)	false	none	The duration in seconds of the ingested source file, if a video or audio file.
fps	number(float)	false	none	The frame rate in frames per second of the source file, if a video file.
created	string	false	none	The time the ingestion task was initially queued.
updated	string	false	none	The time the ingestion status was last updated.

Enumerated Values

Property	Value
status	queued
status	importing
status	ready
status	failed
status	deleted
status	overwritten

OutputsResponse

{
  "renditions": [
    {
      "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
      "status": "ready",
      "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
      "executionTime": 4120.36,
      "transformation": {
        "format": "mp4",
        "size": {
          "width": 1200,
          "height": 800
        },
        "fit": "crop",
        "resolution": "hd",
        "quality": 70,
        "fps": 25,
        "speed": {
          "speed": 1.5,
          "preservePitch": false
        },
        "keyframeInterval": 10,
        "fixOffset": true,
        "fixRotation": true,
        "enhance": {
          "audio": {
            "provider": "dolby",
            "options": {
              "preset": "studio"
            }
          }
        },
        "filename": "my-video"
      },
      "width": 1920,
      "height": 1080,
      "duration": 25.86,
      "fps": 23.967
    }
  ]
}

The list of outputs generated from the source file. Currently supports renditions which are versions of the source file with different transformations applied.

Properties

Name	Type	Required	Restrictions	Description
renditions	[RenditionResponseAttributes]	false	none	The list of renditions generated from the source file.

RenditionResponseAttributes

{
  "id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
  "status": "ready",
  "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
  "executionTime": 4120.36,
  "transformation": {
    "format": "mp4",
    "size": {
      "width": 1200,
      "height": 800
    },
    "fit": "crop",
    "resolution": "hd",
    "quality": 70,
    "fps": 25,
    "speed": {
      "speed": 1.5,
      "preservePitch": false
    },
    "keyframeInterval": 10,
    "fixOffset": true,
    "fixRotation": true,
    "enhance": {
      "audio": {
        "provider": "dolby",
        "options": {
          "preset": "studio"
        }
      }
    },
    "filename": "my-video"
  },
  "width": 1920,
  "height": 1080,
  "duration": 25.86,
  "fps": 23.967
}

The id and attributes of the generated rendition file.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The rendition id.
status	any	false	none	The status of the rendition transformation task. `waiting` - rendition task is waiting for source file to become available `queued` - rendition task is queued waiting to be processed `processing` - the rendition is being processed `ready` - the rendition is ready to be downloaded `failed` - there was an error creating the rendition `deleted` - the rendition has been deleted
url	string	false	none	The URL of the rendition file hosted by Shotstack. The file at the URL can be used by the Edit API. Source file URL's consist of a base URL (AWS bucket), owner id, source id and a file name with the rendition id and extension.
executionTime	number(float)	false	none	The time in milliseconds it took to process the rendition.
transformation	Rendition	false	none	The transformation applied to the source file to create the rendition.
width	integer	false	none	The width in pixels of the ingested source file, if a video or image.
height	integer	false	none	The height in pixels of the ingested source file, if a video or image.
duration	number(float)	false	none	The duration in seconds of the ingested source file, if a video or audio file.
fps	number(float)	false	none	The frame rate in frames per second of the source file, if a video file.

Enumerated Values

Property	Value
status	queued
status	importing
status	ready
status	failed
status	deleted
status	overwritten

UploadResponse

{
  "data": {
    "type": "upload",
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
    "attributes": {
      "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
      "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
      "expires": "2023-01-02T02:47:37.260Z"
    }
  }
}

The response returned by the Ingest API direct upload request. Includes the id of the file and the signed url to send the binary file to. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	UploadResponseData	true	none	An upload resource.

UploadResponseData

{
  "type": "upload",
  "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
  "attributes": {
    "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
    "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
    "expires": "2023-01-02T02:47:37.260Z"
  }
}

The type of resource (an upload), it's id and attributes of the upload request.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of resource, in this case it is an upload.
id	string	true	none	The upload file id.
attributes	UploadResponseAttributes	true	none	The upload attributes including the signed URL.

UploadResponseAttributes

{
  "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
  "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
  "expires": "2023-01-02T02:47:37.260Z"
}

The id and attributes of the upload file including the signed URL to send the binary file data to.

Properties

Name	Type	Required	Restrictions	Description
id	string	true	none	The source id.
url	string	true	none	The signed URL to use in a PUT request to send the binary file to.
expires	string	true	none	The time the upload request will expire. The signed URL will expire after one hour. Upload must complete within one hour.

IngestErrorResponse

{
  "errors": [
    {
      "status": "400",
      "title": "Validation Error",
      "detail": "\"url\" is required"
    }
  ]
}

Error response data for validation and other errors returned by the Ingest API.

Properties

Name	Type	Required	Restrictions	Description
errors	[IngestErrorResponseData]	true	none	An array of errors.

IngestErrorResponseData

{
  "status": "400",
  "title": "Validation Error",
  "detail": "\"url\" is required"
}

Individual errors returned by the Ingest API.

Properties

Name	Type	Required	Restrictions	Description
status	string	true	none	The http status code.
title	string	true	none	A short summary of the error.
detail	string	true	none	A detailed description of the error.