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.

Create API - https://api.shotstack.io/create/{version}
Generate images, videos, voice overs and text using built in and third party generative AI providers.

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

• https://api.shotstack.io/create/{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": [
          {
            "asset": {
              "type": "video",
              "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
              "trim": 2,
              "volume": 1,
              "volumeEffect": "fadeIn",
              "speed": 1,
              "crop": {
                "top": 0.15,
                "bottom": 0.15,
                "left": 0,
                "right": 0
              }
            },
            "start": 2,
            "length": 5,
            "fit": "cover",
            "scale": 0,
            "position": "top",
            "offset": {
              "x": 0.1,
              "y": -0.2
            },
            "transition": {
              "in": "fade",
              "out": "fade"
            },
            "effect": "zoomIn",
            "filter": "greyscale",
            "opacity": 0,
            "transform": {
              "rotate": {
                "angle": 45
              },
              "skew": {
                "x": 0.5,
                "y": 0.5
              },
              "flip": {
                "horizontal": true,
                "vertical": true
              }
            }
          }
        ]
      }
    ],
    "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"
};
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.

Base URL: https://api.shotstack.io/{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": [
          {
            "asset": {
              "type": "video",
              "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
              "trim": 2,
              "volume": 1,
              "volumeEffect": "fadeIn",
              "speed": 1,
              "crop": {
                "top": 0.15,
                "bottom": 0.15,
                "left": 0,
                "right": 0
              }
            },
            "start": 2,
            "length": 5,
            "fit": "cover",
            "scale": 0,
            "position": "top",
            "offset": {
              "x": 0.1,
              "y": -0.2
            },
            "transition": {
              "in": "fade",
              "out": "fade"
            },
            "effect": "zoomIn",
            "filter": "greyscale",
            "opacity": 0,
            "transform": {
              "rotate": {
                "angle": 45
              },
              "skew": {
                "x": 0.5,
                "y": 0.5
              },
              "flip": {
                "horizontal": true,
                "vertical": true
              }
            }
          }
        ]
      }
    ],
    "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"
}

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/{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
                },
                "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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  }
};
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/{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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  }
}

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/{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/{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": [
              {
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                  "trim": 2,
                  "volume": 1,
                  "volumeEffect": "fadeIn",
                  "speed": 1,
                  "crop": {
                    "top": 0.15,
                    "bottom": 0.15,
                    "left": 0,
                    "right": 0
                  }
                },
                "start": 2,
                "length": 5,
                "fit": "cover",
                "scale": 0,
                "position": "top",
                "offset": {
                  "x": 0.1,
                  "y": -0.2
                },
                "transition": {
                  "in": "fade",
                  "out": "fade"
                },
                "effect": "zoomIn",
                "filter": "greyscale",
                "opacity": 0,
                "transform": {
                  "rotate": {
                    "angle": 45
                  },
                  "skew": {
                    "x": 0.5,
                    "y": 0.5
                  },
                  "flip": {
                    "horizontal": true,
                    "vertical": true
                  }
                }
              }
            ]
          }
        ],
        "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"
    }
  }
}

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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  }
};
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/{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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  }
}

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/{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/{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/{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

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,
        "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,
        "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,
                "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,
              "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

Create

The Create API generates assets and media files using Generative AI services like text-to-speech and text-to-avatar. A native text-to-speech service is included as well as integrations with third party providers. Third party services include HeyGen text-to-avatar, ElevenLabs text-to-speech and D-ID text-to-avatar. Assets can be used with the Edit API or downloaded and used independently.

Generate Asset

Code samples

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

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

const fetch = require('node-fetch');
const inputBody = {
  "provider": "shotstack",
  "options": {
    "type": "text-to-speech",
    "text": "This is a text to speech example generated by Shotstack",
    "voice": "Matthew",
    "language": "en-US",
    "newscaster": false
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'x-api-key':'API_KEY'
};

fetch('https://api.shotstack.io/edit/{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/edit/{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/edit/{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/edit/{version}/assets', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{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/edit/{version}/assets", data)
    req.Header = headers

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

POST /assets

Generate an asset using a Shotstack or third party provider. Chose the provider, type of asset and provide prompts, inputs and options to generate the asset. Once generated the asset can be used with the Edit API or downloaded.

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

Body parameter

{
  "provider": "shotstack",
  "options": {
    "type": "text-to-speech",
    "text": "This is a text to speech example generated by Shotstack",
    "voice": "Matthew",
    "language": "en-US",
    "newscaster": false
  }
}

Parameters

Name	In	Type	Required	Description
body	body	GeneratedAsset	true	Generate an asset using the specified provider, type and options.

Example responses

201 Response

{
  "data": {
    "type": "asset",
    "id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
    "attributes": {
      "owner": "5ca6hu7s9k",
      "provider": "shotstack",
      "type": "text-to-speech",
      "url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
      "status": "done",
      "created": "2023-01-02T01:47:18.973Z",
      "updated": "2023-01-02T01:47:37.260Z"
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	The generated asset details	GeneratedAssetResponse
400	Bad Request	A list of validation and other errors	GeneratedAssetErrorResponse

Get Generated Asset

Code samples

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

GET https://api.shotstack.io/edit/{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/edit/{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/edit/{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/edit/{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/edit/{version}/assets/{id}', headers = headers)

print(r.json())

URL obj = new URL("https://api.shotstack.io/edit/{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/edit/{version}/assets/{id}", data)
    req.Header = headers

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

GET /assets/{id}

Get the generated assets status, url and details by ID.

Base URL: https://api.shotstack.io/create/{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": "asset",
    "id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
    "attributes": {
      "owner": "5ca6hu7s9k",
      "provider": "shotstack",
      "type": "text-to-speech",
      "url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
      "status": "done",
      "created": "2023-01-02T01:47:18.973Z",
      "updated": "2023-01-02T01:47:37.260Z"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The generated asset details	GeneratedAssetResponse

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": [
          {
            "asset": {
              "type": "video",
              "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
              "trim": 2,
              "volume": 1,
              "volumeEffect": "fadeIn",
              "speed": 1,
              "crop": {
                "top": 0.15,
                "bottom": 0.15,
                "left": 0,
                "right": 0
              }
            },
            "start": 2,
            "length": 5,
            "fit": "cover",
            "scale": 0,
            "position": "top",
            "offset": {
              "x": 0.1,
              "y": -0.2
            },
            "transition": {
              "in": "fade",
              "out": "fade"
            },
            "effect": "zoomIn",
            "filter": "greyscale",
            "opacity": 0,
            "transform": {
              "rotate": {
                "angle": 45
              },
              "skew": {
                "x": 0.5,
                "y": 0.5
              },
              "flip": {
                "horizontal": true,
                "vertical": true
              }
            }
          }
        ]
      }
    ],
    "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"
}

An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format.

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

Enumerated Values

Property	Value
disk	local
disk	mount

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": [
        {
          "asset": {
            "type": "video",
            "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
            "trim": 2,
            "volume": 1,
            "volumeEffect": "fadeIn",
            "speed": 1,
            "crop": {
              "top": 0.15,
              "bottom": 0.15,
              "left": 0,
              "right": 0
            }
          },
          "start": 2,
          "length": 5,
          "fit": "cover",
          "scale": 0,
          "position": "top",
          "offset": {
            "x": 0.1,
            "y": -0.2
          },
          "transition": {
            "in": "fade",
            "out": "fade"
          },
          "effect": "zoomIn",
          "filter": "greyscale",
          "opacity": 0,
          "transform": {
            "rotate": {
              "angle": 45
            },
            "skew": {
              "x": 0.5,
              "y": 0.5
            },
            "flip": {
              "horizontal": true,
              "vertical": true
            }
          }
        }
      ]
    }
  ],
  "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.
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
}

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": [
    {
      "asset": {
        "type": "video",
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
        "trim": 2,
        "volume": 1,
        "volumeEffect": "fadeIn",
        "speed": 1,
        "crop": {
          "top": 0.15,
          "bottom": 0.15,
          "left": 0,
          "right": 0
        }
      },
      "start": 2,
      "length": 5,
      "fit": "cover",
      "scale": 0,
      "position": "top",
      "offset": {
        "x": 0.1,
        "y": -0.2
      },
      "transition": {
        "in": "fade",
        "out": "fade"
      },
      "effect": "zoomIn",
      "filter": "greyscale",
      "opacity": 0,
      "transform": {
        "rotate": {
          "angle": 45
        },
        "skew": {
          "x": 0.5,
          "y": 0.5
        },
        "flip": {
          "horizontal": true,
          "vertical": true
        }
      }
    }
  ]
}

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

