Download
The Download API allows clients to download media files.
How it Works
Clients request to download a bundle of media files.
- Download Bundle Request: Clients request to download a bundle of media files. The API will return a list of download IDs.
- Get Download Bundle Status: Clients request to get the status of a download bundle. The API will return the status of the download.
- Download File: Clients request to download a file. The API will return a pre-signed URL to download the file.
What You Need
Clients of the Download Bundle API will need:
- An API key to use in header
x-api-key
for all requests. - The
x-api-key
header set with the API key received at registration. - The
mediaId
of the media item to download files from.
Endpoints
All API requests require the x-api-key
header to be set with the API key received at registration.
API paths use base URL https://api.getsubly.com/v2
Download Bundle Request
Download a bundle of media files.
Endpoint: POST /media/{mediaId}/download
Body Format: Content-Type: application/json
Path Parameters:
mediaId
(string): ID of the media item to download files from.
Body
transcriptions
(array): List of transcriptions to downloadlanguage
(string): Language code of the transcriptionformat
(string): Format of the transcription to download e.g. DOCX, TXT (see Transcription Formats)showSpeakers
(boolean - optional): Whether to show speakers in the transcription. Default isfalse
.
captions
(array): List of captions to downloadlanguage
(string): Language code of the captionsformat
(string): Format of the captions to download e.g. SRT, VTT (see Caption Formats)showSpeakers
(boolean - optional): Whether to show speakers in the captions. Default isfalse
.
audio
(array): List of audio files to downloadformat
(string): Format of the audio file to download e.g. MP (see Audio Formats)
video
(array): List of video files to downloadlanguage
(string): Language code of the videoincludeSubtitles
(boolean): Whether to include subtitles in the video.ratio
(string): Aspect ratio of the video e.g. 16:9, 4:3 (see Aspect Ratios)addDisclaimer
(boolean - optional): Whether to add a disclaimer to the video. Default isfalse
.
Example
{
"transcriptions": [
{
"language": "en-GB",
"format": "DOCX"
}
],
"captions": [
{
"language": "en-GB",
"format": "SRT"
}
],
"audio": [
{
"format": "MP3"
}
],
"video": [
{
"language": "en-GB",
"includeSubtitles": true,
"ratio": "16:9",
"addDisclaimer": true
}
]
}
Response
The API will return an download bundle ID and an array of details for each download requested
downloadBundleId
(string): ID of the download bundleitems
(array): List of download items.
Each item in the array will contain:
downloadId
(string): ID of the downloadfileId
(string - optional): ID of the file to download
The fileId
will be returned for
Example Response
{
"downloadBundleId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
"items": [
{
"downloadId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
"fileId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf"
}
]
}
Get Download Bundle Status
Gets the status of a download bundle. Supply the downloadBundleId
that was returned from the Download Bundle Request.
Endpoint: GET /media/:mediaId/download/:downloadBundleId
Parameters
mediaId
(string): Media ID from Download Bundle RequestdownloadBundleId
(string): Download Bundle ID from Download Bundle Request
Response
200
status for valid download ID
downloadBundleId
(string): ID of the download bundleitems
(array): List of download items with status
Each item in the array will contain:
downloadId
(string): ID of the downloadstatus
(string): Status of the download. See Service StatusesfileId
(string - optional): ID of the file to downloadstartTime
(string): Date and time the download was createdendTime
(string - optional): Date and time the download was completed
Example Response
{
"downloadBundleId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
"items": [
{
"downloadId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf"
"status": "COMPLETED",
"fileId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
"startTime": "2021-01-01T12:00:00Z",
"endTime": "2021-01-01T12:01:00Z"
}
]
}
Download File
Download a file. Supply the fileId
that was returned from the Get Download Status or Download Bundle Request.
Endpoint: GET /media/:mediaId/file/:fileId/download
Parameters
mediaId
(string): Media ID from Download Bundle RequestfileId
(string): File ID from Get Download Status or Download Bundle Request
Response
200
status for valid file ID
The response contains a pre-signed URL to download the file with a GET request
fileId
(string): ID of the fileurl
(string): Pre-signed URL to download the file
Example Response
{
"fileId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
"url": "https://my-storage-bucket.s3.amazonaws.com/my-file.docx"
}