Shotstack v1
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Shotstack is a video, image and audio editing service that allows for the automated generation of videos, images and audio using JSON and a RESTful API.
You arrange and configure an edit and POST it to the API which will render your media and provide a file location when complete.
For more details visit shotstack.io or checkout our getting started documentation.
There are three API's, one for editing and generating assets (Edit API), one for managing hosted assets (Serve API) and one for ingesting and transforming source assets (Ingest API).
Each API has it's own base URL and collection of endpoints. Each API uses the same set of API keys.
Edit API - https://api.shotstack.io/edit/{version}
Edit videos, images and audio assets in the cloud using a simple JSON schema and templates.
Serve API - https://api.shotstack.io/serve/{version}
Inspect and manage the hosting of assets generated by the Edit and Ingest APIs.
Ingest API - https://api.shotstack.io/ingest/{version}
Ingest (upload, store and transform) source footage, images, audio and fonts to be used by the Edit API.
Create API - https://api.shotstack.io/create/{version}
Generate images, videos, voice overs and text using built in and third party generative AI providers.
Base URLs:
-
https://api.shotstack.io/edit/{version}
-
version - Set the stage to v1 for production usage without watermarks. Set to stage to use the development sandbox. Default: v1
-
v1
-
stage
-
-
-
https://api.shotstack.io/serve/{version}
-
version - Set the stage to v1 for production usage. Set to stage to use the development sandbox. Default: v1
-
v1
-
stage
-
-
-
https://api.shotstack.io/ingest/{version}
-
version - Set the stage to v1 for production usage. Set to stage to use the development sandbox. Default: v1
-
v1
-
stage
-
-
-
https://api.shotstack.io/create/{version}
-
version - Set the stage to v1 for production usage. Set to stage to use the development sandbox. Default: v1
-
v1
-
stage
-
-
Authentication
- API Key (DeveloperKey)
- Parameter Name: x-api-key, in: header. Set the x-api-key header with your provided key for the correct environment (v1 or stage). Include the header in all calls to the API that are secured with a key.
Edit
The Edit API is used to edit videos, images and audio files in the cloud using a simple to understand JSON schema. Compose an edit using tracks, clips and assets and add transitions, filters, overlays and text. Finally send the JSON to the Edit API to be rendered.
Render Asset
Code samples
# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/render \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
POST https://api.shotstack.io/edit/{version}/render HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/render',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/edit/{version}/render', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/edit/{version}/render',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/edit/{version}/render', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/render");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/render", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /render
Queue and render the contents of an Edit as a video, image or audio file.
Base URL: https://api.shotstack.io/edit/{version}
Body parameter
{
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Edit | true | The video, image or audio edit specified using JSON. |
Example responses
201 Response
{
"success": true,
"message": "Created",
"response": {
"message": "Render Successfully Queued",
"id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | The queued render details | QueuedResponse |
Get Render Status
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/render/{id} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/edit/{version}/render/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/render/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/edit/{version}/render/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/edit/{version}/render/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/edit/{version}/render/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/render/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/render/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /render/{id}
Get the rendering status, temporary asset url and details of a render by ID.
Base URL: https://api.shotstack.io/edit/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the timeline render task in UUID format |
| data | query | boolean | false | Include the data parameter in the response. The data parameter includes the original timeline, output and other settings sent to the API. Note: the default is currently true, this is deprecated and the default will soon be false. If you rely on the data being returned in the response you should explicitly set the parameter to true. |
| merged | query | boolean | false | Used when data is set to true, it will show the merge fields merged in to the data response. |
Example responses
200 Response
{
"success": true,
"message": "OK",
"response": {
"status": "rendering",
"id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"owner": "5ca6hu7s9k",
"url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"data": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeInFadeOut"
},
"background": "#000000",
"tracks": [
{
"clips": [
{
"asset": {
"type": "title",
"text": "Hello World",
"style": "minimal"
},
"start": 0,
"length": 4,
"transition": {
"in": "fade",
"out": "fade"
},
"effect": "slideRight"
},
{
"asset": {
"type": "image",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-image.jpg"
},
"start": 3,
"length": 4,
"effect": "zoomIn",
"filter": "greyscale"
}
]
},
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/my-clip-1.mp4",
"trim": 10.5
},
"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": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/templates',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/edit/{version}/templates', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/edit/{version}/templates',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/edit/{version}/templates', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/templates", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /templates
Save an Edit as a re-usable template. Templates can be retrieved and modified in your application before being rendered. Merge fields can be also used to merge data in to a template and render it in a single request.
Base URL: https://api.shotstack.io/edit/{version}
Body parameter
{
"name": "My template",
"template": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Template | true | Create a template with a name and Edit. |
Example responses
201 Response
{
"success": true,
"message": "Created",
"response": {
"message": "Template Successfully Created",
"id": "f5493c17-d01f-445c-bb49-535fae65f219"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | The saved template status including the id | TemplateResponse |
List Templates
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/templates \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/edit/{version}/templates HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/templates',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/edit/{version}/templates', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/edit/{version}/templates',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/edit/{version}/templates', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/templates", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /templates
Retrieve a list of templates stored against a users account and stage.
Base URL: https://api.shotstack.io/edit/{version}
Example responses
200 Response
{
"success": true,
"message": "OK",
"response": {
"owner": "5ca6hu7s9k",
"templates": [
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"name": "My template",
"created": "2022-06-10T12:50:21.455Z",
"updated": "2022-06-22T08:24:30.168Z"
}
]
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | The list of templates stored against a users account | TemplateListResponse |
Retrieve Template
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/templates/{id} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/edit/{version}/templates/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/templates/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/edit/{version}/templates/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/edit/{version}/templates/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/edit/{version}/templates/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/templates/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /templates/{id}
Retrieve a template by template id.
Base URL: https://api.shotstack.io/edit/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the template in UUID format |
Example responses
200 Response
{
"success": true,
"message": "OK",
"response": {
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"name": "My template",
"owner": "5ca6hu7s9k",
"template": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | The template details including the Edit | TemplateDataResponse |
Update Template
Code samples
# You can also use wget
curl -X PUT https://api.shotstack.io/edit/{version}/templates/{id} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
PUT https://api.shotstack.io/edit/{version}/templates/{id} HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = {
"name": "My template",
"template": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/templates/{id}',
{
method: 'PUT',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PUT','https://api.shotstack.io/edit/{version}/templates/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.put 'https://api.shotstack.io/edit/{version}/templates/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.put('https://api.shotstack.io/edit/{version}/templates/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("PUT", "https://api.shotstack.io/edit/{version}/templates/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
PUT /templates/{id}
Update an existing template by template id.
Base URL: https://api.shotstack.io/edit/{version}
Body parameter
{
"name": "My template",
"template": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Template | true | Update an individual templates name and Edit. Both template name and template must be provided. If the template parameter is omitted a blank template will be saved. |
| id | path | string | true | The id of the template in UUID format |
Example responses
200 Response
{
"success": true,
"message": "OK",
"response": {
"message": "Template Successfully Updated",
"id": "f5493c17-d01f-445c-bb49-535fae65f219"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Update a templates name and Edit | TemplateResponse |
Delete Template
Code samples
# You can also use wget
curl -X DELETE https://api.shotstack.io/edit/{version}/templates/{id} \
-H 'x-api-key: API_KEY'
DELETE https://api.shotstack.io/edit/{version}/templates/{id} HTTP/1.1
Host: api.shotstack.io
const fetch = require('node-fetch');
const headers = {
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/templates/{id}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.shotstack.io/edit/{version}/templates/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'x-api-key' => 'API_KEY'
}
result = RestClient.delete 'https://api.shotstack.io/edit/{version}/templates/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'x-api-key': 'API_KEY'
}
r = requests.delete('https://api.shotstack.io/edit/{version}/templates/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.shotstack.io/edit/{version}/templates/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
DELETE /templates/{id}
Delete a template by its template id.
Base URL: https://api.shotstack.io/edit/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the template in UUID format |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | An empty response signifying the template has been deleted | None |
Render Template
Code samples
# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/templates/render \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
POST https://api.shotstack.io/edit/{version}/templates/render HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = {
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
]
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/templates/render',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/edit/{version}/templates/render', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/edit/{version}/templates/render',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/edit/{version}/templates/render', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/templates/render");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/templates/render", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /templates/render
Render an asset from a template id and optional merge fields. Merge fields can be used to replace placeholder variables within the Edit.
Base URL: https://api.shotstack.io/edit/{version}
Body parameter
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | TemplateRender | true | Render a template by template id. |
Example responses
201 Response
{
"success": true,
"message": "Created",
"response": {
"message": "Render Successfully Queued",
"id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | The queued status including the render id. Check the status of the render using the id and the render status endpoint. | QueuedResponse |
Inspect Media
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/probe/{url} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/edit/{version}/probe/{url} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/probe/{url}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/edit/{version}/probe/{url}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/edit/{version}/probe/{url}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/edit/{version}/probe/{url}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/probe/{url}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/probe/{url}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /probe/{url}
Inspects any media asset (image, video, audio) on the internet using a hosted version of FFprobe. The probe endpoint returns useful information about an asset such as width, height, duration, rotation, framerate, etc...
Base URL: https://api.shotstack.io/edit/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| url | path | string | true | The URL of the media to inspect, must be URL encoded. |
Example responses
200 Response
{
"success": true,
"message": "Created",
"response": {}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | FFprobe response formatted as JSON. | ProbeResponse |
Serve
Assets generated by the Edit API or uploaded via the Ingest API are sent to the Serve API. The Serve API includes a simple hosting service with a CDN or you can send assets to third party services like AWS S3 or Mux. The Serve API includes endpoints to look up assets, where they are hosted and their status.
Get Asset
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/serve/{version}/assets/{id} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/serve/{version}/assets/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/serve/{version}/assets/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/serve/{version}/assets/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/serve/{version}/assets/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/serve/{version}/assets/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/serve/{version}/assets/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/serve/{version}/assets/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /assets/{id}
The Serve API is used to interact with, and delete hosted assets including videos, images, audio files, thumbnails and poster images. Use this endpoint to fetch an asset by asset id. Note that an asset id is unique for each asset and different from the render id.
Base URL: https://api.shotstack.io/serve/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the asset in UUID format |
Example responses
200 Response
{
"data": {
"type": "asset",
"attributes": {
"id": "a4482cbf-e321-42a2-ac8b-947d26886840",
"owner": "5ca6hu7s9k",
"region": "au",
"renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
"filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"status": "ready",
"created": "2021-06-30T09:42:29.446Z",
"updated": "2021-06-30T09:42:30.168Z"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Get asset by asset id | AssetResponse |
Delete Asset
Code samples
# You can also use wget
curl -X DELETE https://api.shotstack.io/serve/{version}/assets/{id} \
-H 'x-api-key: API_KEY'
DELETE https://api.shotstack.io/serve/{version}/assets/{id} HTTP/1.1
Host: api.shotstack.io
const fetch = require('node-fetch');
const headers = {
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/serve/{version}/assets/{id}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.shotstack.io/serve/{version}/assets/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'x-api-key' => 'API_KEY'
}
result = RestClient.delete 'https://api.shotstack.io/serve/{version}/assets/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'x-api-key': 'API_KEY'
}
r = requests.delete('https://api.shotstack.io/serve/{version}/assets/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/serve/{version}/assets/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.shotstack.io/serve/{version}/assets/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
DELETE /assets/{id}
Delete an asset by its asset id. If a render creates multiple assets, such as thumbnail and poster images, each asset must be deleted individually by the asset id.
Base URL: https://api.shotstack.io/serve/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the asset in UUID format |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | An empty response signifying the asset has been deleted | None |
Get Asset by Render ID
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/serve/{version}/assets/render/{id} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/serve/{version}/assets/render/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/serve/{version}/assets/render/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/serve/{version}/assets/render/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/serve/{version}/assets/render/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/serve/{version}/assets/render/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/serve/{version}/assets/render/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/serve/{version}/assets/render/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /assets/render/{id}
A render may generate more than one file, such as a video, thumbnail and poster image. When the assets are created the only known id is the render id returned by the original render request, status request or webhook. This endpoint lets you look up one or more assets by the render id.
Base URL: https://api.shotstack.io/serve/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The render id associated with the asset in UUID format |
Example responses
200 Response
{
"data": [
{
"type": "asset",
"attributes": {
"id": "a4482cbf-e321-42a2-ac8b-947d26886840",
"owner": "5ca6hu7s9k",
"region": "au",
"renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
"filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"status": "ready",
"created": "2021-06-30T09:42:29.446Z",
"updated": "2021-06-30T09:42:30.168Z"
}
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Get one or more assets by render id | AssetRenderResponse |
Transfer Asset
Code samples
# You can also use wget
curl -X POST https://api.shotstack.io/serve/{version}/assets \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
POST https://api.shotstack.io/serve/{version}/assets HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = {
"url": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"id": "018e8937-5015-75ee-aab6-03f214981133",
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/serve/{version}/assets',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/serve/{version}/assets', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/serve/{version}/assets',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/serve/{version}/assets', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/serve/{version}/assets");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/serve/{version}/assets", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /assets
Transfer a file from any publicly available URL to one or more Serve API destinations.
Base URL: https://api.shotstack.io/serve/{version}
Body parameter
{
"url": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"id": "018e8937-5015-75ee-aab6-03f214981133",
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Transfer | true | Fetch an asset from a URL and send it to one or more destinations. |
Example responses
200 Response
{
"data": {
"type": "asset",
"attributes": {
"id": "018e8937-5015-75ee-aab6-03f214981133",
"owner": "5ca6hu7s9k",
"status": "queued",
"created": "2023-09-28T11:17:32.226Z"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | The transfer request details and status | TransferResponse |
Ingest
The Ingest API lets you upload and store your source footage and user generated content in close proximity to the Edit API. Instead of hosting your own assets or building your own uploader you can use the Ingest API. The Ingest API provides endpoints to fetch and upload files and check their status and URLs. All ingested files are available directly from an S3 bucket URL or via CDN (Serve API).
Fetch Source
Code samples
# You can also use wget
curl -X POST https://api.shotstack.io/ingest/{version}/sources \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
POST https://api.shotstack.io/ingest/{version}/sources HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = {
"url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"outputs": {
"renditions": [
{
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
}
],
"transcription": {
"format": "vtt"
}
},
"destinations": {
"provider": "shotstack",
"exclude": false
},
"callback": "https://my-server.com/callback.php"
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/ingest/{version}/sources',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/ingest/{version}/sources', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/ingest/{version}/sources',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/ingest/{version}/sources', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/ingest/{version}/sources", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /sources
Queue a source file to be fetched from a URL and stored by Shotstack. Source files can be videos, images, audio files and fonts. Once ingested, new output renditions can be created from the source file.
Base URL: https://api.shotstack.io/ingest/{version}
Body parameter
{
"url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"outputs": {
"renditions": [
{
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
}
],
"transcription": {
"format": "vtt"
}
},
"destinations": {
"provider": "shotstack",
"exclude": false
},
"callback": "https://my-server.com/callback.php"
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | Source | true | Ingest a video, image, audio or font file from the provided URL. Optionally provide a list of output renditions. |
Example responses
201 Response
{
"data": {
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | The queued source file details | QueuedSourceResponse |
| 400 | Bad Request | A list of validation and other errors | IngestErrorResponse |
List Sources
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/ingest/{version}/sources \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/ingest/{version}/sources HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/ingest/{version}/sources',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/ingest/{version}/sources', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/ingest/{version}/sources',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/ingest/{version}/sources', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/ingest/{version}/sources", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /sources
Retrieve a list of ingested source files stored against a users account and stage.
Base URL: https://api.shotstack.io/ingest/{version}
Example responses
200 Response
{
"data": [
{
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"owner": "5ca6hu7s9k",
"input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
"status": "ready",
"outputs": {
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967,
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | The list of ingested source files stored against a users account | SourceListResponse |
Get Source
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/ingest/{version}/sources/{id} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/ingest/{version}/sources/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/ingest/{version}/sources/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/ingest/{version}/sources/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/ingest/{version}/sources/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/ingest/{version}/sources/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/ingest/{version}/sources/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /sources/{id}
Fetch a source file details and status by its id.
Base URL: https://api.shotstack.io/ingest/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the source file in KSUID format. |
Example responses
200 Response
{
"data": {
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"owner": "5ca6hu7s9k",
"input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
"status": "ready",
"outputs": {
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967,
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Get source file details by id | SourceResponse |
Delete Source
Code samples
# You can also use wget
curl -X DELETE https://api.shotstack.io/ingest/{version}/sources/{id} \
-H 'x-api-key: API_KEY'
DELETE https://api.shotstack.io/ingest/{version}/sources/{id} HTTP/1.1
Host: api.shotstack.io
const fetch = require('node-fetch');
const headers = {
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/ingest/{version}/sources/{id}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.shotstack.io/ingest/{version}/sources/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'x-api-key' => 'API_KEY'
}
result = RestClient.delete 'https://api.shotstack.io/ingest/{version}/sources/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'x-api-key': 'API_KEY'
}
r = requests.delete('https://api.shotstack.io/ingest/{version}/sources/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/ingest/{version}/sources/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("DELETE", "https://api.shotstack.io/ingest/{version}/sources/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
DELETE /sources/{id}
Delete an ingested source file by its id.
Base URL: https://api.shotstack.io/ingest/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the source file in KSUID format. |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | An empty response signifying the ingested source file has been deleted. | None |
Direct Upload
Code samples
# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/upload \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
POST https://api.shotstack.io/edit/{version}/upload HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/upload',
{
method: 'POST',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/edit/{version}/upload', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/edit/{version}/upload',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/edit/{version}/upload', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/upload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/upload", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /upload
Request a signed URL to upload a file to. The response returns a signed URL that you use to upload the file to. The signed URL looks similar to:
In a separate API call, use this signed URL to send a PUT request with the binary file. Using cURL you can use a command like:
curl -X PUT -T video.mp4 {data.attributes.url}
Where video.mp4 is the file you want to upload and {data.attributes.url} is the signed URL returned in the response. The request must be a PUT type.
The SDK does not currently support the PUT request. You can use the SDK to make the request for the signed URL and then use cURL to make the PUT request.
Base URL: https://api.shotstack.io/ingest/{version}
Example responses
200 Response
{
"data": {
"type": "upload",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
"expires": "2023-01-02T02:47:37.260Z"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | The id and signed URL to upload to. | UploadResponse |
Create
The Create API generates assets and media files using Generative AI services like text-to-speech and text-to-avatar. A native text-to-speech service is included as well as integrations with third party providers. Third party services include HeyGen text-to-avatar, ElevenLabs text-to-speech and D-ID text-to-avatar. Assets can be used with the Edit API or downloaded and used independently.
Generate Asset
Code samples
# You can also use wget
curl -X POST https://api.shotstack.io/edit/{version}/assets \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
POST https://api.shotstack.io/edit/{version}/assets HTTP/1.1
Host: api.shotstack.io
Content-Type: application/json
Accept: application/json
const fetch = require('node-fetch');
const inputBody = {
"provider": "shotstack",
"options": {
"type": "text-to-speech",
"text": "This is a text to speech example generated by Shotstack",
"voice": "Matthew",
"language": "en-US",
"newscaster": false
}
};
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/assets',
{
method: 'POST',
body: JSON.stringify(inputBody),
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.shotstack.io/edit/{version}/assets', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.post 'https://api.shotstack.io/edit/{version}/assets',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.post('https://api.shotstack.io/edit/{version}/assets', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/assets");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.shotstack.io/edit/{version}/assets", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /assets
Generate an asset using a Shotstack or third party provider. Chose the provider, type of asset and provide prompts, inputs and options to generate the asset. Once generated the asset can be used with the Edit API or downloaded.
Base URL: https://api.shotstack.io/create/{version}
Body parameter
{
"provider": "shotstack",
"options": {
"type": "text-to-speech",
"text": "This is a text to speech example generated by Shotstack",
"voice": "Matthew",
"language": "en-US",
"newscaster": false
}
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | GeneratedAsset | true | Generate an asset using the specified provider, type and options. |
Example responses
201 Response
{
"data": {
"type": "asset",
"id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
"attributes": {
"owner": "5ca6hu7s9k",
"provider": "shotstack",
"type": "text-to-speech",
"url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
"status": "done",
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | The generated asset details | GeneratedAssetResponse |
| 400 | Bad Request | A list of validation and other errors | GeneratedAssetErrorResponse |
Get Generated Asset
Code samples
# You can also use wget
curl -X GET https://api.shotstack.io/edit/{version}/assets/{id} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
GET https://api.shotstack.io/edit/{version}/assets/{id} HTTP/1.1
Host: api.shotstack.io
Accept: application/json
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.shotstack.io/edit/{version}/assets/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.shotstack.io/edit/{version}/assets/{id}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.shotstack.io/edit/{version}/assets/{id}',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.shotstack.io/edit/{version}/assets/{id}', headers = headers)
print(r.json())
URL obj = new URL("https://api.shotstack.io/edit/{version}/assets/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.shotstack.io/edit/{version}/assets/{id}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /assets/{id}
Get the generated assets status, url and details by ID.
Base URL: https://api.shotstack.io/create/{version}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The id of the source file in KSUID format. |
Example responses
200 Response
{
"data": {
"type": "asset",
"id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
"attributes": {
"owner": "5ca6hu7s9k",
"provider": "shotstack",
"type": "text-to-speech",
"url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
"status": "done",
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | The generated asset details | GeneratedAssetResponse |
Schemas
Edit
{
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| timeline | Timeline | true | none | A timeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time. |
| output | Output | true | none | The output format, render range and type of media to generate. |
| merge | [MergeField] | false | none | An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder {{NAME}} and replace it with the value Jane. |
| callback | string | false | none | An optional webhook callback URL used to receive status notifications when a render completes or fails. Notifications are also sent when a rendered video is sent to an output destination. See webhooks for more details. |
| disk | string | false | none | Notice: This option is now deprecated and will be removed. Disk types are handled automatically. Setting a disk type has no effect. The disk type to use for storing footage and assets for each render. See disk types for more details.
|
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": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"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
|
| 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": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"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": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"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, i.e. a video clip or an image. Choose from one of the available asset types below. |
| start | any | true | none | The start position of the Clip on the timeline. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | The start position of the Clip on the timeline, in seconds. For example, to start the Clip at 2 seconds, set the start value to 2. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | The start position using a smart clip property. Set to auto to automatically play the clip after the previous clip finishes. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| length | any | true | none | The duration the Clip should play for. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | The duration the Clip should play for, in seconds. For example, to play the Clip for 5 seconds, set the length value to 5. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | The duration the Clip should play for using a smart clip property. Set to auto to play the Clip for the duration of the asset. Set to end to display or play the clip to the end of the timeline. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| fit | string | false | none | Set how the asset should be scaled to fit the viewport using one of the following options:
|
| 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.
|
| 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.
Fast or Slow to the effect, e.g. zoomInFast or slideRightSlow. |
| filter | string | false | none | A filter effect to apply to the Clip.
|
| opacity | any | false | none | Offset an asset on the horizontal axis (left or right). Use a number or an array of Tween objects to create a custom animation. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | Sets the opacity of the Clip where 1 is opaque and 0 is transparent. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom animation. Animate the opacity of an asset over time. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| transform | Transformation | false | none | A transformation lets you modify the visual properties of a clip. Available transformations are rotate, skew and flip. Transformations can be combined to create interesting new shapes and effects. |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | auto |
| anonymous | auto |
| anonymous | end |
| 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 | blur |
| filter | boost |
| filter | contrast |
| filter | darken |
| filter | greyscale |
| filter | lighten |
| filter | muted |
| filter | negative |
Asset
{
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
}
The type of asset to display for the duration of the Clip, i.e. a video clip or an image. Choose from one of the available asset types below.
Properties
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | VideoAsset | false | none | The VideoAsset 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 | TextAsset | false | none | The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom Fonts. You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | 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. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | CaptionAsset | false | none | The CaptionAsset is used to add captions (subtitles) to a video. It uses a supplied SRT or VTT file which will be read and burnt to the video. Captions can be applied independently from a video or audio file for greater flexibility with styling and layout. For example you can scale, position or crop a video without modifying the captions. To sync captions with a video or audio file use a Video or Audio with matching start and end time. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | HtmlAsset | false | none | Notice: The HtmlAsset is deprecated, use the TextAsset instead. The HtmlAsset clip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | TitleAsset | false | none | Notice: The TitleAsset is deprecated, use the TextAsset instead. The TitleAsset clip type lets you create video titles from a text string and apply styling and positioning. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShapeAsset | false | none | The ShapeAsset is used to add shapes to a video. The shape can be styled with a fill and a stroke. You can manipulate properties such as rotation to create dynamic effects like a diamond shape or stripes. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | TextToImageAsset | false | none | The TextToImageAsset lets you create a dynamic image from a text prompt. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ImageToVideoAsset | false | none | The ImageToVideoAsset lets you create a video from an image and a text prompt. |
VideoAsset
{
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
}
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 | any | false | none | Set the volume of the video clip. Use a number or an array of Tween objects to create custom volume transitions. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number(float) | false | none | The volume level for the video clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1). |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| volumeEffect | string | false | none | Preset volume effects to apply to the video asset
|
| speed | number(float) | false | none | Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire video (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire video (i.e. original length / 2). |
| crop | Crop | false | none | Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset. |
| chromaKey | ChromaKey | false | none | Chroma key, commonly known as green screen, is a technique that replaces a specific color in a video with a different background image or video, enabling seamless integration of diverse environments. |
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. |
TextAsset
{
"type": "text",
"text": "Hello World",
"width": 400,
"height": 200,
"font": {
"family": "Open Sans",
"color": "#ffffff",
"opacity": 0.8,
"size": 24,
"weight": 400,
"lineHeight": 0.85
},
"background": {
"color": "#000000"
},
"alignment": {
"horizontal": "center",
"vertical": "center"
}
}
The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom Fonts. You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset - set to text for text. |
| text | string | true | none | The text string to display. |
| width | integer | false | none | Set the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box. |
| height | integer | false | none | Set the width of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the height of the bounding box. |
| font | TextFont | false | none | Font styling properties. |
| background | TextBackground | false | none | Background styling properties. |
| alignment | TextAlignment | false | none | Alignment properties. |
AudioAsset
{
"type": "audio",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/sound.mp3",
"trim": 0,
"volume": 0.5,
"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 | any | false | none | Set the volume of the audio clip. Use a number or an array of Tween objects to create custom volume transitions. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number(float) | false | none | The volume level for the audio clip. Range varies from 0 to 1 where 0 is muted and 1 is full volume (defaults to 1). |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom volume effect. Modify the volume of an asset over time. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| speed | number(float) | false | none | Adjust the playback speed of the audio clip between 0 (paused) and 10 (10x normal speed), where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire audio (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire audio (i.e. original length / 2). |
| effect | string | false | none | The effect to apply to the audio asset
|
Enumerated Values
| Property | Value |
|---|---|
| effect | fadeIn |
| effect | fadeOut |
| effect | fadeInFadeOut |
ShapeAsset
{
"type": "shape",
"shape": "rectangle",
"width": 800,
"height": 800,
"fill": {
"color": "#ffffff",
"opacity": 1
},
"stroke": {
"color": "#000000",
"width": 0.8
},
"rectangle": {
"width": 800,
"height": 800,
"cornerRadius": 20
},
"circle": {
"radius": 800
},
"line": {
"length": 100,
"thickness": 4
}
}
The ShapeAsset is used to add shapes to a video. The shape can be styled with a fill and a stroke. You can manipulate properties such as rotation to create dynamic effects like a diamond shape or stripes.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset - set to shape for shape. |
| shape | string | true | none | The shape to display. |
| width | integer | false | none | Sets the width of the bounding box in pixels. This value should be larger than the shape's width. If omitted, the entire viewport width and height will be used. |
| height | integer | false | none | Sets the height of the bounding box in pixels. This value should be larger than the shape's height. If omitted, the entire viewport width and height will be used. |
| fill | object | false | none | Specifies the fill style of the shape. |
| » color | string | false | none | The color of the fill using hexadecimal color notation. |
| » opacity | number | false | none | The opacity of the fill where 1 is opaque and 0 is transparent. |
| stroke | object | false | none | Specifies the stroke style of the shape. |
| » color | string | false | none | The stroke color of the font using hexadecimal color notation. |
| » width | number | false | none | The width of the stroke in pixels. |
| rectangle | object | false | none | Configuration settings for the rectangle shape. Required when shape is set to rectangle. |
| » width | integer | true | none | Set the width of the rectangle shape in pixels. |
| » height | integer | true | none | Set the height of the rectangle shape in pixels. |
| » cornerRadius | integer | false | none | Set the corner radius of the rectangle shape. |
| circle | object | false | none | Configuration settings for the circle shape. Required when shape is set to circle. |
| » radius | integer | true | none | Set the radius of the circle shape in pixels. |
| line | object | false | none | Configuration settings for the line shape. Required when shape is set to line. |
| » length | integer | true | none | Set the length of the line shape in pixels. |
| » thickness | integer | true | none | Set the thickness of the line in pixels. |
Enumerated Values
| Property | Value |
|---|---|
| shape | rectangle |
| shape | circle |
| shape | line |
LumaAsset
{
"type": "luma",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/mask.mp4",
"trim": 0
}
The LumaAsset is used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset - set to luma for luma mattes. |
| src | string | true | none | The luma matte source URL. The URL must be publicly accessible or include credentials. |
| trim | number | false | none | The start trim point of the luma matte clip, in seconds (defaults to 0). Videos will start from the in trim point. A luma matte video will play until the file ends or the Clip length is reached. |
CaptionAsset
{
"type": "caption",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/captions.srt",
"font": {
"family": "Open Sans",
"color": "#ffffff",
"opacity": 0.8,
"size": 24,
"lineHeight": 0.85,
"stroke": "#ff6600",
"strokeWidth": 0.8
},
"background": {
"color": "#000000",
"opacity": 0.4,
"padding": 30,
"borderRadius": 18
},
"margin": {
"top": 0.25,
"left": 0.05,
"right": 0.45
},
"trim": 2,
"speed": 1
}
The CaptionAsset is used to add captions (subtitles) to a video. It uses a supplied SRT or VTT file which will be read and burnt to the video.
Captions can be applied independently from a video or audio file for greater flexibility with styling and layout. For example you can scale, position or crop a video without modifying the captions.
To sync captions with a video or audio file use a Video or Audio with matching start and end time.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset - set to caption for captions. |
| src | string | true | none | The URL to an SRT or VTT subtitles file. The URL must be publicly accessible or include credentials. |
| font | CaptionFont | false | none | Font styling properties. |
| background | CaptionBackground | false | none | Background styling properties. |
| margin | CaptionMargin | false | none | Margin properties. |
| trim | number | false | none | The start trim point of the captions, in seconds (defaults to 0). Remove the trim length from teh start of the captions and allow it to be synced with video or audio. The captions will play until the file ends or the Clip length is reached. |
| speed | number(float) | false | none | Adjust the playback speed of the captions between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire captions (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire captions (i.e. original length / 2). |
TextToImageAsset
{
"type": "text-to-image",
"prompt": "A serene landscape featuring a crystal-clear mountain lake at sunrise. The water reflects the pink and orange sky like a mirror. In the foreground, a majestic pine tree stands tall, its branches framing the view. Snow-capped peaks rise in the distance, their edges softened by a light morning mist. A pair of deer drink from the lake's edge, creating gentle ripples on the otherwise still surface.",
"width": 512,
"height": 512,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
}
}
The TextToImageAsset lets you create a dynamic image from a text prompt.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-image for text-to-image. |
| prompt | string | true | none | The text prompt to generate an image from. |
| width | integer | true | none | The width of the image in pixels. |
| height | integer | true | none | The height of the image in pixels. |
| crop | Crop | false | none | Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-image |
ImageToVideoAsset
{
"type": "image-to-video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
"prompt": "Slowly zoom out and orbit left around the object.",
"aspectRatio": "16:9",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
}
}
The ImageToVideoAsset lets you create a video from an image and a text prompt.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | false | none | The type of asset to generate - set to image-to-video for image-to-video. |
| src | string | false | none | The image source URL. The URL must be publicly accessible or include credentials. |
| prompt | string | false | none | The instructions for modifying the image into a video sequence. |
| aspectRatio | string | false | none | The aspect ratio (shape) of the video output. |
| speed | number(float) | false | none | Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Adjusting the speed will also adjust the duration of the clip and may require you to adjust the Clip length. For example, if you set speed to 0.5, the clip will need to be 2x as long to play the entire video (i.e. original length / 0.5). If you set speed to 2, the clip will need to be half as long to play the entire video (i.e. original length / 2). |
| crop | Crop | false | none | Crop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset. |
Enumerated Values
| Property | Value |
|---|---|
| type | image-to-video |
| aspectRatio | 1:1 |
| aspectRatio | 4:3 |
| aspectRatio | 16:9 |
| aspectRatio | 9:16 |
| aspectRatio | 3:4 |
| aspectRatio | 21:9 |
| aspectRatio | 9:21 |
HtmlAsset
{
"type": "html",
"html": "<p>Hello <b>World</b></p>",
"css": "p { color: #ffffff; } b { color: #ffff00; }",
"width": 400,
"height": 200,
"background": "string",
"position": "top"
}
Notice: The HtmlAsset is deprecated, use the TextAsset instead.
The HtmlAsset clip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset - set to html for HTML. |
| html | string | true | none | The HTML text string. See list of supported HTML tags. |
| css | string | false | none | The CSS text string to apply styling to the HTML. See list of support CSS properties. |
| width | integer | false | none | Set the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box. |
| height | integer | false | none | Set the width of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the height of the bounding box. |
| background | string | false | none | Apply a background color behind the HTML bounding box using. Set the text color using hexadecimal color notation. Transparency is supported by setting the first two characters of the hex string (opposite to HTML), i.e. #80ffffff will be white with 50% transparency. |
| position | string | false | none | Place the HTML in one of nine predefined positions within the HTML area.
|
Enumerated Values
| Property | Value |
|---|---|
| position | top |
| position | topRight |
| position | right |
| position | bottomRight |
| position | bottom |
| position | bottomLeft |
| position | left |
| position | topLeft |
| position | center |
TitleAsset
{
"type": "title",
"text": "Hello World",
"style": "minimal",
"color": "string",
"size": "xx-small",
"background": "#000000",
"position": "top",
"offset": {
"x": 0.1,
"y": -0.2
}
}
Notice: The TitleAsset is deprecated, use the TextAsset 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.
|
| 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.
|
| 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.
|
| 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 |
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:
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:
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 | any | false | none | Offset an asset on the horizontal axis (left or right). Use a number or an array of Tween objects to create a custom animation. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number(float) | false | none | Range varies from -10 to 10. Positive numbers move the asset right, negative left. The distance moved is relative to the width of the viewport - i.e. an X offset of 0.5 will move the asset half the screen width to the right. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom animation. Animate the X offset of an asset over time. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| y | any | false | none | Offset an asset on the vertical axis (up or down). Use a number or an array of Tween objects to create a custom animation. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number(float) | false | none | Range varies from -10 to 10. Positive numbers move the asset up, negative down. The distance moved is relative to the height of the viewport - i.e. an Y offset of 0.5 will move the asset half the screen height up. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom animation. Animate the Y offset of an asset over time. |
Crop
{
"top": 0.15,
"bottom": 0.15,
"left": 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 | any | false | none | Rotate a clip by the specified angle in degrees. Use a number or an array of Tween objects to create a custom animation. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer(float) | false | none | The angle to rotate the clip. Can be 0 to 360, or 0 to -360. Using a positive number rotates the clip clockwise, negative numbers counter-clockwise. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom animation. Animate the rotation of an asset over time. |
SkewTransformation
{
"x": 0.5,
"y": 0.5
}
Skew a clip so its edges are sheared at an angle. Use values between 0 and 3. Over 3 the clip will be skewed almost flat.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| x | any | false | none | Skew the clip along it's x axis. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number(float) | false | none | Range varies from 0 to 3. Positive numbers skew the asset right, negative left. The distance moved is relative to the width of the viewport - i.e. an X skew of 0.5 will skew the asset half the screen width to the right. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom animation. Animate the X skew of an asset over time. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| y | any | false | none | Skew the clip along it's y axis. |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number(float) | false | none | Range varies from 0 to 3. Positive numbers skew the asset up, negative down. The distance moved is relative to the height of the viewport - i.e. an Y skew of 0.5 will skew the asset half the screen height up. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [Tween] | false | none | An array of Tween objects used to create a custom animation. Animate the Y skew of an asset over time. |
FlipTransformation
{
"horizontal": true,
"vertical": true
}
Flip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| horizontal | boolean | false | none | Flip a clip horizontally. |
| vertical | boolean | false | none | Flip a clip vertically. |
TextFont
{
"family": "Open Sans",
"color": "#ffffff",
"opacity": 0.8,
"size": 24,
"weight": 400,
"lineHeight": 0.85
}
Font properties for text.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| family | string | false | none | The font family name. This must be Family name embedded in the font, i.e. "Open Sans". |
| color | string | false | none | The text color using hexadecimal color notation. |
| opacity | number | false | none | The opacity of the text where 1 is opaque and 0 is transparent. |
| size | integer | false | none | The size of the font in pixels (px). |
| weight | integer | false | none | The weight of the font. 100 is lightest, 900 is heaviest (boldest). |
| lineHeight | number | false | none | The line height of the font as a ratio of the font size. |
TextBackground
{
"color": "#000000"
}
Displays a background box behind the text.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| color | string | false | none | The background color using hexadecimal color notation. |
TextAlignment
{
"horizontal": "center",
"vertical": "center"
}
Horizontal and vertical alignment properties for text.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| horizontal | string | false | none | The horizontal alignment of the text. Value must be one of:
|
| vertical | string | false | none | The vertical alignment of the text. Value must be one of:
|
Enumerated Values
| Property | Value |
|---|---|
| horizontal | left |
| horizontal | center |
| horizontal | right |
| vertical | top |
| vertical | center |
| vertical | bottom |
CaptionFont
{
"family": "Open Sans",
"color": "#ffffff",
"opacity": 0.8,
"size": 24,
"lineHeight": 0.85,
"stroke": "#ff6600",
"strokeWidth": 0.8
}
Font properties for captions text.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| family | string | false | none | The font family name. This must be Family name embedded in the font, i.e. "Open Sans". |
| color | string | false | none | The text color using hexadecimal color notation. |
| opacity | number | false | none | The opacity of the text where 1 is opaque and 0 is transparent. |
| size | integer | false | none | The size of the font in pixels (px). |
| lineHeight | number | false | none | The line height of the font as a ratio of the font size. |
| stroke | string | false | none | The stroke color of the font using hexadecimal color notation. |
| strokeWidth | number | false | none | The width of the stroke in pixels. |
CaptionBackground
{
"color": "#000000",
"opacity": 0.4,
"padding": 30,
"borderRadius": 18
}
Displays a background box behind the caption text.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| color | string | false | none | The background color using hexadecimal color notation. |
| opacity | number | false | none | The opacity of the background color. |
| padding | integer | false | none | The padding inside the background box in pixels. |
| borderRadius | integer | false | none | The border radius of the background box in pixels. |
CaptionMargin
{
"top": 0.25,
"left": 0.05,
"right": 0.45
}
The margin properties for captions. Margins are used to position the caption text and background on the screen.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| top | number | false | none | The margin above the text. Pushes captions down the screen. |
| left | number | false | none | The margin to the left of the text. Pushes captions to the right. |
| right | number | false | none | The margin to the right of the text. Pushes captions to the left. |
ChromaKey
{
"color": "#00b140",
"threshold": 150,
"halo": 100
}
Chroma key, commonly known as green screen, is a technique that replaces a specific color in a video with a different background image or video, enabling seamless integration of diverse environments.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| color | string | false | none | The chroma key color as a hex value. For a green screen, use a green hex value. |
| threshold | integer | false | none | Pixels within this distance from the key color are eliminated by setting their alpha values to zero. |
| halo | integer | false | none | Pixels within the halo distance from the threshold boundary are given an increasing alpha value based on their distance from the threshold. |
Tween
{
"from": 0,
"to": 1,
"start": 0,
"length": 3,
"interpolation": "bezier",
"easing": "ease"
}
Use a Tween to animate properties over time. The following properties are currently supported and can be animated:
- Opacity - animate the transparency of a clip.
- Offset - animate the x and y position of a clip.
- Rotation - animate the rotation of a clip.
- Skew - animate the horizontal and vertical shearing effect.
- Volume - animate the audio volume of a clip.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| from | any | false | none | The initial property value at the start of the animation. |
| to | any | false | none | The final property value at the end of the animation. |
| start | number | false | none | The time in seconds when the animation starts, relative to the clip, not the timeline. |
| length | number | false | none | The duration of the animation in seconds. |
| interpolation | string | false | none | The interpolation method to use for the animation. Available options are:
|
| easing | string | false | none | The easing function to use for the animation. Easing controls the rate of change of the animated value, allowing for more natural motion by speeding up or slowing down the animation at different points. Only applicable if interpolation is set to bezier. |
Enumerated Values
| Property | Value |
|---|---|
| interpolation | linear |
| interpolation | bezier |
| interpolation | constant |
| easing | ease |
| easing | easeIn |
| easing | easeOut |
| easing | easeInOut |
| easing | easeInQuad |
| easing | easeInCubic |
| easing | easeInQuart |
| easing | easeInQuint |
| easing | easeInSine |
| easing | easeInExpo |
| easing | easeInCirc |
| easing | easeInBack |
| easing | easeOutQuad |
| easing | easeOutCubic |
| easing | easeOutQuart |
| easing | easeOutQuint |
| easing | easeOutSine |
| easing | easeOutExpo |
| easing | easeOutCirc |
| easing | easeOutBack |
| easing | easeInOutQuad |
| easing | easeInOutCubic |
| easing | easeInOutQuart |
| easing | easeInOutQuint |
| easing | easeInOutSine |
| easing | easeInOutExpo |
| easing | easeInOutCirc |
| easing | easeInOutBack |
MergeField
{
"find": "NAME",
"replace": "Jane"
}
A merge field consists of a key; find, and a value; replace. Merge fields can be used to replace placeholders within the JSON edit to create re-usable templates. Placeholders should be a string with double brace delimiters, i.e. "{{NAME}}". A placeholder can be used for any value within the JSON edit.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| find | string | true | none | The string to find without delimiters. |
| replace | any | true | none | The replacement value. The replacement can be any valid JSON type - string, boolean, number, etc... |
Output
{
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
}
The output format, render range and type of media to generate.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| format | string | true | none | The output format and type of media file to generate.
|
| resolution | string | false | none | The preset output resolution of the video or image. For custom sizes use the size property.
|
| aspectRatio | string | false | none | The aspect ratio (shape) of the video or image. Useful for social media output formats. Options are:
|
| 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.
|
| 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.
|
| 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.
|
| repeat | boolean | false | none | Loop settings for gif files. Set to true to loop, false to play only once. |
| mute | boolean | false | none | Mute the audio track of the output video. Set to true to mute, false to un-mute. |
| range | Range | false | none | Specify a time range to render, i.e. to render only a portion of a video or audio file. Omit this setting to export the entire video. Range can also be used to render a frame at a specific time point - setting a range and output format as jpg will output a single frame image at the range start point. |
| poster | Poster | false | none | Generate a poster image from a specific point on the timeline. |
| thumbnail | Thumbnail | false | none | Generate a thumbnail image from a specific point on the timeline. |
| destinations | [Destinations] | false | none | Specify the storage locations and hosting services to send rendered videos to. |
Enumerated Values
| Property | Value |
|---|---|
| format | mp4 |
| format | gif |
| format | mp3 |
| format | jpg |
| format | png |
| format | bmp |
| resolution | preview |
| resolution | mobile |
| resolution | sd |
| resolution | hd |
| resolution | 1080 |
| resolution | 4k |
| aspectRatio | 16:9 |
| aspectRatio | 9:16 |
| aspectRatio | 1:1 |
| aspectRatio | 4:5 |
| aspectRatio | 4:3 |
| fps | 12 |
| fps | 15 |
| fps | 23.976 |
| fps | 24 |
| fps | 25 |
| fps | 29.97 |
| fps | 30 |
| fps | 48 |
| fps | 50 |
| fps | 59.94 |
| fps | 60 |
| scaleTo | preview |
| scaleTo | mobile |
| scaleTo | sd |
| scaleTo | hd |
| scaleTo | 1080 |
| quality | verylow |
| quality | low |
| quality | medium |
| quality | high |
| quality | veryhigh |
Size
{
"width": 1200,
"height": 800
}
Set a custom size for a video or image in pixels. When using a custom size omit the resolution and aspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| width | integer | false | none | Set a custom width for the video or image file in pixels. Value must be divisible by 2. Maximum video width is 1920px, maximum image width is 4096px. |
| height | integer | false | none | Set a custom height for the video or image file in pixels. Value must be divisible by 2. Maximum video height is 1920px, maximum image height is 4096px. |
Range
{
"start": 3,
"length": 6
}
Specify a time range to render, i.e. to render only a portion of a video or audio file. Omit this setting to export the entire video. Range can also be used to render a frame at a specific time point - setting a range and output format as jpg will output a single frame image at the range start point.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start | number(float) | false | none | The point on the timeline, in seconds, to start the render from - i.e. start at second 3. |
| length | number(float) | false | none | The length of the portion of the video or audio to render - i.e. render 6 seconds of the video. |
Poster
{
"capture": 1
}
Generate a poster image for the video at a specific point from the timeline. The poster image size will match the size of the output video.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| capture | number | true | none | The point on the timeline in seconds to capture a single frame to use as the poster image. |
Thumbnail
{
"capture": 1,
"scale": 0.3
}
Generate a thumbnail image for the video or image at a specific point from the timeline.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| capture | number | true | none | The point on the timeline in seconds to capture a single frame to use as the thumbnail image. |
| scale | number | true | none | Scale the thumbnail size to a fraction of the viewport size - i.e. setting the scale to 0.5 will scale the thumbnail to half the size of the viewport. |
Destinations
{
"provider": "shotstack",
"exclude": false
}
A destination is a location where assets can be sent to for serving or hosting. Videos, images and audio files that are rendered by the Edit API and source and rendition files generated by the Ingest API can be sent to destinations. You can also fetch a file from any public URL and transfer it to a destination. A file can be sent to one or more destinations including 3rd party destinations.
By default all ingested and generated assets are automatically sent to the Shotstack hosting destination. You can opt-out from by setting the Shotstack destination exclude property to true.
Properties
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShotstackDestination | false | none | Send videos and assets to the Shotstack hosting and CDN service. This destination is enabled by default. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | MuxDestination | false | none | Send videos to the Mux video hosting and streaming service. Mux credentials are required and added via the dashboard, not in the request. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | S3Destination | false | none | Send videos and assets to an Amazon S3 bucket. Send files to any region with your own prefix and filename. AWS credentials are required and added via the dashboard, not in the request. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | GoogleCloudStorageDestination | false | none | Send videos and assets to a Google Cloud Storage bucket. Send files with your own prefix and filename. Google Cloud credentials are required and added via the dashboard, not in the request. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | GoogleDriveDestination | false | none | Send rendered videos and assets to the Google Drive cloud storage service. Google Drive uses OAuth and you must authenticate and link your Google account via dashboard, not in the request. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | VimeoDestination | false | none | Send videos to Vimeo video hosting and streaming service. Vimeo credentials are required and added via the dashboard, not in the request. |
ShotstackDestination
{
"provider": "shotstack",
"exclude": false
}
Send videos and assets to the Shotstack hosting and CDN service. This destination is enabled by default.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The destination to send assets to - set to shotstack for Shotstack hosting and CDN. |
| exclude | boolean | false | none | Set to true to opt-out from the Shotstack hosting and CDN service. All files must be downloaded within 24 hours of rendering. |
MuxDestination
{
"provider": "mux",
"options": {
"playbackPolicy": [
"public"
],
"passthrough": "string"
}
}
Send videos to the Mux video hosting and streaming service. Mux credentials are required and added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The destination to send video to - set to mux for Mux. |
| options | MuxDestinationOptions | false | none | Additional Mux configuration and features. |
MuxDestinationOptions
{
"playbackPolicy": [
"public"
],
"passthrough": "string"
}
Pass additional options to control how Mux processes video. Currently supports playback_policy and passthrough options.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| playbackPolicy | [string] | false | none | Sets the Mux playback_policy option. Value is an array of strings - use public, signed, or both. |
| passthrough | string | false | none | Sets the Mux passthrough option. Max 255 characters. |
S3Destination
{
"provider": "s3",
"options": {
"region": "us-east-1",
"bucket": "my-bucket",
"prefix": "my-renders",
"filename": "my-file",
"acl": "public-read"
}
}
Send videos and assets to an Amazon S3 bucket. Send files to any region with your own prefix and filename. AWS credentials are required and added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The destination to send assets to - set to s3 for S3. |
| options | S3DestinationOptions | false | none | Additional S3 configuration options. |
S3DestinationOptions
{
"region": "us-east-1",
"bucket": "my-bucket",
"prefix": "my-renders",
"filename": "my-file",
"acl": "public-read"
}
Pass additional options to control how files are stored in S3.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| region | string | true | none | Choose the region to send the file to. Must be a valid AWS region string like us-east-1 or ap-southeast-2. |
| bucket | string | true | none | The bucket name to send files to. The bucket must exist in the AWS account before files can be sent. |
| prefix | string | false | none | A prefix for the file being sent. This is typically a folder name, i.e. videos or customerId/videos. |
| filename | string | false | none | Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also -poster.jpg and -thumb.jpg will be appended for poster and thumbnail images. |
| acl | string | false | none | Sets the S3 Access Control List (acl) permissions. Default is private. Must use a valid S3 Canned ACL. |
GoogleCloudStorageDestination
{
"provider": "google-cloud-storage",
"options": {
"bucket": "my-bucket",
"prefix": "my-renders",
"filename": "my-file"
}
}
Send videos and assets to a Google Cloud Storage bucket. Send files with your own prefix and filename. Google Cloud credentials are required and added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The destination to send assets to - set to google-cloud-storage for Google Cloud Storage. |
| options | GoogleCloudStorageDestinationOptions | false | none | Additional Google Cloud Storage configuration options. |
GoogleCloudStorageDestinationOptions
{
"bucket": "my-bucket",
"prefix": "my-renders",
"filename": "my-file"
}
Pass additional options to control how files are stored in Google Cloud Storage.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| bucket | string | true | none | The bucket name to send files to. The bucket must exist in the Google Cloud Storage account before files can be sent. |
| prefix | string | false | none | A prefix for the file being sent. This is typically a folder name, i.e. videos or customerId/videos. |
| filename | string | false | none | Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also -poster.jpg and -thumb.jpg will be appended for poster and thumbnail images. |
GoogleDriveDestination
{
"provider": "google-drive",
"options": {
"folderId": "1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A",
"filename": "my-file"
}
}
Send rendered videos and assets to the Google Drive cloud storage service. Google Drive uses OAuth and you must authenticate and link your Google account via dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The destination to send assets to - set to google-drive for Google Drive. |
| options | GoogleDriveDestinationOptions | true | none | Additional Google Drive configuration and features. |
GoogleDriveDestinationOptions
{
"folderId": "1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A",
"filename": "my-file"
}
Pass the folder ID and options to configure how assets are stored in Google Drive.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| folderId | string | true | none | The Google Drive folder ID where asset will be stored. The folder ID is required and can be retrieved from the URL when logged in to Google Drive, e.g. https://drive.google.com/drive/u/0/folders/1r-eTY6OLO8tzQRKwMyq-fIrQ_7AJEI6A. |
| filename | string | false | none | Use your own filename instead of the default filenames generated by Shotstack. Note: omit the file extension as this will be appended depending on the output format. Also -poster.jpg and -thumb.jpg will be appended for poster and thumbnail images. |
VimeoDestination
{
"provider": "vimeo",
"options": {
"name": "string",
"description": "string",
"privacy": {
"view": "anybody",
"embed": "public",
"comments": "anybody"
}
}
}
Send videos to Vimeo video hosting and streaming service. Vimeo credentials are required and added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The destination to send video to - set to vimeo for Vimeo. |
| options | VimeoDestinationOptions | false | none | Additional Vimeo configuration and features. |
VimeoDestinationOptions
{
"name": "string",
"description": "string",
"privacy": {
"view": "anybody",
"embed": "public",
"comments": "anybody"
}
}
Pass additional options to control how Vimeo publishes video, including name, description and privacy settings.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | false | none | A name or title for the video that will be displayed on the Vimeo website. |
| description | string | false | none | A description of the video that will be displayed on the Vimeo website. |
| privacy | VimeoDestinationPrivacyOptions | false | none | Options to control the visibility of videos and privacy features. |
VimeoDestinationPrivacyOptions
{
"view": "anybody",
"embed": "public",
"comments": "anybody"
}
Options to control the visibility of videos and privacy features.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| view | string | false | none | Set who can view the videos. Available options are:
|
| embed | string | false | none | Set who can embed the video. Available options are:
|
| comments | string | false | none | Set who can comment on the video. Available options are:
|
Enumerated Values
| Property | Value |
|---|---|
| view | anybody |
| view | nobody |
| view | contacts |
| view | password |
| view | unlisted |
| embed | public |
| embed | private |
| embed | whitelist |
| comments | anybody |
| comments | nobody |
| comments | contacts |
Template
{
"name": "My template",
"template": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
}
A template is a saved Edit than can be loaded and re-used.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | true | none | The template name |
| template | Edit | false | none | An edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format. |
TemplateRender
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
]
}
Configure the id and optional merge fields to render a template by id.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The id of the template to render in UUID format. |
| merge | [MergeField] | false | none | An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder {{NAME}} and replace it with the value Jane. |
Source
{
"url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"outputs": {
"renditions": [
{
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
}
],
"transcription": {
"format": "vtt"
}
},
"destinations": {
"provider": "shotstack",
"exclude": false
},
"callback": "https://my-server.com/callback.php"
}
The details of the file to be ingested and any transformations to be applied. Once the source file has been ingested, new renditions can be created from it. The renditions are specified in the outputs property. A rendition is a new version, generated from the source. This can be used to create new sizes and aspect ratios tht serve different purposes within an application.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| url | string | false | none | The URL of the file to be ingested. The URL must be publicly accessible or include credentials. |
| outputs | Outputs | false | none | The output renditions and transformations that should be generated from the source file. |
| destinations | Destinations | false | none | A destination is a location where assets can be sent to for serving or hosting. Videos, images and audio files that are rendered by the Edit API and source and rendition files generated by the Ingest API can be sent to destinations. You can also fetch a file from any public URL and transfer it to a destination. A file can be sent to one or more destinations including 3rd party destinations. By default all ingested and generated assets are automatically sent to the Shotstack hosting destination. You can opt-out from by setting the Shotstack destination exclude property to true. |
| callback | string | false | none | An optional webhook callback URL used to receive status notifications when sources are uploaded and renditions processed. |
Outputs
{
"renditions": [
{
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
}
],
"transcription": {
"format": "vtt"
}
}
The output renditions and transformations that should be generated from the source file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| renditions | [Rendition] | false | none | The output renditions and transformations that should be generated from the source file. |
| transcription | Transcription | false | none | The transcription settings for the output file. |
Rendition
{
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
}
A rendition is a new output file that is generated from the source. The rendition can be encoded to a different format and have transformations applied to it such as resizing, cropping, etc...
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| format | string | false | none | The output format to encode the file to. You can only encode a file to the same type, i.e. a video to a video or an image to an image. You can't encode a video as an image. The following formats are available:
|
| 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.
|
| resolution | any | false | none | The preset output resolution of the video or image. This is a convenience property that sets the width and height based on industry standard resolutions. The following resolutions are available:
|
| 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.
|
| speed | Speed | false | none | Set the playback speed of a video or audio file. Allows you to preserve the pitch of the audio so that it is sped up without sounding too high pitched or too low. |
| keyframeInterval | integer | false | none | The keyframe interval is useful to optimize playback, seeking and smoother scrubbing in browsers. The value sets the number of frames between a keyframe. The lower the number, the larger the file. Try a value between 10 and 25 for smooth scrubbing. |
| fixOffset | boolean | false | none | Attempt to fix audio and video sync issues. This can occur when recording devices, such as smartphones and web cams use compression techniques like Variable Frame Rate (VFR) which can cause audio and video to go out of sync. This option will attempt to fix the sync issues. |
| fixRotation | boolean | false | none | Automatically reset the rotation of the video based on the orientation metadata in the video file. This is useful for videos recorded on smartphones that have orientation metadata that may not work correctly with certain video editing software, including the Shotstack Edit API. |
| enhance | Enhancements | false | none | Apply media processing enhancements to the rendition using a third party provider. Currently only Dolby.io audio enhancement is available. |
| filename | string | false | none | A custom name for the generated rendition file. The file extension will be automatically added based on the format of the rendition. If no filename is provided, the rendition ID will be used. |
Enumerated Values
| Property | Value |
|---|---|
| format | mp4 |
| format | webm |
| format | mov |
| format | avi |
| format | mkv |
| format | ogv |
| format | wmv |
| format | avif |
| format | gif |
| format | mp3 |
| format | wav |
| format | jpg |
| format | png |
| format | webp |
| format | tif |
| fit | cover |
| fit | contain |
| fit | crop |
| resolution | preview |
| resolution | mobile |
| resolution | sd |
| resolution | hd |
| resolution | fhd |
| fps | 12 |
| fps | 15 |
| fps | 23.976 |
| fps | 24 |
| fps | 25 |
| fps | 29.97 |
| fps | 30 |
| fps | 48 |
| fps | 50 |
| fps | 59.94 |
| fps | 60 |
Transcription
{
"format": "vtt"
}
Generate a transcription of the audio in the video. The transcription can be output as a file in SRT or VTT format.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| format | string | false | none | The output format of the transcription file. The following formats are available:
|
Enumerated Values
| Property | Value |
|---|---|
| format | srt |
| format | vtt |
Speed
{
"speed": 1.5,
"preservePitch": false
}
Set the playback speed of a video or audio file. Allows you to preserve the pitch of the audio so that it is sped up without sounding too high pitched or too low.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| speed | number(float) | false | none | Adjust the playback speed of the video clip between 0 (paused) and 10 (10x normal speed) where 1 is normal speed (defaults to 1). Set values less than 1 to slow down the playback speed, i.e. set speed to 0.5 to play back at half speed. Set values greater than 1 to speed up the playback speed, i.e. set speed to 2 to play back at double speed. |
| preservePitch | boolean | false | none | Set whether to adjust the audio pitch or not. Set to false to make the audio sound higher or lower pitched. By default the pitch is preserved. |
Enhancements
{
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
}
Enhancements that can be applied to a rendition. Currently only supports the Dolby audio enhancement.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| audio | AudioEnhancement | false | none | An audio enhancement that can be applied to the audio content of the rendition. |
AudioEnhancement
{
"provider": "dolby",
"options": {
"preset": "studio"
}
}
An audio enhancement that can be applied to the audio content of a rendition. The following providers are available:
Properties
None
DolbyEnhancement
{
"provider": "dolby",
"options": {
"preset": "studio"
}
}
Dolby.io audio enhancement provider. Credentials are required and must be added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The enhancement provider to use - set to dolby for Dolby. |
| options | DolbyEnhancementOptions | true | none | Additional Dolby configuration and features. |
DolbyEnhancementOptions
{
"preset": "studio"
}
Options for the Dolby.io audio enhancement provider.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| preset | string | true | none | The preset to use for the audio enhancement. The following presets are available:
|
Enumerated Values
| Property | Value |
|---|---|
| preset | conference |
| preset | interview |
| preset | lecture |
| preset | meeting |
| preset | mobile_phone |
| preset | music |
| preset | podcast |
| preset | studio |
| preset | voice_over |
Transfer
{
"url": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"id": "018e8937-5015-75ee-aab6-03f214981133",
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
}
The asset URL to fetch and transfer to a destination.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| url | string | true | none | The file URL to fetch and transfer. |
| id | string | true | none | An identifier for the asset which must be provided by the client. The identifier does not need to be unique. |
| destinations | [Destinations] | true | none | Specify the storage locations and hosting services to send the file to. |
GeneratedAsset
{
"provider": "shotstack",
"options": {
"type": "text-to-speech",
"text": "This is a text to speech example generated by Shotstack",
"voice": "Matthew",
"language": "en-US",
"newscaster": false
}
}
A generated asset is a media asset created by the Create API. You can use native or third party providers to generate video, audio and image files using Generative AI services like text-to-speech and text-to-avatar.
Properties
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShotstackGeneratedAsset | false | none | Generate assets using the native Shotstack provider. Shotstack provides a text-to-speech and a text-to-image service. The Shotstack provider works natively with your existing API key, no additional credentials are required. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | DIDGeneratedAsset | false | none | Generate assets using D-ID. D-ID provide a text-to-avatar service. The D-ID provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ElevenLabsGeneratedAsset | false | none | Generate assets using ElevenLabs. ElevenLabs provide a text-to-speech service. The ElevenLabs provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | HeyGenGeneratedAsset | false | none | Generate assets using HeyGen. HeyGen provide a text-to-avatar service. The HeyGen provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | OpenAiGeneratedAsset | false | none | Generate assets using OpenAI. OpenAI provide a text generation service using ChatGPT 3.5 and 4. The OpenAI provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | StabilityAiGeneratedAsset | false | none | Generate assets using Stability AI. Stability AI provide a text-to-image service using Stable Diffusion. The Stability AI provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request. |
ShotstackGeneratedAsset
{
"provider": "shotstack",
"options": {
"type": "text-to-speech",
"text": "This is a text to speech example generated by Shotstack",
"voice": "Matthew",
"language": "en-US",
"newscaster": false
}
}
Generate assets using the native Shotstack provider. Shotstack provides a text-to-speech and a text-to-image service. The Shotstack provider works natively with your existing API key, no additional credentials are required.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The name of the provider - set to shotstack for Shotstack. |
| options | ShotstackGeneratedAssetOptions | true | none | Options and configuration for the native Shotstack services. |
Enumerated Values
| Property | Value |
|---|---|
| provider | shotstack |
ShotstackGeneratedAssetOptions
{
"type": "text-to-speech",
"text": "This is a text to speech example generated by Shotstack",
"voice": "Matthew",
"language": "en-US",
"newscaster": false
}
Generate assets using the native Shotstack provider AI services.
Properties
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShotstackTextToSpeechOptions | false | none | Options for the Shotstack text-to-speech service. Set the text to be converted to speech and choose a voice to set the speaking style. The output will be generated as an MP3 audio file available at the URL returned in the response. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShotstackTextToImageOptions | false | none | Options for the Shotstack text-to-image service. Set a text prompt to generate an image from. The output will be generated as a PNG file available at the URL returned in the response. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShotstackTextGeneratorOptions | false | none | Options for the Shotstack text-generator service. Set a text prompt that will be used to generate a new body of text. The output will be generated as a text (txt) file available at the URL returned in the response. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| anonymous | ShotstackImageToVideoOptions | false | none | Options for the Shotstack image-to-video service. Set the URL of an image to convert in to a video. The output will be generated as an MP4 file available at the URL returned in the response. |
ShotstackTextToSpeechOptions
{
"type": "text-to-speech",
"text": "This is a text to speech example generated by Shotstack",
"voice": "Matthew",
"language": "en-US",
"newscaster": false
}
Options for the Shotstack text-to-speech service. Set the text to be converted to speech and choose a voice to set the speaking style. The output will be generated as an MP3 audio file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-speech for text-to-speech. |
| text | string | true | none | The text to convert to speech. |
| voice | string | true | none | The voice to use for the text-to-speech conversion. You must pair the correct voice with the correct language. For each language there is a language code that must be set in the language property. The voice must be available for the language code or the conversion will fail. i.e. To use the voice Zeina for Arabic you must set the language to arb.Select a voice from the list of available voices, the language code is in brackets:
|
| language | string | false | none | The language code for the text-to-speech conversion. You must pair the correct language with the correct voice (see voice parameter above). Select a language from the list of available languages:
|
| newscaster | boolean | false | none | Set the voice to newscaster mode. *Only Matthew and Joanna for US English (en-US), Lupe for US Spanish (es-US), and Amy for British English (en-GB) are available in the newscaster voice. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-speech |
| voice | Hala |
| voice | Lisa |
| voice | Arlet |
| voice | Hiujin |
| voice | Zhiyu |
| voice | Sofie |
| voice | Laura |
| voice | Olivia |
| voice | Amy |
| voice | Emma |
| voice | Brian |
| voice | Arthur |
| voice | Kajal |
| voice | Niamh |
| voice | Aria |
| voice | Ayanda |
| voice | Ivy |
| voice | Joanna |
| voice | Kendra |
| voice | Kimberly |
| voice | Salli |
| voice | Joey |
| voice | Justin |
| voice | Kevin |
| voice | Matthew |
| voice | Ruth |
| voice | Stephen |
| voice | Suvi |
| voice | Léa |
| voice | Rémi |
| voice | Gabrielle |
| voice | Liam |
| voice | Vicki |
| voice | Daniel |
| voice | Hannah |
| voice | Kajal |
| voice | Bianca |
| voice | Adriano |
| voice | Takumi |
| voice | Kazuha |
| voice | Tomoko |
| voice | Seoyeon |
| voice | Ida |
| voice | Ola |
| voice | Camila |
| voice | Vitória |
| voice | Vitoria |
| voice | Thiago |
| voice | Inês |
| voice | Ines |
| voice | Lucia |
| voice | Sergio |
| voice | Mia |
| voice | Andrés |
| voice | Lupe |
| voice | Pedro |
| voice | Elin |
| language | cmn-CN |
| language | da-DK |
| language | de-DE |
| language | en-AU |
| language | en-GB |
| language | en-IN |
| language | en-US |
| language | es-ES |
| language | es-MX |
| language | es-US |
| language | fr-CA |
| language | fr-FR |
| language | it-IT |
| language | ja-JP |
| language | hi-IN |
| language | ko-KR |
| language | nb-NO |
| language | nl-NL |
| language | pl-PL |
| language | pt-BR |
| language | pt-PT |
| language | sv-SE |
| language | en-NZ |
| language | en-ZA |
| language | ca-ES |
| language | de-AT |
| language | yue-CN |
| language | ar-AE |
| language | fi-FI |
ShotstackTextToImageOptions
{
"type": "text-to-image",
"prompt": "A detailed photograph of Mars, showcasing its orange-red surface",
"width": 512,
"height": 512
}
Options for the Shotstack text-to-image service. Set a text prompt to generate an image from. The output will be generated as a PNG file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-image for text-to-image. |
| prompt | string | true | none | The text prompt to generate an image from. |
| width | integer | true | none | The width of the image in pixels. |
| height | integer | true | none | The height of the image in pixels. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-image |
ShotstackImageToVideoOptions
{
"type": "image-to-video",
"imageUrl": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/image.jpg",
"guidanceScale": 1.8,
"motion": 127
}
Options for the Shotstack image-to-video service. Set the URL of an image to convert in to a video. The output will be generated as an MP4 file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to image-to-video for image-to-video. |
| imageUrl | string | true | none | The URL of the image to convert to video. The URL must be publicly accessible or include credentials. The image dimensions must exactly match one of the following: 1024px x 576px, 576px x 1024px or 768px x 768px. |
| guidanceScale | number | false | none | The guidance scale determines how closely the generated video will match the image. Lower numbers allow for more creative freedom. A number between 0 and 10. |
| motion | integer | false | none | The amount of motion in the video. A number between 1 and 255. |
Enumerated Values
| Property | Value |
|---|---|
| type | image-to-video |
ShotstackTextGeneratorOptions
{
"type": "text-generator",
"prompt": "Generate a short script for a 15 second video describing the benefits of the Shotstack API"
}
Options for the Shotstack text-generator service. Set a text prompt that will be used to generate a new body of text. The output will be generated as a text (txt) file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-generator for text generation. |
| prompt | string | true | none | The text prompt to generate text from. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-generator |
DIDGeneratedAsset
{
"provider": "d-id",
"options": {
"type": "text-to-avatar",
"text": "I am an avatar generated by D-ID using a text prompt",
"avatar": "jack",
"background": "#ffffff"
}
}
Generate assets using D-ID. D-ID provide a text-to-avatar service. The D-ID provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The name of the provider - set to d-id for D-ID. |
| options | DIDGeneratedAssetOptions | true | none | Options and configuration for the D-ID text-to-avatar service. |
Enumerated Values
| Property | Value |
|---|---|
| provider | d-id |
DIDGeneratedAssetOptions
{
"type": "text-to-avatar",
"text": "I am an avatar generated by D-ID using a text prompt",
"avatar": "jack",
"background": "#ffffff"
}
Generate assets using the third party D-ID provider AI services.
The following AI generation services are available:
Properties
None
DIDTextToAvatarOptions
{
"type": "text-to-avatar",
"text": "I am an avatar generated by D-ID using a text prompt",
"avatar": "jack",
"background": "#ffffff"
}
Options for the D-ID text-to-avatar service. Set the text to be converted to an avatar and configure the avatar and background. The output will be generated as an MP4 video file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-avatar for text-to-avatar. |
| text | string | true | none | The text or script that the avatar will narrate. |
| avatar | string | true | none | The avatar character to generate. Select from the list of available avatars:
|
| background | string | false | none | The background color of the video. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-avatar |
| avatar | jack |
| avatar | lana |
| avatar | lily |
| avatar | matt |
| avatar | rian |
ElevenLabsGeneratedAsset
{
"provider": "elevenlabs",
"options": {
"type": "text-to-speech",
"text": "This is a text to speech example generated by ElevenLabs",
"voice": "Adam"
}
}
Generate assets using ElevenLabs. ElevenLabs provide a text-to-speech service. The ElevenLabs provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The name of the provider - set to elevenlabs for ElevenLabs. |
| options | ElevenLabsGeneratedAssetOptions | true | none | Options and configuration for the ElevenLabs text-to-speech service. |
Enumerated Values
| Property | Value |
|---|---|
| provider | elevenlabs |
ElevenLabsGeneratedAssetOptions
{
"type": "text-to-speech",
"text": "This is a text to speech example generated by ElevenLabs",
"voice": "Adam"
}
Generate assets using the third party ElevenLabs provider AI services.
The following AI generation services are available:
Properties
None
ElevenLabsTextToSpeechOptions
{
"type": "text-to-speech",
"text": "This is a text to speech example generated by ElevenLabs",
"voice": "Adam"
}
Options for the ElevenLabs text-to-speech service. Set the text to be converted to speech and choose a voice to set the speaking style. The output will be generated as an MP3 audio file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-speech for text-to-speech. |
| text | string | true | none | The text to convert to speech. |
| voice | string | true | none | The voice to use for the text-to-speech conversion. Select a voice from the list of available voices:
|
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-speech |
| voice | Adam |
| voice | Antoni |
| voice | Arnold |
| voice | Bella |
| voice | Domi |
| voice | Elli |
| voice | Josh |
| voice | Rachel |
| voice | Sam |
HeyGenGeneratedAsset
{
"provider": "heygen",
"options": {
"type": "text-to-avatar",
"text": "I am an avatar generated by HeyGen using a text prompt",
"avatar": "Angela",
"voice": "Abbi - Natural",
"avatarStyle": "normal",
"background": "#ffffff",
"ratio": "16:9",
"test": true
}
}
Generate assets using HeyGen. HeyGen provide a text-to-avatar service. The HeyGen provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The name of the provider - set to heygen for HeyGen. |
| options | HeyGenGeneratedAssetOptions | true | none | Options and configuration for the HeyGen text-to-avatar service. |
Enumerated Values
| Property | Value |
|---|---|
| provider | heygen |
HeyGenGeneratedAssetOptions
{
"type": "text-to-avatar",
"text": "I am an avatar generated by HeyGen using a text prompt",
"avatar": "Angela",
"voice": "Abbi - Natural",
"avatarStyle": "normal",
"background": "#ffffff",
"ratio": "16:9",
"test": true
}
Generate assets using the third party HeyGen provider AI services.
The following AI generation services are available:
Properties
None
HeyGenTextToAvatarOptions
{
"type": "text-to-avatar",
"text": "I am an avatar generated by HeyGen using a text prompt",
"avatar": "Angela",
"voice": "Abbi - Natural",
"avatarStyle": "normal",
"background": "#ffffff",
"ratio": "16:9",
"test": true
}
Options for the HeyGen text-to-avatar service. Set the text to be converted to an avatar and configure the avatars voice, speaking style, appearance and background. The output will be generated as an MP4 video file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-avatar for text-to-avatar. |
| text | string | true | none | The text or script that the avatar will narrate. |
| avatar | string | true | none | The avatar character to generate. Select from the list of available avatars:
|
| voice | string | true | none | The avatars voice and speaking style. Select from the list of available voices:
|
| avatarStyle | string | false | none | The display style of the avatar, a rectangle normal or circular circle background. Defaults to normal. |
| background | string | false | none | The background color of the video. Defaults to #ffffff. |
| ratio | string | false | none | The aspect ratio of the video, 16:9 horizontal or 9:16 vertical. Defaults to 16:9. |
| test | boolean | false | none | A boolean flag indicating whether the video is for testing purposes. See the "test" parameter in HeyGen for more details. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-avatar |
| avatar | Angela |
| avatar | Bill |
| avatar | Daisy |
| avatar | Derek |
| avatar | Eva |
| avatar | Jake |
| avatar | Jeff |
| avatar | Jerome |
| avatar | Joon |
| avatar | Kayla |
| avatar | Kent |
| avatar | Luna |
| avatar | Mark |
| avatar | Matthew |
| avatar | Monica |
| avatar | Peter |
| avatar | Selina |
| avatar | Tanya |
| avatar | Thomas |
| avatar | Tina |
| avatar | Tyler |
| avatar | Vanessa |
| avatar | Vera |
| avatar | Wilson |
| avatar | Zoey |
| voice | Abbi - Natural |
| voice | Adam - Natural |
| voice | Aiston - Friendly |
| voice | Alice - Newscaster |
| voice | Alison - Cheerful |
| voice | Amber - Friendly |
| voice | Amy - Warm |
| voice | Ana - Cheerful |
| voice | Antoni - Friendly |
| voice | Aria - Newscaster |
| voice | Arnold - Cheerful |
| voice | Arthur - Natural |
| voice | Bella - Friendly |
| voice | Belle - Natural |
| voice | Brandon - Warm |
| voice | Brian - Natural |
| voice | Bruce - Natural |
| voice | Cerise - Cheerful |
| voice | Christopher - Calm |
| voice | Clara - Professional |
| voice | Connor - Natural |
| voice | Dahlia - Friendly |
| voice | Davis - Professional |
| voice | Dean - Natural |
| voice | Delbert - Cheerful |
| voice | Edward - Friendly |
| voice | Elaine - Calm |
| voice | Emily - Natural |
| voice | Emma - Newscaster |
| voice | Eric - Newscaster |
| voice | Grace - Natural |
| voice | Hailey - Calm |
| voice | Indira - Cheerful |
| voice | Isabella - Cheerful |
| voice | Jacob - Natural |
| voice | Jahmai - Friendly |
| voice | Jane - Serious |
| voice | Jason - Serious |
| voice | Jelle - Friendly |
| voice | Jen - Natural |
| voice | Jenny - Professional |
| voice | Jodi - Cheerful |
| voice | Joey - Calm |
| voice | Johan - Friendly |
| voice | Josie - Cheerful |
| voice | Keanan - Natural |
| voice | Keith - Cheerful |
| voice | Kellie - Friendly |
| voice | Lauren - Friendly |
| voice | Leah - Natural |
| voice | Liam - Professional |
| voice | Libby - Natural |
| voice | Lily - Professional |
| voice | Lucas - Natural |
| voice | Luke - Professional |
| voice | Luna - Natural |
| voice | Marieke - Natural |
| voice | Matthew - Professional |
| voice | Michelle - Natural |
| voice | Mitchell - Natural |
| voice | Molly - Newscaster |
| voice | Monica - Calm |
| voice | Natasha - Professional |
| voice | Neerja - Newscaster |
| voice | Noah - Serious |
| voice | Oliver - Newscaster |
| voice | Olivia - Calm |
| voice | Paul - Natural |
| voice | Prabhat - Natural |
| voice | Raveena - Natural |
| voice | Rudi - Friendly |
| voice | Ryan - Professional |
| voice | Sam - Natural |
| voice | Sara - Cheerful |
| voice | Sherry - Friendly |
| voice | Sonia - Warm |
| voice | Thomas - Natural |
| voice | Todd - Professional |
| voice | Tony - Professional |
| voice | Tracy - Cheerful |
| voice | Wayne - Natural |
| voice | Wilder - Natural |
| voice | Wille - Natural |
| voice | William - Friendly |
| avatarStyle | normal |
| avatarStyle | circle |
| ratio | 16:9 |
| ratio | 9:16 |
OpenAiGeneratedAsset
{
"provider": "openai",
"options": {
"type": "text-generator",
"prompt": "Generate a short script for a 15 second video describing the benefits of the Shotstack API",
"model": "gpt-4",
"systemPrompt": "You are a professional script writer and film maker"
}
}
Generate assets using OpenAI. OpenAI provide a text generation service using ChatGPT 3.5 and 4. The OpenAI provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The name of the provider - set to openai for OpenAI. |
| options | OpenAiGeneratedAssetOptions | true | none | Options and configuration for the OpenAI text-generator service. |
Enumerated Values
| Property | Value |
|---|---|
| provider | openai |
OpenAiGeneratedAssetOptions
{
"type": "text-generator",
"prompt": "Generate a short script for a 15 second video describing the benefits of the Shotstack API",
"model": "gpt-4",
"systemPrompt": "You are a professional script writer and film maker"
}
Generate assets using OpenAI provider AI services.
The following AI generation services are available:
Properties
None
OpenAiTextGeneratorOptions
{
"type": "text-generator",
"prompt": "Generate a short script for a 15 second video describing the benefits of the Shotstack API",
"model": "gpt-4",
"systemPrompt": "You are a professional script writer and film maker"
}
Options for the OpenAI text-generator service. Set a text prompt that will be used to generate a new body of text. The output will be generated as a text (txt) file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-generator for text generation. |
| prompt | string | true | none | The text prompt to generate text from. |
| model | string | true | none | The model to use for generating the text. Select from the list of available models:
|
| systemPrompt | string | false | none | The system prompt to use for generating the text. This is an optional prompt that can be used to provide context or additional information to the model. |
Enumerated Values
| Property | Value |
|---|---|
| type | text-generator |
| model | gpt-3.5-turbo |
| model | gpt-4 |
StabilityAiGeneratedAsset
{
"provider": "stability-ai",
"options": {
"type": "text-to-image",
"prompt": "A detailed photograph of Mars, showcasing its orange-red surface",
"engine": "stable-diffusion-xl-1024-v1-0",
"width": 512,
"height": 512,
"steps": 30,
"seed": 0,
"cfgScale": 7,
"stylePreset": "photographic"
}
}
Generate assets using Stability AI. Stability AI provide a text-to-image service using Stable Diffusion. The Stability AI provider works on a bring-your-own-key basis, credentials are required and must be added via the dashboard, not in the request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| provider | string | true | none | The name of the provider - set to stability-ai for Stability AI. |
| options | StabilityAiGeneratedAssetOptions | true | none | Options and configuration for the Stability AI text-to-image service. |
Enumerated Values
| Property | Value |
|---|---|
| provider | stability-ai |
StabilityAiGeneratedAssetOptions
{
"type": "text-to-image",
"prompt": "A detailed photograph of Mars, showcasing its orange-red surface",
"engine": "stable-diffusion-xl-1024-v1-0",
"width": 512,
"height": 512,
"steps": 30,
"seed": 0,
"cfgScale": 7,
"stylePreset": "photographic"
}
Generate assets using Stability AI provider AI services.
The following AI generation services are available:
Properties
None
StabilityAiTextToImageOptions
{
"type": "text-to-image",
"prompt": "A detailed photograph of Mars, showcasing its orange-red surface",
"engine": "stable-diffusion-xl-1024-v1-0",
"width": 512,
"height": 512,
"steps": 30,
"seed": 0,
"cfgScale": 7,
"stylePreset": "photographic"
}
Options for the Stability AI text-to-image service. Set a text prompt to generate an image from plus other engine and configuration options. The output will be generated as a JPG file available at the URL returned in the response.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of asset to generate - set to text-to-image for text-to-image. |
| prompt | string | true | none | The text prompt to generate an image from. |
| engine | string | false | none | The engine (model) to use for generating the image. Select from the list of available engines:
|
| width | integer | true | none | The width of the image in pixels. Must be divisible by 64. |
| height | integer | true | none | The height of the image in pixels. Must be divisible by 64. |
| steps | integer | false | none | The number of iterative diffusion steps to run. A number between 10 and 50. |
| seed | integer | false | none | Using the same seed can help you create images that look similar. Set to 0 for a random seed. A number between 0 and 4294967295. |
| cfgScale | number | false | none | Determines how closely the generated image will match the prompt. Lower numbers allow for more creative freedom. A number between 0 and 35. |
| stylePreset | string | false | none | Apply a preset to generate an image in a particular style. Select from the list of available presets:
|
Enumerated Values
| Property | Value |
|---|---|
| type | text-to-image |
| engine | stable-diffusion-xl-1024-v0-9 |
| engine | stable-diffusion-xl-1024-v1-0 |
| engine | stable-diffusion-v1-6 |
| engine | stable-diffusion-512-v2-1 |
| engine | stable-diffusion-xl-beta-v2-2-2 |
| stylePreset | 3d-model |
| stylePreset | analog-film |
| stylePreset | anime |
| stylePreset | cinematic |
| stylePreset | comic-book |
| stylePreset | digital-art |
| stylePreset | enhance |
| stylePreset | fantasy-art |
| stylePreset | isometric |
| stylePreset | line-art |
| stylePreset | low-poly |
| stylePreset | modeling-compound |
| stylePreset | neon-punk |
| stylePreset | origami |
| stylePreset | photographic |
| stylePreset | pixel-art |
| stylePreset | tile-texture |
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": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
},
"created": "2020-10-30T09:42:29.446Z",
"updated": "2020-10-30T09:42:39.168Z"
}
}
The response received after a render status request is submitted. The response includes details about status of a render and the output URL.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | true if status available, else false. |
| message | string | true | none | OK or an error message. |
| response | RenderResponseData | true | none | RenderResponse or an error message. |
RenderResponseData
{
"id": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"owner": "5ca6hu7s9k",
"plan": "basic",
"status": "done",
"error": "",
"duration": 8.5,
"renderTime": 9433.44,
"url": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"poster": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7-poster.jpg",
"thumbnail": "https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7-thumb.jpg",
"data": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
},
"created": "2020-10-30T09:42:29.446Z",
"updated": "2020-10-30T09:42:39.168Z"
}
The response data returned with the RenderResponse including status and URL.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The id of the render task in UUID format. |
| owner | string | true | none | The owner id of the render task. |
| plan | string | false | none | The customer subscription plan. |
| status | string | true | none | The status of the render task.
|
| 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": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
}
}
The template data including the template name and Edit.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | true if successfully returned, else false. |
| message | string | true | none | OK, Bad Request or an error message. |
| response | TemplateDataResponseData | true | none | TemplateDataResponseData or an error message. |
TemplateDataResponseData
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"name": "My template",
"owner": "5ca6hu7s9k",
"template": {
"timeline": {
"soundtrack": {
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/music.mp3",
"effect": "fadeIn",
"volume": 0
},
"background": "string",
"fonts": [
{
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/open-sans.ttf"
}
],
"tracks": [
{
"clips": [
{
"asset": {
"type": "video",
"src": "https://s3-ap-northeast-1.amazonaws.com/my-bucket/video.mp4",
"trim": 2,
"volume": 0.5,
"volumeEffect": "fadeIn",
"speed": 1,
"crop": {
"top": 0.15,
"bottom": 0.15,
"left": 0,
"right": 0
},
"chromaKey": {
"color": "#00b140",
"threshold": 150,
"halo": 100
}
},
"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.5,
"transform": {
"rotate": {
"angle": 45
},
"skew": {
"x": 0.5,
"y": 0.5
},
"flip": {
"horizontal": true,
"vertical": true
}
}
}
]
}
],
"cache": true
},
"output": {
"format": "mp4",
"resolution": "hd",
"aspectRatio": "16:9",
"size": {
"width": 1200,
"height": 800
},
"fps": 25,
"scaleTo": "preview",
"quality": "medium",
"repeat": true,
"mute": false,
"range": {
"start": 3,
"length": 6
},
"poster": {
"capture": 1
},
"thumbnail": {
"capture": 1,
"scale": 0.3
},
"destinations": [
{
"provider": "shotstack",
"exclude": false
}
]
},
"merge": [
{
"find": "NAME",
"replace": "Jane"
}
],
"callback": "https://my-server.com/callback.php",
"disk": "local"
}
}
The response data returned with the TemplateDataResponse.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The unique id of the template in UUID format. |
| name | string | true | none | The template name. |
| owner | string | true | none | The owner id of the templates. |
| template | Edit | true | none | The Edit template. |
TemplateListResponse
{
"success": true,
"message": "OK",
"response": {
"owner": "5ca6hu7s9k",
"templates": [
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"name": "My template",
"created": "2022-06-10T12:50:21.455Z",
"updated": "2022-06-22T08:24:30.168Z"
}
]
}
}
A list of previously saved templates.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | true if successfully returned, else false. |
| message | string | true | none | OK, Bad Request or an error message. |
| response | TemplateListResponseData | true | none | TemplateListResponseData or an error message. |
TemplateListResponseData
{
"owner": "5ca6hu7s9k",
"templates": [
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"name": "My template",
"created": "2022-06-10T12:50:21.455Z",
"updated": "2022-06-22T08:24:30.168Z"
}
]
}
The response data returned with the TemplateListResponse.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| owner | string | true | none | The owner id of the templates. |
| templates | [TemplateListResponseItem] | true | none | The list of templates. |
TemplateListResponseItem
{
"id": "f5493c17-d01f-445c-bb49-535fae65f219",
"name": "My template",
"created": "2022-06-10T12:50:21.455Z",
"updated": "2022-06-22T08:24:30.168Z"
}
The individual template item returned with the TemplateListResponseData templates list.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The unique id of the template in UUID format. |
| name | string | true | none | The template name |
| created | string | false | none | The time the template was created. |
| updated | string | false | none | The time the template was last updated. |
ProbeResponse
{
"success": true,
"message": "Created",
"response": {}
}
The response received after a probe request is submitted. The probe requests returns data from FFprobe formatted as JSON.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | true if media successfully read, else false. |
| message | string | true | none | Created, Bad Request or an error message. |
| response | object | true | none | The response from FFprobe in JSON format. |
AssetResponse
{
"data": {
"type": "asset",
"attributes": {
"id": "a4482cbf-e321-42a2-ac8b-947d26886840",
"owner": "5ca6hu7s9k",
"region": "au",
"renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
"filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"status": "ready",
"created": "2021-06-30T09:42:29.446Z",
"updated": "2021-06-30T09:42:30.168Z"
}
}
}
The response returned by the Serve API get asset request. Includes details of a hosted video, image, audio file, thumbnail or poster image. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | AssetResponseData | true | none | An asset resource. |
AssetRenderResponse
{
"data": [
{
"type": "asset",
"attributes": {
"id": "a4482cbf-e321-42a2-ac8b-947d26886840",
"owner": "5ca6hu7s9k",
"region": "au",
"renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
"filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"status": "ready",
"created": "2021-06-30T09:42:29.446Z",
"updated": "2021-06-30T09:42:30.168Z"
}
}
]
}
The response returned by the Serve API get asset by render id request. The response is an array of asset resources, including video, image, audio, thumbnail and poster image. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [AssetResponseData] | true | none | An array of asset resources grouped by render id. |
AssetResponseData
{
"type": "asset",
"attributes": {
"id": "a4482cbf-e321-42a2-ac8b-947d26886840",
"owner": "5ca6hu7s9k",
"region": "au",
"renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
"filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"status": "ready",
"created": "2021-06-30T09:42:29.446Z",
"updated": "2021-06-30T09:42:30.168Z"
}
}
The type of resource (an asset) and attributes of the asset.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of resource, in this case it is an assets. |
| attributes | AssetResponseAttributes | true | none | The asset attributes including render id, url, filename, file size, etc... |
AssetResponseAttributes
{
"id": "a4482cbf-e321-42a2-ac8b-947d26886840",
"owner": "5ca6hu7s9k",
"region": "au",
"renderId": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7",
"providerId": "a4482cbf-e321-42a2-ac8b-947d26886840",
"filename": "2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"url": "https://cdn.shotstack.io/au/v1/5ca6hu7s9k/2abd5c11-0f3d-4c6d-ba20-235fc9b8e8b7.mp4",
"status": "ready",
"created": "2021-06-30T09:42:29.446Z",
"updated": "2021-06-30T09:42:30.168Z"
}
The list of asset attributes and their values.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The unique id of the hosted asset in UUID format. |
| owner | string | true | none | The owner id of the asset. |
| region | string | false | none | The region the asset is hosted, currently only au (Australia). |
| renderId | string | false | none | The original render id that created the asset in UUID format. Multiple assets can share the same render id. |
| providerId | string | false | none | The third party id of an asset transferred to an external provider, i.e. Mux, YouTube or S3. If the provider is Shotstack, the providerID is the same as the asset id. |
| filename | string | false | none | The asset file name. |
| url | string | false | none | The asset file name. |
| status | string | true | none | The status of the asset.
|
| created | string | false | none | The time the asset was created. |
| updated | string | false | none | The time the asset status was last updated. |
Enumerated Values
| Property | Value |
|---|---|
| status | importing |
| status | ready |
| status | failed |
| status | deleted |
TransferResponse
{
"data": {
"type": "asset",
"attributes": {
"id": "018e8937-5015-75ee-aab6-03f214981133",
"owner": "5ca6hu7s9k",
"status": "queued",
"created": "2023-09-28T11:17:32.226Z"
}
}
}
The response returned by the Serve API transfer asset request. The response includes the ID and transfer status. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | TransferResponseData | true | none | An asset transfer resource. |
TransferResponseData
{
"type": "asset",
"attributes": {
"id": "018e8937-5015-75ee-aab6-03f214981133",
"owner": "5ca6hu7s9k",
"status": "queued",
"created": "2023-09-28T11:17:32.226Z"
}
}
The type of resource (an asset) and the transfer attributes. Returned with TransferResponse.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | false | none | The type of resource, in this case it is an asset. |
| attributes | TransferResponseAttributes | false | none | The attributes of the asset transfer including the status. |
TransferResponseAttributes
{
"id": "018e8937-5015-75ee-aab6-03f214981133",
"owner": "5ca6hu7s9k",
"status": "queued",
"created": "2023-09-28T11:17:32.226Z"
}
The transfer request attributes inlcudling the user specified ID and status. Returned with TransferResponseData.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | The user provided ID for the asset |
| owner | string | false | none | The attributes of the asset transfer including the status. |
| status | string | false | none | The status of the asset transfer.
|
| created | string | false | none | The time the asset transfer was created. |
Enumerated Values
| Property | Value |
|---|---|
| status | queued |
| status | failed |
QueuedSourceResponse
{
"data": {
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2"
}
}
The response returned by the Ingest API fetch source request. Includes the id of the source file. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | QueuedSourceResponseData | true | none | A source resource. |
QueuedSourceResponseData
{
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2"
}
The type of resource (a source) and the newly created source id. Returned with QueuedSourceResponse.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of resource, in this case it is a source. |
| id | string | true | none | The source id. |
SourceListResponse
{
"data": [
{
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"owner": "5ca6hu7s9k",
"input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
"status": "ready",
"outputs": {
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967,
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
]
}
A list of all ingested source files fetched or uploaded to a users account.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [SourceResponseData] | true | none | An array of ingested source files. |
SourceResponse
{
"data": {
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"owner": "5ca6hu7s9k",
"input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
"status": "ready",
"outputs": {
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967,
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
}
The response returned by the Ingest API get source request. Includes details of the ingested source file. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | SourceResponseData | true | none | A source resource. |
SourceResponseData
{
"type": "source",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"owner": "5ca6hu7s9k",
"input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
"status": "ready",
"outputs": {
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967,
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
The type of resource (a source), it's id and attributes of the source file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of resource, in this case it is a source. |
| id | string | true | none | The source file id. |
| attributes | SourceResponseAttributes | true | none | The source attributes including its url, status, width, height, duration, etc... |
SourceResponseAttributes
{
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"owner": "5ca6hu7s9k",
"input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
"source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
"status": "ready",
"outputs": {
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967,
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
The id and attributes of the source file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The source id. |
| owner | string | true | none | The owner id of the source file. |
| input | string | false | none | The original URL of an ingested source file, where it originated. Only displayed for files ingested using the fetch source endpoint. Not displayed for direct uploads. |
| source | string | false | none | The URL of the source file hosted by Shotstack. The file at the URL can be used by the Edit API. Source file URL's consist of a base URL (AWS bucket), owner id, source id and a file named source. The extension varies depending on the type of file ingested. |
| status | any | false | none | The status of the source file ingestion task.
|
| outputs | OutputsResponse | false | none | The list of outputs generated from the source file. Currently supports renditions which are versions of the source file with different transformations applied. |
| width | integer | false | none | The width in pixels of the ingested source file, if a video or image. |
| height | string | false | none | The height in pixels of the ingested source file, if a video or image. |
| duration | number(float) | false | none | The duration in seconds of the ingested source file, if a video or audio file. |
| fps | number(float) | false | none | The frame rate in frames per second of the source file, if a video file. |
| created | string | false | none | The time the ingestion task was initially queued. |
| updated | string | false | none | The time the ingestion status was last updated. |
Enumerated Values
| Property | Value |
|---|---|
| status | queued |
| status | importing |
| status | ready |
| status | failed |
| status | deleted |
| status | overwritten |
OutputsResponse
{
"renditions": [
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
]
}
The list of outputs generated from the source file. Currently supports renditions which are versions of the source file with different transformations applied.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| renditions | [RenditionResponseAttributes] | false | none | The list of renditions generated from the source file. |
RenditionResponseAttributes
{
"id": "zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd",
"status": "ready",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/zzyaqh5d-0jjq-va0n-aajo-3zwlje2q3uqd.mp4",
"executionTime": 4120.36,
"transformation": {
"format": "mp4",
"size": {
"width": 1200,
"height": 800
},
"fit": "crop",
"resolution": "hd",
"quality": 70,
"fps": 25,
"speed": {
"speed": 1.5,
"preservePitch": false
},
"keyframeInterval": 10,
"fixOffset": true,
"fixRotation": true,
"enhance": {
"audio": {
"provider": "dolby",
"options": {
"preset": "studio"
}
}
},
"filename": "my-video"
},
"width": 1920,
"height": 1080,
"duration": 25.86,
"fps": 23.967
}
The id and attributes of the generated rendition file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The rendition id. |
| status | any | false | none | The status of the rendition transformation task.
|
| url | string | false | none | The URL of the rendition file hosted by Shotstack. The file at the URL can be used by the Edit API. Source file URL's consist of a base URL (AWS bucket), owner id, source id and a file name with the rendition id and extension. |
| executionTime | number(float) | false | none | The time in milliseconds it took to process the rendition. |
| transformation | Rendition | false | none | The transformation applied to the source file to create the rendition. |
| width | integer | false | none | The width in pixels of the ingested source file, if a video or image. |
| height | integer | false | none | The height in pixels of the ingested source file, if a video or image. |
| duration | number(float) | false | none | The duration in seconds of the ingested source file, if a video or audio file. |
| fps | number(float) | false | none | The frame rate in frames per second of the source file, if a video file. |
Enumerated Values
| Property | Value |
|---|---|
| status | queued |
| status | importing |
| status | ready |
| status | failed |
| status | deleted |
| status | overwritten |
UploadResponse
{
"data": {
"type": "upload",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
"expires": "2023-01-02T02:47:37.260Z"
}
}
}
The response returned by the Ingest API direct upload request. Includes the id of the file and the signed url to send the binary file to. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | UploadResponseData | true | none | An upload resource. |
UploadResponseData
{
"type": "upload",
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"attributes": {
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
"expires": "2023-01-02T02:47:37.260Z"
}
}
The type of resource (an upload), it's id and attributes of the upload request.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of resource, in this case it is an upload. |
| id | string | true | none | The upload file id. |
| attributes | UploadResponseAttributes | true | none | The upload attributes including the signed URL. |
UploadResponseAttributes
{
"id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
"url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
"expires": "2023-01-02T02:47:37.260Z"
}
The id and attributes of the upload file including the signed URL to send the binary file data to.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | true | none | The source id. |
| url | string | true | none | The signed URL to use in a PUT request to send the binary file to. |
| expires | string | true | none | The time the upload request will expire. The signed URL will expire after one hour. Upload must complete within one hour. |
IngestErrorResponse
{
"errors": [
{
"status": "400",
"title": "Validation Error",
"detail": "\"url\" is required"
}
]
}
Error response data for validation and other errors returned by the Ingest API.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| errors | [IngestErrorResponseData] | true | none | An array of errors. |
IngestErrorResponseData
{
"status": "400",
"title": "Validation Error",
"detail": "\"url\" is required"
}
Individual errors returned by the Ingest API.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | true | none | The http status code. |
| title | string | true | none | A short summary of the error. |
| detail | string | true | none | A detailed description of the error. |
GeneratedAssetResponse
{
"data": {
"type": "asset",
"id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
"attributes": {
"owner": "5ca6hu7s9k",
"provider": "shotstack",
"type": "text-to-speech",
"url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
"status": "done",
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
}
The response returned by the Create API generate asset and get generated asset requests. Includes status and details of the generated asset. The response follows the json:api specification.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | GeneratedAssetResponseData | true | none | A generated asset resource. |
GeneratedAssetResponseData
{
"type": "asset",
"id": "01gz0-tj679-xj30t-hr8zk-3hasvk",
"attributes": {
"owner": "5ca6hu7s9k",
"provider": "shotstack",
"type": "text-to-speech",
"url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
"status": "done",
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
}
The type of resource (an asset), it's id and attributes of the generated file.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | The type of resource, in this case it is an asset. |
| id | string | true | none | The generated asset id. |
| attributes | GeneratedAssetResponseAttributes | true | none | The generated asset attributes including its url, status, provider, type, etc... |
GeneratedAssetResponseAttributes
{
"owner": "5ca6hu7s9k",
"provider": "shotstack",
"type": "text-to-speech",
"url": "https://shotstack-create-api-v1-assets.s3.amazonaws.com/5ca6hu7s9k/01gz0-tj679-xj30t-hr8zk-3hasvk.mp3",
"status": "done",
"created": "2023-01-02T01:47:18.973Z",
"updated": "2023-01-02T01:47:37.260Z"
}
The id and attributes of the generated asset.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| owner | string | true | none | The owner id of the asset. |
| provider | string | true | none | The native or third party provider that generated the asset, shotstack, elevenlabs, heygen or d-id. |
| type | string | true | none | The type of service used to generate the asset, text-to-speech or text-to-avatar. |
| url | string | false | none | The URL of the asset file hosted by Shotstack. The file at the URL can be used by the Edit API. Generated asset file URL's consist of a base URL (AWS bucket), owner id, asset id and extension. The extension varies depending on the type of file generated. |
| status | string | true | none | The status of the asset file generation task.
|
| created | string | true | none | The time the generate asset task was initially queued. |
| updated | string | true | none | The time the asset status was last updated. |
Enumerated Values
| Property | Value |
|---|---|
| provider | shotstack |
| provider | elevenlabs |
| provider | heygen |
| provider | d-id |
| type | text-to-speech |
| type | text-to-avatar |
| status | queued |
| status | processing |
| status | saving |
| status | done |
| status | failed |
GeneratedAssetErrorResponse
{
"errors": [
{
"status": 400,
"title": "Bad Request",
"detail": "\"body/options/text\" is required."
}
]
}
Error response data for validation and other errors returned by the Create API.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| errors | [GeneratedAssetErrorResponseData] | true | none | An array of errors. |
GeneratedAssetErrorResponseData
{
"status": 400,
"title": "Bad Request",
"detail": "\"body/options/text\" is required."
}
Individual errors returned by the Create API.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | true | none | The http status code. |
| title | string | true | none | A short summary of the error. |
| detail | string | true | none | A detailed description of the error. |