{
  "asset": {
    "type": "video",
    "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
    "trim": 2,
    "volume": 1,
    "volumeEffect": "fadeIn",
    "speed": 1,
    "crop": {
      "top": 0.15,
      "bottom": 0.15,
      "left": 0,
      "right": 0
    }
  },
  "start": 2,
  "length": 5,
  "fit": "cover",
  "scale": 0,
  "position": "top",
  "offset": {
    "x": 0.1,
    "y": -0.2
  },
  "transition": {
    "in": "fade",
    "out": "fade"
  },
  "effect": "zoomIn",
  "filter": "greyscale",
  "opacity": 0,
  "transform": {
    "rotate": {
      "angle": 45
    },
    "skew": {
      "x": 0.5,
      "y": 0.5
    },
    "flip": {
      "horizontal": true,
      "vertical": true
    }
  }
}

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
asset	Asset	true	none	The type of asset to display for the duration of the Clip. Value must be one of: VideoAsset ImageAsset TitleAsset HtmlAsset AudioAsset LumaAsset
start	number	true	none	The start position of the Clip on the timeline, in seconds.
length	number	true	none	The length, in seconds, the Clip should play for.
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	number	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.
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. 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	number	false	none	Sets the opacity of the Clip where 1 is opaque and 0 is transparent.
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.

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	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",
  "trim": 2,
  "volume": 1,
  "volumeEffect": "fadeIn",
  "speed": 1,
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 0,
    "right": 0
  }
}

