Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

StartMedicalStreamTranscription

Starts a bidirectional HTTP/2 or WebSocket stream where audio is streamed to Amazon Transcribe Medical and the transcription results are streamed to your application.

The following parameters are required:

language-code
media-encoding
sample-rate

For more information on streaming with Amazon Transcribe Medical, see Transcribing streaming audio.

Request Syntax


POST /medical-stream-transcription HTTP/1.1
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
x-amzn-transcribe-vocabulary-name: VocabularyName
x-amzn-transcribe-specialty: Specialty
x-amzn-transcribe-type: Type
x-amzn-transcribe-show-speaker-label: ShowSpeakerLabel
x-amzn-transcribe-session-id: SessionId
x-amzn-transcribe-enable-channel-identification: EnableChannelIdentification
x-amzn-transcribe-number-of-channels: NumberOfChannels
x-amzn-transcribe-content-identification-type: ContentIdentificationType
Content-type: application/json

{
   "AudioEvent": { 
      "AudioChunk": blob
   },
   "ConfigurationEvent": { 
      "ChannelDefinitions": [ 
         { 
            "ChannelId": number,
            "ParticipantRole": "string"
         }
      ],
      "PostCallAnalyticsSettings": { 
         "ContentRedactionOutput": "string",
         "DataAccessRoleArn": "string",
         "OutputEncryptionKMSKeyId": "string",
         "OutputLocation": "string"
      }
   }
}

URI Request Parameters

The request uses the following URI parameters.

ContentIdentificationType

Labels all personal health information (PHI) identified in your transcript.

Content identification is performed at the segment level; PHI is flagged upon complete transcription of an audio segment.

For more information, see Identifying personal health information (PHI) in a transcription.

Valid Values: PHI

EnableChannelIdentification

Enables channel identification in multi-channel audio.

Channel identification transcribes the audio on each channel independently, then appends the output for each channel into one transcript.

If you have multi-channel audio and do not enable channel identification, your audio is transcribed in a continuous manner and your transcript is not separated by channel.

If you include EnableChannelIdentification in your request, you must also include NumberOfChannels.

For more information, see Transcribing multi-channel audio.

LanguageCode

Specify the language code that represents the language spoken in your audio.

Important

Amazon Transcribe Medical only supports US English (en-US).

Required: Yes

MediaEncoding

Specify the encoding used for the input audio. Supported formats are:

FLAC
OPUS-encoded audio in an Ogg container
PCM (only signed 16-bit little-endian audio formats, which does not include WAV)

For more information, see Media formats.

Valid Values: pcm | ogg-opus | flac

Required: Yes

MediaSampleRateHertz

The sample rate of the input audio (in hertz). Amazon Transcribe Medical supports a range from 16,000 Hz to 48,000 Hz. Note that the sample rate you specify must match that of your audio.

Valid Range: Minimum value of 8000. Maximum value of 48000.

Required: Yes

NumberOfChannels

Specify the number of channels in your audio stream. This value must be 2, as only two channels are supported. If your audio doesn't contain multiple channels, do not include this parameter in your request.

If you include NumberOfChannels in your request, you must also include EnableChannelIdentification.

Valid Range: Minimum value of 2.

SessionId

Specify a name for your transcription session. If you don't include this parameter in your request, Amazon Transcribe Medical generates an ID and returns it in the response.

Length Constraints: Fixed length of 36.

Pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}

ShowSpeakerLabel

Enables speaker partitioning (diarization) in your transcription output. Speaker partitioning labels the speech from individual speakers in your media file.

For more information, see Partitioning speakers (diarization).

Specialty

Specify the medical specialty contained in your audio.

Required: Yes

Type

Specify the type of input audio. For example, choose DICTATION for a provider dictating patient notes and CONVERSATION for a dialogue between a patient and a medical professional.

Valid Values: CONVERSATION | DICTATION

Required: Yes

VocabularyName

Specify the name of the custom vocabulary that you want to use when processing your transcription. Note that vocabulary names are case sensitive.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Request Body

The request accepts the following data in JSON format.

AudioEvent

A blob of audio from your application. Your audio stream consists of one or more audio events.

For more information, see Event stream encoding.

Type: AudioEvent object

Required: No

ConfigurationEvent

Contains audio channel definitions and post-call analytics settings.

Type: ConfigurationEvent object

Required: No

Response Syntax


