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 captions 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.
    • captions (object - optional): Settings for the captions in the video
      • guideLines (string - optional): BBC/Netflix/YouTube/TED (see Caption Guidelines)
      • maxCharsLine: (number - optional): Maximum characters per line. Will override value from guideLines
      • maxLines: (number - optional): Maximum lines per caption. Will override value from guideLines
    • style (object - optional): Settings for the style of the captions in the video
      • font (string - optional): Font to use for the captions. Default is Arial
      • size (number - optional): Size of the captions. Default is 100%
      • bold (boolean - optional): Whether to use bold for the captions. Default is false
      • italic (boolean - optional): Whether to use italic for the captions. Default is false
      • underline (boolean - optional): Whether to use underline for the captions. Default is false
      • alignment: (string - optional): Alignment of the captions. For values see Caption Alignment
      • colorPrimary (string - optional): Primary color of the captions in RGB format e.g. #FFAA00
      • colorBack (string - optional): Background color of the captions in RGB format e.g. #FFAA00
  • reports (array): List of reports to download
    • report (string): Type of report to download e.g. ACCESSIBILITY. For values see Report Types

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,
      "captions": {
        "guideLines": "BBC",
        "maxCharsLine": 32,
        "maxLines": 1
      }
    }
  ]
}

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