The type of asset to display for the duration of the Clip. Value must be one of:

• VideoAsset
• ImageAsset
• TitleAsset
• HtmlAsset
• AudioAsset
• LumaAsset

Properties

oneOf

Name	Type	Required	Restrictions	Description
anonymous	VideoAsset	false	none	The VideoAsset is used to create video sequences from video files. The src must be a publicly accessible URL to a video resource such as an mp4 file.

xor

Name	Type	Required	Restrictions	Description
anonymous	ImageAsset	false	none	The ImageAsset is used to create video from images to compose an image. The src must be a publicly accessible URL to an image resource such as a jpg or png file.

xor

Name	Type	Required	Restrictions	Description
anonymous	TitleAsset	false	none	Notice: The title asset is deprecated, use the HTML asset 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	HtmlAsset	false	none	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	AudioAsset	false	none	The AudioAsset is used to add sound effects and audio at specific intervals on the timeline. The src must be a publicly accessible URL to an audio resource such as an mp3 file.

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.

VideoAsset

{
  "type": "video",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
  "trim": 2,
  "volume": 1,
  "volumeEffect": "fadeIn",
  "speed": 1,
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 0,
    "right": 0
  }
}

The VideoAsset is used to create video sequences from video files. The src must be a publicly accessible URL to a video resource such as an mp4 file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to video for videos.
src	string	true	none	The video source URL. The URL must be publicly accessible or include credentials.
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	number	false	none	Set the volume for the video clip between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1).
volumeEffect	string	false	none	The volume effect 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.

Enumerated Values

Property	Value
volumeEffect	fadeIn
volumeEffect	fadeOut
volumeEffect	fadeInFadeOut

ImageAsset

{
  "type": "image",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
  "crop": {
    "top": 0.15,
    "bottom": 0.15,
    "left": 0,
    "right": 0
  }
}

The ImageAsset is used to create video from images to compose an image. The src must be a publicly accessible URL to an image resource such as a jpg or png file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to image for images.
src	string	true	none	The image source URL. The URL must be publicly accessible or include credentials.
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.

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 title asset is deprecated, use the HTML asset 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
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

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"
}

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
position	top
position	topRight
position	right
position	bottomRight
position	bottom
position	bottomLeft
position	left
position	topLeft
position	center

AudioAsset

{
  "type": "audio",
  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/sound.mp3",
  "trim": 0,
  "volume": 1,
  "speed": 1,
  "effect": "fadeIn"
}

The AudioAsset is used to add sound effects and audio at specific intervals on the timeline. The src must be a publicly accessible URL to an audio resource such as an mp3 file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset - set to audio for audio assets.
src	string	true	none	The audio source URL. The URL must be publicly accessible or include credentials.
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	number	false	none	Set the volume for the audio clip between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1).
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
effect	fadeIn
effect	fadeOut
effect	fadeInFadeOut

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.

Transition

{
  "in": "fade",
  "out": "fade"
}

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	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	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	number(float)	false	none	Offset an asset on the horizontal axis (left or right), range varies from -10 to 10. Positive numbers move the asset right, negative left. For all assets except titles the distance moved is relative to the width of the viewport - i.e. an X offset of 0.5 will move the asset half the screen width to the right.
y	number(float)	false	none	Offset an asset on the vertical axis (up or down), range varies from -10 to 10. Positive numbers move the asset up, negative down. For all assets except titles the distance moved is relative to the height of the viewport - i.e. an Y offset of 0.5 will move the asset up half the screen height.

Crop

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

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 0 and 3. Over 3 the clip will be skewed 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	integer	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.

SkewTransformation

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

Skew a clip so its edges are sheared at an angle. Use values between 0 and 3. Over 3 the clip will be skewed almost flat.

Properties

Name	Type	Required	Restrictions	Description
x	number(float)	false	none	Skew the clip along it's x axis.
y	number(float)	false	none	Skew the clip along it's y axis.

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.

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.

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

The following destinations are available:

• ShotstackDestination
• MuxDestination
• S3Destination

Properties

anyOf

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

or

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

or

Name	Type	Required	Restrictions	Description
anonymous	S3Destination	false	none	Send rendered videos 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.

ShotstackDestination

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

Send rendered 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 rendered 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 rendered 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 rendered assets 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 rendered videos 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 rendered 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 render ID filename. Note: omit the file extension as this will be appended depending n 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.

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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  }
}

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.

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,
        "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. The following destinations are available: ShotstackDestination MuxDestination S3Destination
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,
      "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,
  "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.
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.

GeneratedAsset

{
  "provider": "shotstack",
  "options": {
    "type": "text-to-speech",
    "text": "This is a text to speech example generated by Shotstack",
    "voice": "Matthew",
    "language": "en-US",
    "newscaster": false
  }
}