HTTP/1.1 200
x-amzn-request-id: RequestId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
x-amzn-transcribe-vocabulary-name: VocabularyName
x-amzn-transcribe-specialty: Specialty
x-amzn-transcribe-type: Type
x-amzn-transcribe-show-speaker-label: ShowSpeakerLabel
x-amzn-transcribe-session-id: SessionId
x-amzn-transcribe-enable-channel-identification: EnableChannelIdentification
x-amzn-transcribe-number-of-channels: NumberOfChannels
x-amzn-transcribe-content-identification-type: ContentIdentificationType
Content-type: application/json

{
   "BadRequestException": { 
   },
   "ConflictException": { 
   },
   "InternalFailureException": { 
   },
   "LimitExceededException": { 
   },
   "ServiceUnavailableException": { 
   },
   "TranscriptEvent": { 
      "Transcript": { 
         "Results": [ 
            { 
               "Alternatives": [ 
                  { 
                     "Entities": [ 
                        { 
                           "Category": "string",
                           "Confidence": number,
                           "Content": "string",
                           "EndTime": number,
                           "StartTime": number
                        }
                     ],
                     "Items": [ 
                        { 
                           "Confidence": number,
                           "Content": "string",
                           "EndTime": number,
                           "Speaker": "string",
                           "StartTime": number,
                           "Type": "string"
                        }
                     ],
                     "Transcript": "string"
                  }
               ],
               "ChannelId": "string",
               "EndTime": number,
               "IsPartial": boolean,
               "ResultId": "string",
               "StartTime": number
            }
         ]
      }
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

ContentIdentificationType

Shows whether content identification was enabled for your transcription.

Valid Values: PHI

EnableChannelIdentification

Shows whether channel identification was enabled for your transcription.

LanguageCode

Provides the language code that you specified in your request. This must be en-US.

MediaEncoding

Provides the media encoding you specified in your request.

Valid Values: pcm | ogg-opus | flac

MediaSampleRateHertz

Provides the sample rate that you specified in your request.

Valid Range: Minimum value of 8000. Maximum value of 48000.

NumberOfChannels

Provides the number of channels that you specified in your request.

Valid Range: Minimum value of 2.

RequestId

Provides the identifier for your streaming request.

SessionId

Provides the identifier for your transcription session.

Length Constraints: Fixed length of 36.

Pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}

ShowSpeakerLabel

Shows whether speaker partitioning was enabled for your transcription.

Specialty

Provides the medical specialty that you specified in your request.

Type

Provides the type of audio you specified in your request.

Valid Values: CONVERSATION | DICTATION

VocabularyName

Provides the name of the custom vocabulary that you specified in your request.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

The following data is returned in JSON format by the service.

BadRequestException

One or more arguments to the StartStreamTranscription, StartMedicalStreamTranscription, or StartCallAnalyticsStreamTranscription operation was not valid. For example, MediaEncoding or LanguageCode used unsupported values. Check the specified parameters and try your request again.

Type: Exception

HTTP Status Code: 400

ConflictException

A new stream started with the same session ID. The current stream has been terminated.

Type: Exception

HTTP Status Code: 409

InternalFailureException

A problem occurred while processing the audio. Amazon Transcribe terminated processing.

Type: Exception

HTTP Status Code: 500

LimitExceededException

Your client has exceeded one of the Amazon Transcribe limits. This is typically the audio length limit. Break your audio stream into smaller chunks and try your request again.

Type: Exception

HTTP Status Code: 429

ServiceUnavailableException

The service is currently unavailable. Try your request later.

Type: Exception

HTTP Status Code: 503

TranscriptEvent

The MedicalTranscriptEvent associated with a MedicalTranscriptResultStream.

Contains a set of transcription results from one or more audio segments, along with additional information per your request parameters. This can include information relating to alternative transcriptions, channel identification, partial result stabilization, language identification, and other transcription-related data.

Type: MedicalTranscriptEvent object

Errors

For information about the errors that are common to all actions, see Common Errors.

BadRequestException

HTTP Status Code: 400

ConflictException

A new stream started with the same session ID. The current stream has been terminated.

HTTP Status Code: 409

InternalFailureException

A problem occurred while processing the audio. Amazon Transcribe terminated processing.

HTTP Status Code: 500

LimitExceededException

Your client has exceeded one of the Amazon Transcribe limits. This is typically the audio length limit. Break your audio stream into smaller chunks and try your request again.

HTTP Status Code: 429

ServiceUnavailableException

The service is currently unavailable. Try your request later.

HTTP Status Code: 503