Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Preferences
Contact Us
Feedback
AWS Documentation
Create an AWS Account
StartMedicalScribeStream - Amazon Transcribe
Request SyntaxURI Request ParametersRequest BodyResponse SyntaxResponse ElementsErrorsSee Also

StartMedicalScribeStream

PDF

Starts a bidirectional HTTP/2 stream, where audio is streamed to AWS HealthScribe and the transcription results are streamed to your application.

When you start a stream, you first specify the stream configuration in a MedicalScribeConfigurationEvent. This event includes channel definitions, encryption settings, and post-stream analytics settings, such as the output configuration for aggregated transcript and clinical note generation. These are additional streaming session configurations beyond those provided in your initial start request headers. Whether you are starting a new session or resuming an existing session, your first event must be a MedicalScribeConfigurationEvent.

After you send a MedicalScribeConfigurationEvent, you start AudioEvents and AWS HealthScribe responds with real-time transcription results. When you are finished, to start processing the results with the post-stream analytics, send a MedicalScribeSessionControlEvent with a Type of END_OF_SESSION and AWS HealthScribe starts the analytics.

You can pause or resume streaming. To pause streaming, complete the input stream without sending the MedicalScribeSessionControlEvent. To resume streaming, call the StartMedicalScribeStream and specify the same SessionId you used to start the stream.

The following parameters are required:

  • language-code

  • media-encoding

  • media-sample-rate-hertz

For more information on streaming with AWS HealthScribe, see AWS HealthScribe.

Request Syntax

POST /medical-scribe-stream HTTP/1.1
x-amzn-transcribe-session-id: SessionId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
Content-type: application/json

{
   "AudioEvent": { 
      "AudioChunk": blob
   },
   "ConfigurationEvent": { 
      "ChannelDefinitions": [ 
         { 
            "ChannelId": number,
            "ParticipantRole": "string"
         }
      ],
      "EncryptionSettings": { 
         "KmsEncryptionContext": { 
            "string" : "string" 
         },
         "KmsKeyId": "string"
      },
      "PostStreamAnalyticsSettings": { 
         "ClinicalNoteGenerationSettings": { 
            "NoteTemplate": "string",
            "OutputBucketName": "string"
         }
      },
      "ResourceAccessRoleArn": "string",
      "VocabularyFilterMethod": "string",
      "VocabularyFilterName": "string",
      "VocabularyName": "string"
   },
   "SessionControlEvent": { 
      "Type": "string"
   }
}

URI Request Parameters

The request uses the following URI parameters.

LanguageCode

Specify the language code for your HealthScribe streaming session.

Valid Values: 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

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

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

Required: Yes

SessionId

Specify an identifier for your streaming session (in UUID format). If you don't include a SessionId in your request, AWS HealthScribe 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}

Request Body

The request accepts the following data in JSON format.

AudioEvent

A wrapper for your audio chunks

For more information, see Event stream encoding.

Type: MedicalScribeAudioEvent object

Required: No

ConfigurationEvent

Specify additional streaming session configurations beyond those provided in your initial start request headers. For example, specify channel definitions, encryption settings, and post-stream analytics settings.

Whether you are starting a new session or resuming an existing session, your first event must be a MedicalScribeConfigurationEvent.

Type: MedicalScribeConfigurationEvent object

Required: No

SessionControlEvent

Specify the lifecycle of your streaming session, such as ending the session.

Type: MedicalScribeSessionControlEvent object

Required: No

Response Syntax

HTTP/1.1 200
x-amzn-transcribe-session-id: SessionId
x-amzn-request-id: RequestId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
Content-type: application/json

{
   "BadRequestException": { 
   },
   "ConflictException": { 
   },
   "InternalFailureException": { 
   },
   "LimitExceededException": { 
   },
   "ServiceUnavailableException": { 
   },
   "TranscriptEvent": { 
      "TranscriptSegment": { 
         "BeginAudioTime": number,
         "ChannelId": "string",
         "Content": "string",
         "EndAudioTime": number,
         "IsPartial": boolean,
         "Items": [ 
            { 
               "BeginAudioTime": number,
               "Confidence": number,
               "Content": "string",
               "EndAudioTime": number,
               "Type": "string",
               "VocabularyFilterMatch": boolean
            }
         ],
         "SegmentId": "string"
      }
   }
}

Response Elements

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

The response returns the following HTTP headers.

LanguageCode

The Language Code that you specified in your request. Same as provided in the StartMedicalScribeStreamRequest.

Valid Values: en-US

MediaEncoding

The Media Encoding you specified in your request. Same as provided in the StartMedicalScribeStreamRequest

Valid Values: pcm | ogg-opus | flac

MediaSampleRateHertz

The sample rate (in hertz) that you specified in your request. Same as provided in the StartMedicalScribeStreamRequest

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

RequestId

The unique identifier for your streaming request.

SessionId

The identifier (in UUID format) for your streaming session.

If you already started streaming, this is same ID as the one you specified in your initial StartMedicalScribeStreamRequest.

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}

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 transcript event that contains real-time transcription results.

Type: MedicalScribeTranscriptEvent object

Errors

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

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.

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

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following:

Need help?

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.