A generated asset is a media asset created by the Create API. You can use native or third party providers to generate video, audio and image files using Generative AI services like text-to-speech and text-to-avatar. The following providers are currently available:

• ShotstackGeneratedAsset
• DIDGeneratedAsset
• ElevenLabsGeneratedAsset
• HeyGenGeneratedAsset

Properties

oneOf

Name	Type	Required	Restrictions	Description
anonymous	ShotstackGeneratedAsset	false	none	Generate assets using the native Shotstack provider. Shotstack provides a text-to-speech and a text-to-image service.

xor

Name	Type	Required	Restrictions	Description
anonymous	DIDGeneratedAsset	false	none	Generate assets using D-ID. D-ID provide a text-to-avatar service.

xor

Name	Type	Required	Restrictions	Description
anonymous	ElevenLabsGeneratedAsset	false	none	Generate assets using ElevenLabs. ElevenLabs provide a text-to-speech service.

xor

Name	Type	Required	Restrictions	Description
anonymous	HeyGenGeneratedAsset	false	none	Generate assets using HeyGen. HeyGen provide a text-to-avatar service.

ShotstackGeneratedAsset

{
  "provider": "shotstack",
  "options": {
    "type": "text-to-speech",
    "text": "This is a text to speech example generated by Shotstack",
    "voice": "Matthew",
    "language": "en-US",
    "newscaster": false
  }
}

Generate assets using the native Shotstack provider. Shotstack provides a text-to-speech and a text-to-image service.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The name of the provider - set to shotstack for Shotstack.
options	ShotstackGeneratedAssetOptions	true	none	Options and configuration for the native Shotstack services.

Enumerated Values

Property	Value
provider	shotstack

ShotstackGeneratedAssetOptions

{
  "type": "text-to-speech",
  "text": "This is a text to speech example generated by Shotstack",
  "voice": "Matthew",
  "language": "en-US",
  "newscaster": false
}

Generate assets using the native Shotstack provider AI services.

The following AI generation services are available:

• ShotstackTextToSpeechOptions
• ShotstackTextToImageOptions

Properties

oneOf

Name	Type	Required	Restrictions	Description
anonymous	ShotstackTextToSpeechOptions	false	none	Options for the Shotstack text-to-speech service. Set the text to be converted to speech and choose a voice to set the speaking style. The output will be generated as an MP3 audio file.

xor

Name	Type	Required	Restrictions	Description
anonymous	ShotstackTextToImageOptions	false	none	Options for the Shotstack text-to-image service. Set a text prompt to generate anb image from. The output will be generated as a PNG file.

ShotstackTextToSpeechOptions

{
  "type": "text-to-speech",
  "text": "This is a text to speech example generated by Shotstack",
  "voice": "Matthew",
  "language": "en-US",
  "newscaster": false
}

Options for the Shotstack text-to-speech service. Set the text to be converted to speech and choose a voice to set the speaking style. The output will be generated as an MP3 audio file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset to generate - 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. You must pair the correct voice with the correct language. For each language there is a language code that must be set in the language property. The voice must be available for the language code or the conversion will fail. i.e. To use the voice Zeina for Arabic you must set the language to arb. Select a voice from the list of available voices, the language code is in brackets: Arabic - Gulf (ar-AE) Hala Dutch - Belgian (nl-BE) Lisa Catalan (ca-ES) Arlet Chinese - Cantonese (yue-CN) Hiujin Chinese - Mandarin (cmn-CN) Zhiyu Danish (da-DK) Sofie Dutch (nl-NL) Laura English - Australian (en-AU) Olivia English - British (en-GB) Amy Emma Brian Arthur English - Indian (en-IN) Kajal English - Ireland (en-IE) Niamh English - New Zealand (en-NZ) Aria English - South African (en-ZA) Ayanda English - US (en-US) Ivy Joanna Kendra Kimberly Salli Joey Justin Kevin Matthew Ruth Stephen Finnish (fi-FI) Suvi French (fr-FR) Léa Rémi French - Canadian (fr-CA) Gabrielle Liam German (de-DE) Vicki Daniel German - Austrian (de-AT) Hannah Hindi (hi-IN) Kajal Italian (it-IT) Bianca Adriano Japanese (ja-JP) Takumi Kazuha Tomoko Korean (ko-KR) Seoyeon Norwegian (nb-NO) Ida Polish (pl-PL) Ola Portuguese - Brazilian (pt-BR) Camila Vitória or Vitoria Thiago Portuguese - European (pt-PT) Inês or Ines Spanish (es-ES) Lucia Sergio Spanish - Mexican (es-MX) Mia Andrés Spanish - US (es-US) Lupe Pedro Swedish (sv-SE) Elin
language	string	false	none	The language code for the text-to-speech conversion. You must pair the correct language with the correct voice (see voice parameter above). Select a language from the list of available languages: cmn-CN da-DK de-DE en-AU en-GB en-IN en-US es-ES es-MX es-US fr-CA fr-FR it-IT ja-JP hi-IN ko-KR nb-NO nl-NL pl-PL pt-BR pt-PT sv-SE en-NZ en-ZA ca-ES de-AT yue-CN ar-AE fi-FI
newscaster	boolean	false	none	Set the voice to newscaster mode. *Only Matthew and Joanna for US English (en-US), Lupe for US Spanish (es-US), and Amy for British English (en-GB) are available in the newscaster voice.

