Skip to main content

Download

The Download API allows clients to download media files.

How it Works

Clients request to download a bundle of media files.

  1. Download Bundle Request: Clients request to download a bundle of media files. The API will return a list of download IDs.
  2. Get Download Bundle Status: Clients request to get the status of a download bundle. The API will return the status of the download.
  3. 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 download
    • language (string): Language code of the transcription
    • format (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 is false.
  • captions (array): List of captions to download
    • language (string): Language code of the captions
    • format (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 is false.
  • audio (array): List of audio files to download
    • format (string): Format of the audio file to download e.g. MP (see Audio Formats)
  • video (array): List of video files to download
    • language (string): Language code of the video
    • includeSubtitles (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 is false.

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 bundle
  • items (array): List of download items.

Each item in the array will contain:

  • downloadId (string): ID of the download
  • fileId (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 Request
  • downloadBundleId (string): Download Bundle ID from Download Bundle Request

Response

200 status for valid download ID

  • downloadBundleId (string): ID of the download bundle
  • items (array): List of download items with status

Each item in the array will contain:

  • downloadId (string): ID of the download
  • status (string): Status of the download. See Service Statuses
  • fileId (string - optional): ID of the file to download
  • startTime (string): Date and time the download was created
  • endTime (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 Request
  • fileId (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 file
  • url (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"
}