Skip to main content

Transcription API

The Transcribe API allows clients to get the transcription of a media item (video or audio). The input media is defined by an S3 bucket name and key along with the language spoken.

How it Works

Clients provide an input media item to the Subly Transcribe API. Subly then transcribes the input and when finished writes the transcription to the requested location in an SRT file.

What You Need​

Clients of the Transcribe API will need:

  • An S3 bucket in AWS that is accessible by Subly (see below for bucket configuration)
  • An API key to use in header x-api-key for all requests.

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

Transcribe Media Request​

Start transcription of Media

Endpoint: POST /transcribe

Body Format: Content-Type: application/json

Body​

  • input
    • media
      • bucket (string): Bucket containing the media
      • key (string): Key to identify the media file in the bucket
      • language (string): Language code for transcription e.g. en-US, en-GB (see full list below)
      • type (string): Type of media (see full list below)
    • options (optional)
      • maxCharsLine (number - optional): Maximum number of characters per line in the transcription. Default is 42.
      • maxLines (number - optional): Maximum number of lines in the transcription. Default is 2.
      • newLineAfterPunctuation (boolean - optional): Whether to start a new line after punctuation. Default is true.
  • output
    • bucket (string): Bucket to put output transcription
    • key (string): Directory to put output transcription to

Example​

{
  "input": {
    "media": {
      "bucket": "my-storage-bucket",
      "key": "my-video.mp4",
      "language": "en-GB",
      "type": "video/mp4"
    }
  },
  "output": {
    "bucket": "my-storage-bucket",
    "key": "my-video"
  }
}

Response​

200 status for successful job

  • jobId (string): Job ID of successful transcribe job

Example Response​

{
  "jobId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf"
}

Transcribe Job Status​

Gets the status of a transcribe job. Supply the jobId that was returned from the Transcribe Media Request.

Endpoint: GET /transcribe/status/:jobId

Body Format: Content-Type: application/json

Parameters​

  • jobId (string): Job ID from Transcribe Media Request

Response​

200 status for valid job ID

  • jobId (string)
  • language (string) - Language of the transcribe job
  • status (string) - QUEUED, IN_PROGRESS, FAILED, COMPLETED
  • creationTime (timestamp)
  • completedTime (timestamp - optional)
  • failureReason (string - optional): Information on why the job failed if status is FAILED
  • output (array - optional): List of output files written

For each output item there are the following fields

  • type (string) - SRT, Transcription
  • bucket (string)
  • key (string)

Example Response​

{
  "jobId": "fb80e3e2-a7d1-4cac-a302-3320d3de8edf",
  "status": "COMPLETED",
  "language": "en-US",
  "creationTime": "2021-05-31T11:57:32.992Z",
  "completedTime": "2021-05-31T11:58:32.992Z",
  "output": [
    {
      "type": "SRT",
      "bucket": "my-storage-bucket",
      "key": "my-video/subtitles.srt"
    },
    {
      "type": "Transcription",
      "bucket": "my-storage-bucket",
      "key": "my-video/transcription.json"
    }
  ]
}

Supported Options

Available Languages​

Available languages for transcribe are:

  • en-AU: English (Australian)
  • en-GB: English (British)
  • en-US: English (US)
  • en-IN: English (Indian)
  • en-IE: English (Irish)
  • en-AB: English (Scottish)
  • en-WL: English (Welsh)
  • en-ZA: English (South African)
  • en-NZ: English (New Zealand)
  • af-ZA: Afrikaans
  • ar-AE: Arabic (Gulf)
  • ar-SA: Arabic (Modern Standard)
  • zh-CN: Chinese (Simplified)
  • zh-TW: Chinese (Traditional)
  • da-DK: Danish
  • nl-NL: Dutch
  • fr-FR: French
  • fr-CA: French (Canadian)
  • de-DE: German
  • de-CH: German (Swiss)
  • he-IL: Hebrew
  • hi-IN: Hindi (Indian)
  • id-ID: Indonesian
  • it-IT: Italian
  • ja-JP: Japanese
  • ko-KR: Korean
  • ms-MY: Malay
  • pt-PT: Portuguese
  • pt-BR: Portuguese (Brazilian)
  • ru-RU: Russian
  • es-ES: Spanish
  • es-US: Spanish (US)
  • ta-IN: Tamil
  • te-IN: Telugu
  • th-TH: Thai
  • tr-TR: Turkish

Media Type​

  • video/mp4: MP4 video
  • audio/mpeg: MP3 audio