Enumerated Values

Property	Value
type	text-to-speech
voice	Hala
voice	Lisa
voice	Arlet
voice	Hiujin
voice	Zhiyu
voice	Sofie
voice	Laura
voice	Olivia
voice	Amy
voice	Emma
voice	Brian
voice	Arthur
voice	Kajal
voice	Niamh
voice	Aria
voice	Ayanda
voice	Ivy
voice	Joanna
voice	Kendra
voice	Kimberly
voice	Salli
voice	Joey
voice	Justin
voice	Kevin
voice	Matthew
voice	Ruth
voice	Stephen
voice	Suvi
voice	Léa
voice	Rémi
voice	Gabrielle
voice	Liam
voice	Vicki
voice	Daniel
voice	Hannah
voice	Kajal
voice	Bianca
voice	Adriano
voice	Takumi
voice	Kazuha
voice	Tomoko
voice	Seoyeon
voice	Ida
voice	Ola
voice	Camila
voice	Vitória
voice	Vitoria
voice	Thiago
voice	Inês
voice	Ines
voice	Lucia
voice	Sergio
voice	Mia
voice	Andrés
voice	Lupe
voice	Pedro
voice	Elin
language	cmn-CN
language	da-DK
language	de-DE
language	en-AU
language	en-GB
language	en-IN
language	en-US
language	es-ES
language	es-MX
language	es-US
language	fr-CA
language	fr-FR
language	it-IT
language	ja-JP
language	hi-IN
language	ko-KR
language	nb-NO
language	nl-NL
language	pl-PL
language	pt-BR
language	pt-PT
language	sv-SE
language	en-NZ
language	en-ZA
language	ca-ES
language	de-AT
language	yue-CN
language	ar-AE
language	fi-FI

ShotstackTextToImageOptions

{
  "type": "text-to-image",
  "prompt": "A detailed photograph of Mars, showcasing its orange-red surface",
  "width": 512,
  "height": 512
}

Options for the Shotstack text-to-image service. Set a text prompt to generate anb image from. The output will be generated as a PNG file.

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	true	none	The width of the image in pixels.
height	integer	true	none	The height of the image in pixels.

Enumerated Values

Property	Value
type	text-to-image

DIDGeneratedAsset

{
  "provider": "d-id",
  "options": {
    "type": "text-to-avatar",
    "text": "I am an avatar generated by D-ID using a text prompt",
    "avatar": "jack",
    "background": "#ffffff"
  }
}

Generate assets using D-ID. D-ID provide a text-to-avatar service.

Properties

Name	Type	Required	Restrictions	Description
provider	string	true	none	The name of the provider - set to d-id for D-ID.
options	DIDGeneratedAssetOptions	true	none	Options and configuration for the D-ID text-to-avatar service.

Enumerated Values

Property	Value
provider	d-id

DIDGeneratedAssetOptions

{
  "type": "text-to-avatar",
  "text": "I am an avatar generated by D-ID using a text prompt",
  "avatar": "jack",
  "background": "#ffffff"
}

Generate assets using the third party D-ID provider AI services.

The following AI generation services are available:

• DidTextToAvatarOptions

Properties

None

DIDTextToAvatarOptions

{
  "type": "text-to-avatar",
  "text": "I am an avatar generated by D-ID using a text prompt",
  "avatar": "jack",
  "background": "#ffffff"
}

Options for the D-ID text-to-avatar service. Set the text to be converted to an avatar and configure the avatar and background. The output will be generated as an MP4 video file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset to generate - set to text-to-avatar for text-to-avatar.
text	string	true	none	The text or script that the avatar will narrate.
avatar	string	true	none	The avatar character to generate. Select from the list of available avatars: jack lana lily matt rian
background	string	false	none	The background color of the video.

Enumerated Values

Property	Value
type	text-to-avatar
avatar	jack
avatar	lana
avatar	lily
avatar	matt
avatar	rian

ElevenLabsGeneratedAsset

{
  "provider": "elevenlabs",
  "options": {
    "type": "text-to-speech",
    "text": "This is a text to speech example generated by ElevenLabs",
    "voice": "Adam"
  }
}

Generate assets using ElevenLabs. ElevenLabs provide a text-to-speech service.

Properties

Name	Type	Required	Restrictions	Description
provider	string	false	none	The name of the provider - set to elevenlabs for ElevenLabs.
options	ElevenLabsGeneratedAssetOptions	false	none	Options and configuration for the ElevenLabs text-to-speech service.

