NAV Navigation
Curl HTTP NodeJS PHP Ruby Python Java Go

Shotstack v1

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

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

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

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

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

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

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

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

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

Base URLs:

Authentication

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

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": "sd",
        "quality": 70,
        "fps": 25,
        "filename": "my-video"
      }
    ]
  },
  "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": "sd",
        "quality": 70,
        "fps": 25,
        "filename": "my-video"
      }
    ]
  },
  "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": "sd",
                "quality": 70,
                "fps": 25,
                "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": "sd",
              "quality": 70,
              "fps": 25,
              "filename": "my-video"
            },
            "width": 1920,
            "height": 1080,
            "duration": 25.86,
            "fps": 23.967
          }
        ]
      },
      "width": 1920,
      "height": 1080,
      "duration": 25.86,
      "fps": 23.967,
      "created": "2023-01-02T01:47:18.973Z",
      "updated": "2023-01-02T01:47:37.260Z"
    }
  }
}

Responses

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

Delete Source

Code samples

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

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

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

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

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

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

 'API_KEY',
);

$client = new \GuzzleHttp\Client();

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

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

 // ...

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

print(r.json())

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

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

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

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

DELETE /sources/{id}

Delete an ingested source file by its id.

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

Parameters

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

Responses

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

Direct Upload

Code samples

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

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

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

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

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

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

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

$client = new \GuzzleHttp\Client();

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

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

 // ...

require 'rest-client'
require 'json'

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

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

p JSON.parse(result)

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

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

print(r.json())

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

package main

import (
       "bytes"
       "net/http"
)

func main() {

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

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

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

POST /upload

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

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

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

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

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

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

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

Example responses

200 Response

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

Responses

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

Schemas

Edit

{
  "timeline": {
    "soundtrack": {
      "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
      "effect": "fadeIn",
      "volume": 0
    },
    "background": "string",
    "fonts": [
      {
        "src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
      }
    ],
    "tracks": [
      {
        "clips": [
          {
            "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": "sd",
    "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:
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:

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": "sd",
  "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 output resolution of the video or image.

  • 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

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.

  • low - slightly reduced quality, smaller file size

  • medium (default) - optimized quality, render speeds and file size

  • high - slightly increased quality, larger 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
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 low
quality medium
quality high

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

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": "sd",
      "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": "sd",
        "quality": 70,
        "fps": 25,
        "filename": "my-video"
      }
    ]
  },
  "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. 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:
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": "sd",
      "quality": 70,
      "fps": 25,
      "filename": "my-video"
    }
  ]
}

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.

Rendition

{
  "format": "mp4",
  "size": {
    "width": 1200,
    "height": 800
  },
  "fit": "crop",
  "resolution": "sd",
  "quality": 70,
  "fps": 25,
  "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)

  • jpg - jpg image file (image only)

  • png - png image file (image only)

  • mp3 - mp3 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 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

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 mp3
format jpg
format png
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

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": "sd",
        "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": "sd",
      "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": "sd",
        "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": "sd",
      "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 render task.
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

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": "sd",
                "quality": 70,
                "fps": 25,
                "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": "sd",
              "quality": 70,
              "fps": 25,
              "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": "sd",
            "quality": 70,
            "fps": 25,
            "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": "sd",
          "quality": 70,
          "fps": 25,
          "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": "sd",
        "quality": 70,
        "fps": 25,
        "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": "sd",
    "quality": 70,
    "fps": 25,
    "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.