MRH.io

Amazon Transcribe Ad-Hoc Documentation

January 17, 2018

At the time of this writing, the API reference in the docs is… well… let’s just say it Leaves something to be desired

Luckily, the zip file came with a helpful file called service-2.json that gives us some clues.

{
  "version":"2.0",
  "metadata":{ ... },
  "operations":{
    "GetTranscriptionJob":{
      "name":"GetTranscriptionJob",
      "http":{
        "method":"POST",
        "requestUri":"/"
      },
      "input":{"shape":"GetTranscriptionJobRequest"},
      "output":{"shape":"GetTranscriptionJobResponse"},
      "errors":[
        {"shape":"BadRequestException"},
        {"shape":"LimitExceededException"},
        {"shape":"InternalFailureException"},
        {"shape":"NotFoundException"}
      ]
    },
    "ListTranscriptionJobs":{
      "name":"ListTranscriptionJobs",
      "http":{
        "method":"POST",
        "requestUri":"/"
      },
      "input":{"shape":"ListTranscriptionJobsRequest"},
      "output":{"shape":"ListTranscriptionJobsResponse"},
      "errors":[
        {"shape":"BadRequestException"},
        {"shape":"LimitExceededException"},
        {"shape":"InternalFailureException"}
      ]
    },
    "StartTranscriptionJob":{
      "name":"StartTranscriptionJob",
      "http":{
        "method":"POST",
        "requestUri":"/"
      },
      "input":{"shape":"StartTranscriptionJobRequest"},
      "output":{"shape":"StartTranscriptionJobResponse"},
      "errors":[
        {"shape":"BadRequestException"},
        {"shape":"LimitExceededException"},
        {"shape":"InternalFailureException"},
        {"shape":"ConflictException"}
      ]
    }
  },
  "shapes":{ ... }
}

Looks like we can List Transcription Jobs, Get a Transcription Job, and Start a Transcription Job.

The “shapes” section is longer and not listed but I gather that those are similar to data models or data structure interfaces that the APIs are either expecting, or will return.

So, from there we might be able to pull together something that might look like this:

AWS Transcribe API Documentation

GetTranscriptionJob

Method: POST

Example


Input:

{
  "TranscriptionJobName": string
}

Output:

"TranscriptionJob":{
  "TranscriptionJobName": string,
  "TranscriptionJobStatus": string, one of "IN_PROGRESS", "FAILED", "COMPLETED",
  "LanguageCode": string, one of "en-US", "es-US",
  "MediaSampleRateHertz": int,
  "MediaFormat": string, one of "mp3", "mp4", "wav", "flac",
  "Media": {
    "MediaFileUri": string in URI format
  },
  "Transcript": {
    "TranscriptFileUri": string in URI format
  },
  "CreationTime": datetime
  "CompletionTime": datetime,
  "FailureReason": string
}

Possible Errors:

  • BadRequestExceptionawaw
  • LimitExceededException
  • InternalFailureException
  • NotFoundException

ListTranscriptionJobs

Method: POST

Example:


Inputs:

{
  "Status": string, one of "IN_PROGRESS", "FAILED", "COMPLETED",
  "NextToken": string,
  "MaxResults": integer
}

note: should NextToken be integer?

Outputs:

{
  "TranscriptionJobSummaries": [
      {
        "TranscriptionJobName": string,
        "CreationTime": datetime,
        "CompletionTime": datetime,
        "LanguageCode": string, one of "en-US", "es-US",
        "TranscriptionJobStatus": string, one of "IN_PROGRESS", "FAILED", "COMPLETED",
        "FailureReason": string
      }
  ]
}

Possible Errors:
- BadRequestException
- LimitExceededException
- InternalFailureException

#### StartTranscriptionJob

Method: POST

Example:
```javascript

Kyle Mathews

This is the website of Mark Robert Henderson. He lives in Cape Ann, works in Cambridge, and plays with distributed apps and tech philosophy online.

Mark's social media presence is slowly and deliberately withering away, so the best way to reach him is via e-mail.