Enumerated Values

Property	Value
provider	elevenlabs

ElevenLabsGeneratedAssetOptions

{
  "type": "text-to-speech",
  "text": "This is a text to speech example generated by ElevenLabs",
  "voice": "Adam"
}

Generate assets using the third party ElevenLabs provider AI services.

The following AI generation services are available:

• ElevenLabsTextToSpeechOptions

Properties

None

ElevenLabsTextToSpeechOptions

{
  "type": "text-to-speech",
  "text": "This is a text to speech example generated by ElevenLabs",
  "voice": "Adam"
}

Options for the ElevenLabs text-to-speech service. Set the text to be converted to speech and choose a voice to set the speaking style. The output will be generated as an MP3 audio file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset to generate - 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. Select a voice from the list of available voices: Adam Antoni Arnold Bella Domi Elli Josh Rachel Sam

Enumerated Values

Property	Value
type	text-to-speech
voice	Adam
voice	Antoni
voice	Arnold
voice	Bella
voice	Domi
voice	Elli
voice	Josh
voice	Rachel
voice	Sam

HeyGenGeneratedAsset

{
  "provider": "heygen",
  "options": {
    "type": "text-to-avatar",
    "text": "I am an avatar generated by HeyGen using a text prompt",
    "avatar": "Angela",
    "voice": "Abbi - Natural",
    "avatarStyle": "normal",
    "background": "#ffffff",
    "ratio": "16:9",
    "test": true
  }
}

Generate assets using HeyGen. HeyGen provide a text-to-avatar service.

Properties

Name	Type	Required	Restrictions	Description
provider	string	false	none	The name of the provider - set to heygen for HeyGen.
options	HeyGenGeneratedAssetOptions	false	none	Options and configuration for the HeyGen text-to-avatar service.

Enumerated Values

Property	Value
provider	heygen

HeyGenGeneratedAssetOptions

{
  "type": "text-to-avatar",
  "text": "I am an avatar generated by HeyGen using a text prompt",
  "avatar": "Angela",
  "voice": "Abbi - Natural",
  "avatarStyle": "normal",
  "background": "#ffffff",
  "ratio": "16:9",
  "test": true
}

Generate assets using the third party HeyGen provider AI services.

The following AI generation services are available:

• HeyGenTextToAvatarOptions

Properties

None

HeyGenTextToAvatarOptions

{
  "type": "text-to-avatar",
  "text": "I am an avatar generated by HeyGen using a text prompt",
  "avatar": "Angela",
  "voice": "Abbi - Natural",
  "avatarStyle": "normal",
  "background": "#ffffff",
  "ratio": "16:9",
  "test": true
}

Options for the HeyGen text-to-avatar service. Set the text to be converted to an avatar and configure the avatars voice, speaking style, appearance and background. The output will be generated as an MP4 video file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of asset to generate - set to text-to-avatar for text-to-avatar.
text	string	true	none	The text or script that the avatar will narrate.
avatar	string	true	none	The avatar character to generate. Select from the list of available avatars: Angela Bill Daisy Derek Eva Jake Jeff Jerome Joon Kayla Kent Luna Mark Matthew Monica Peter Selina Tanya Thomas Tina Tyler Vanessa Vera Wilson Zoey
voice	string	true	none	The avatars voice and speaking style. Select from the list of available voices: Abb- - Natural Adam - Natural Aiston - Friendly Alice - Newscaster Alison - Cheerful Amber - Friendly Amy - Warm Ana - Cheerful Antoni - Friendly Aria - Newscaster Arnold - Cheerful Arthur - Natural Bella - Friendly Belle - Natural Brandon - Warm Brian - Natural Bruce - Natural Cerise - Cheerful Christopher - Calm Clara - Professional Connor - Natural Dahlia - Friendly Davis - Professional Dean - Natural Delbert - Cheerful Edward - Friendly Elaine - Calm Emily - Natural Emma - Newscaster Eric - Newscaster Grace - Natural Hailey - Calm Indira - Cheerful Isabella - Cheerful Jacob - Natural Jahmai - Friendly Jane - Serious Jason - Serious Jelle - Friendly Jen - Natural Jenny - Professional Jodi - Cheerful Joey - Calm Johan - Friendly Josie - Cheerful Keanan - Natural Keith - Cheerful Kellie - Friendly Lauren - Friendly Leah - Natural Liam - Professional Libby - Natural Lily - Professional Lucas - Natural Luke - Professional Luna - Natural Marieke - Natural Matthew - Professional Michelle - Natural Mitchell - Natural Molly - Newscaster Monica - Calm Natasha - Professional Neerja - Newscaster Noah - Serious Oliver - Newscaster Olivia - Calm Paul - Natural Prabhat - Natural Raveena - Natural Rudi - Friendly Ryan - Professional Sam - Natural Sara - Cheerful Sherry - Friendly Sonia - Warm Thomas - Natural Todd - Professional Tony - Professional Tracy - Cheerful Wayne - Natural Wilder - Natural Wille - Natural William - Friendly
avatarStyle	string	false	none	The display style of the avatar, a rectangle normal or circular circle background. Defaults to normal.
background	string	false	none	The background color of the video. Defaults to #ffffff.
ratio	string	false	none	The aspect ratio of the video, 16:9 horizontal or 9:16 vertical. Defaults to 16:9.
test	boolean	false	none	A boolean flag indicating whether the video is for testing purposes. See the "test" parameter in HeyGen for more details.

Enumerated Values

Property	Value
type	text-to-avatar
avatar	Angela
avatar	Bill
avatar	Daisy
avatar	Derek
avatar	Eva
avatar	Jake
avatar	Jeff
avatar	Jerome
avatar	Joon
avatar	Kayla
avatar	Kent
avatar	Luna
avatar	Mark
avatar	Matthew
avatar	Monica
avatar	Peter
avatar	Selina
avatar	Tanya
avatar	Thomas
avatar	Tina
avatar	Tyler
avatar	Vanessa
avatar	Vera
avatar	Wilson
avatar	Zoey
voice	Abbi - Natural
voice	Adam - Natural
voice	Aiston - Friendly
voice	Alice - Newscaster
voice	Alison - Cheerful
voice	Amber - Friendly
voice	Amy - Warm
voice	Ana - Cheerful
voice	Antoni - Friendly
voice	Aria - Newscaster
voice	Arnold - Cheerful
voice	Arthur - Natural
voice	Bella - Friendly
voice	Belle - Natural
voice	Brandon - Warm
voice	Brian - Natural
voice	Bruce - Natural
voice	Cerise - Cheerful
voice	Christopher - Calm
voice	Clara - Professional
voice	Connor - Natural
voice	Dahlia - Friendly
voice	Davis - Professional
voice	Dean - Natural
voice	Delbert - Cheerful
voice	Edward - Friendly
voice	Elaine - Calm
voice	Emily - Natural
voice	Emma - Newscaster
voice	Eric - Newscaster
voice	Grace - Natural
voice	Hailey - Calm
voice	Indira - Cheerful
voice	Isabella - Cheerful
voice	Jacob - Natural
voice	Jahmai - Friendly
voice	Jane - Serious
voice	Jason - Serious
voice	Jelle - Friendly
voice	Jen - Natural
voice	Jenny - Professional
voice	Jodi - Cheerful
voice	Joey - Calm
voice	Johan - Friendly
voice	Josie - Cheerful
voice	Keanan - Natural
voice	Keith - Cheerful
voice	Kellie - Friendly
voice	Lauren - Friendly
voice	Leah - Natural
voice	Liam - Professional
voice	Libby - Natural
voice	Lily - Professional
voice	Lucas - Natural
voice	Luke - Professional
voice	Luna - Natural
voice	Marieke - Natural
voice	Matthew - Professional
voice	Michelle - Natural
voice	Mitchell - Natural
voice	Molly - Newscaster
voice	Monica - Calm
voice	Natasha - Professional
voice	Neerja - Newscaster
voice	Noah - Serious
voice	Oliver - Newscaster
voice	Olivia - Calm
voice	Paul - Natural
voice	Prabhat - Natural
voice	Raveena - Natural
voice	Rudi - Friendly
voice	Ryan - Professional
voice	Sam - Natural
voice	Sara - Cheerful
voice	Sherry - Friendly
voice	Sonia - Warm
voice	Thomas - Natural
voice	Todd - Professional
voice	Tony - Professional
voice	Tracy - Cheerful
voice	Wayne - Natural
voice	Wilder - Natural
voice	Wille - Natural
voice	William - Friendly
avatarStyle	normal
avatarStyle	circle
ratio	16:9
ratio	9:16

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": [
              {
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                  "trim": 2,
                  "volume": 1,
                  "volumeEffect": "fadeIn",
                  "speed": 1,
                  "crop": {
                    "top": 0.15,
                    "bottom": 0.15,
                    "left": 0,
                    "right": 0
                  }
                },
                "start": 2,
                "length": 5,
                "fit": "cover",
                "scale": 0,
                "position": "top",
                "offset": {
                  "x": 0.1,
                  "y": -0.2
                },
                "transition": {
                  "in": "fade",
                  "out": "fade"
                },
                "effect": "zoomIn",
                "filter": "greyscale",
                "opacity": 0,
                "transform": {
                  "rotate": {
                    "angle": 45
                  },
                  "skew": {
                    "x": 0.5,
                    "y": 0.5
                  },
                  "flip": {
                    "horizontal": true,
                    "vertical": true
                  }
                }
              }
            ]
          }
        ],
        "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"
    },
    "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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  },
  "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 rendering - the asset is being rendered 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	rendering
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": [
              {
                "asset": {
                  "type": "video",
                  "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                  "trim": 2,
                  "volume": 1,
                  "volumeEffect": "fadeIn",
                  "speed": 1,
                  "crop": {
                    "top": 0.15,
                    "bottom": 0.15,
                    "left": 0,
                    "right": 0
                  }
                },
                "start": 2,
                "length": 5,
                "fit": "cover",
                "scale": 0,
                "position": "top",
                "offset": {
                  "x": 0.1,
                  "y": -0.2
                },
                "transition": {
                  "in": "fade",
                  "out": "fade"
                },
                "effect": "zoomIn",
                "filter": "greyscale",
                "opacity": 0,
                "transform": {
                  "rotate": {
                    "angle": 45
                  },
                  "skew": {
                    "x": 0.5,
                    "y": 0.5
                  },
                  "flip": {
                    "horizontal": true,
                    "vertical": true
                  }
                }
              }
            ]
          }
        ],
        "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"
    }
  }
}

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": [
            {
              "asset": {
                "type": "video",
                "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
                "trim": 2,
                "volume": 1,
                "volumeEffect": "fadeIn",
                "speed": 1,
                "crop": {
                  "top": 0.15,
                  "bottom": 0.15,
                  "left": 0,
                  "right": 0
                }
              },
              "start": 2,
              "length": 5,
              "fit": "cover",
              "scale": 0,
              "position": "top",
              "offset": {
                "x": 0.1,
                "y": -0.2
              },
              "transition": {
                "in": "fade",
                "out": "fade"
              },
              "effect": "zoomIn",
              "filter": "greyscale",
              "opacity": 0,
              "transform": {
                "rotate": {
                  "angle": 45
                },
                "skew": {
                  "x": 0.5,
                  "y": 0.5
                },
                "flip": {
                  "horizontal": true,
                  "vertical": true
                }
              }
            }
          ]
        }
      ],
      "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"
  }
}

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,
                "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,
              "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,
            "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,
          "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	string	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,
        "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,
    "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.

GeneratedAssetResponse

{
  "data": {
    "type": "asset",
    "id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
    "attributes": {
      "owner": "5ca6hu7s9k",
      "provider": "shotstack",
      "type": "text-to-speech",
      "url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
      "status": "done",
      "created": "2023-01-02T01:47:18.973Z",
      "updated": "2023-01-02T01:47:37.260Z"
    }
  }
}

The response returned by the Create API generate asset and get generated asset requests. Includes status and details of the generated asset. The response follows the json:api specification.

Properties

Name	Type	Required	Restrictions	Description
data	GeneratedAssetResponseData	true	none	A generated asset resource.

GeneratedAssetResponseData

{
  "type": "asset",
  "id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
  "attributes": {
    "owner": "5ca6hu7s9k",
    "provider": "shotstack",
    "type": "text-to-speech",
    "url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
    "status": "done",
    "created": "2023-01-02T01:47:18.973Z",
    "updated": "2023-01-02T01:47:37.260Z"
  }
}

The type of resource (an asset), it's id and attributes of the generated file.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of resource, in this case it is an asset.
id	string	true	none	The generated asset id.
attributes	GeneratedAssetResponseAttributes	true	none	The generated asset attributes including its url, status, provider, type, etc...

GeneratedAssetResponseAttributes

{
  "owner": "5ca6hu7s9k",
  "provider": "shotstack",
  "type": "text-to-speech",
  "url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
  "status": "done",
  "created": "2023-01-02T01:47:18.973Z",
  "updated": "2023-01-02T01:47:37.260Z"
}

The id and attributes of the generated asset.

Properties

Name	Type	Required	Restrictions	Description
owner	string	true	none	The owner id of the asset.
provider	string	true	none	The native or third party provider that generated the asset, shotstack, elevenlabs, heygen or d-id.
type	string	true	none	The type of service used to generate the asset, text-to-speech or text-to-avatar.
url	string	false	none	The URL of the asset file hosted by Shotstack. The file at the URL can be used by the Edit API. Generated asset file URL's consist of a base URL (AWS bucket), owner id, asset id and extension. The extension varies depending on the type of file generated.
status	string	true	none	The status of the asset file generation task. queued - generation task is queued waiting to be processed processing - the asset is being generated by the provider saving - the asset is being saved to Shotstack done - the asset has been generated and stored failed - there was an error generating the asset
created	string	true	none	The time the generate asset task was initially queued.
updated	string	true	none	The time the asset status was last updated.

Enumerated Values

Property	Value
provider	shotstack
provider	elevenlabs
provider	heygen
provider	d-id
type	text-to-speech
type	text-to-avatar
status	queued
status	processing
status	saving
status	done
status	failed

GeneratedAssetErrorResponse

{
  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "\"body/options/text\" is required."
    }
  ]
}

Error response data for validation and other errors returned by the Create API.

Properties

Name	Type	Required	Restrictions	Description
errors	[GeneratedAssetErrorResponseData]	true	none	An array of errors.

GeneratedAssetErrorResponseData

{
  "status": 400,
  "title": "Bad Request",
  "detail": "\"body/options/text\" is required."
}

Individual errors returned by the Create 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.