Amazon Transcribe Service

2026/11/20 - Amazon Transcribe Service - 1 new api methods

Changes  This release adds the TranscribeAudio API for synchronous transcription. Send a media file inline or from Amazon S3 and receive the transcript in the same response, with support for speaker, channel identification, language identification, custom vocabularies, vocabulary filters, and PII redaction.

TranscribeAudio (new) Link ¶

Transcribes a media file and returns the transcript in the same response. There is no job to start and no status to poll.

Use TranscribeAudio when you already have a complete media file and want the transcript right away. For large files, long audio, or bulk processing, use .

You must include the following parameters in your TranscribeAudio request:

  • Media: Your audio, either as inline bytes ( MediaBytes) or as the Amazon S3 location of a media file ( MediaFileUri).

  • One of Language or LanguageDetectionMode: Specify the language of your audio, or have Amazon Transcribe identify it.

Your audio must be between 0.5 seconds and 1 hour long. Supported formats are WAV, MP3, FLAC, M4A, MP4, Ogg, WebM, and AMR.

If you send your audio in the request ( MediaBytes), the file can be up to 25 MB. If you provide an Amazon S3 location ( MediaFileUri), the file can be up to 500 MB.

Amazon Transcribe always turns on smart formatting, also known as inverse text normalization (ITN). It writes numbers, dates, currency, and similar items in their usual written form. For example, "one hundred" becomes "100". You can't turn smart formatting off.

By default, Amazon Transcribe returns the transcript in TranscriptResponse. If you include OutputConfiguration, Amazon Transcribe writes the transcript to the Amazon S3 location you specify instead, and the response contains only that location.

See also: AWS API Documentation

Request Syntax

client.transcribe_audio(
    Media={
        'MediaBytes': b'bytes',
        'MediaFileUri': 'string'
    },
    Language='en'|'es'|'fr'|'it'|'de'|'ja'|'pt'|'ko'|'zh-CN'|'zh-TW'|'zh-HK',
    LanguageDetectionMode='IDENTIFY_LANGUAGE',
    LanguageOptions=[
        'en'|'es'|'fr'|'it'|'de'|'ja'|'pt'|'ko'|'zh-CN'|'zh-TW'|'zh-HK',
    ],
    ChannelIdentification=True|False,
    ShowSpeakerLabels=True|False,
    MaxSpeakerLabels=123,
    VocabularySettings=[
        {
            'Language': 'en'|'es'|'fr'|'it'|'de'|'ja'|'pt'|'ko'|'zh-CN'|'zh-TW'|'zh-HK',
            'VocabularyName': 'string',
            'Phrases': [
                {
                    'Text': 'string',
                    'DisplayAs': 'string'
                },
            ]
        },
    ],
    VocabularyFilterSettings={
        'VocabularyFilterMethod': 'remove'|'mask'|'tag',
        'Filters': [
            {
                'Language': 'en'|'es'|'fr'|'it'|'de'|'ja'|'pt'|'ko'|'zh-CN'|'zh-TW'|'zh-HK',
                'VocabularyFilterName': 'string',
                'Words': [
                    'string',
                ]
            },
        ]
    },
    ContentRedaction={
        'RedactionType': 'PII',
        'RedactionOutput': 'redacted'|'redacted_and_unredacted',
        'PiiEntityTypes': [
            'BANK_ACCOUNT_NUMBER'|'BANK_ROUTING'|'CREDIT_DEBIT_NUMBER'|'CREDIT_DEBIT_CVV'|'CREDIT_DEBIT_EXPIRY'|'PIN'|'EMAIL'|'ADDRESS'|'NAME'|'PHONE'|'SSN'|'DATE_TIME'|'PASSPORT_NUMBER'|'DRIVER_ID'|'URL'|'AGE'|'USERNAME'|'PASSWORD'|'AWS_ACCESS_KEY'|'AWS_SECRET_KEY'|'IP_ADDRESS'|'MAC_ADDRESS'|'LICENSE_PLATE'|'VEHICLE_IDENTIFICATION_NUMBER'|'US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER'|'CA_HEALTH_NUMBER'|'CA_SOCIAL_INSURANCE_NUMBER'|'INTERNATIONAL_BANK_ACCOUNT_NUMBER'|'SWIFT_CODE'|'ALL',
        ]
    },
    OutputConfiguration={
        'OutputMediaFileUri': 'string'
    }
)
type Media:

dict

param Media:

[REQUIRED]

The audio to transcribe. Specify exactly one of MediaBytes or MediaFileUri.

Audio sent in the request ( MediaBytes) can be up to 25 MB. Audio in Amazon S3 ( MediaFileUri) can be up to 500 MB.

  • MediaBytes (bytes) --

    Your audio file, provided inline in the request. The maximum size is 25 MB (26,214,400 bytes) of audio, measured before base64 encoding.

    If you use an Amazon Web Services SDK, the SDK base64-encodes the bytes for you. If you call the API directly, base64-encode the bytes yourself.

  • MediaFileUri (string) --

    The Amazon S3 location of the media file you want to transcribe. For example:

    • s3://amzn-s3-demo-bucket/my-media-file.flac

    • s3://amzn-s3-demo-bucket/media-files/my-media-file.flac

    The maximum file size is 500 MB. You must have read permission for the file.

    The Amazon S3 bucket that contains your input media must be located in the same Amazon Web Services Region where you're making your transcription request.

type Language:

string

param Language:

The language spoken in your audio, as a base language code (for example, en or es).

Include either Language or LanguageDetectionMode in your request, but not both.

type LanguageDetectionMode:

string

param LanguageDetectionMode:

Enables automatic language identification. Use IDENTIFY_LANGUAGE if your audio contains a single language that you don't know in advance.

You can optionally include LanguageOptions to limit identification to languages you think may be present, which can improve accuracy.

Amazon Transcribe returns the identified language, as a locale (for example, en-US), in the response metadata.

Include either Language or LanguageDetectionMode in your request, but not both.

type LanguageOptions:

list

param LanguageOptions:

A list of two or more languages that you think may be present in your audio, as base language codes (for example, en and es). Each language can appear only once. A list with only one language returns a BadRequestException.

You can use LanguageOptions only with LanguageDetectionMode.

  • (string) --

type ChannelIdentification:

boolean

param ChannelIdentification:

Enables channel identification in multi-channel audio. Each channel is transcribed independently, and each item in the transcript is labeled with its channel.

Channel identification supports up to two channels.

type ShowSpeakerLabels:

boolean

param ShowSpeakerLabels:

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

If you set ShowSpeakerLabels to true, you must also include MaxSpeakerLabels.

For more information, see Partitioning speakers (diarization).

type MaxSpeakerLabels:

integer

param MaxSpeakerLabels:

Specify the maximum number of speakers you want to partition in your media.

Note that if your media contains more speakers than the specified number, Amazon Transcribe treats multiple speakers as a single speaker.

You can set MaxSpeakerLabels only if ShowSpeakerLabels is true.

type VocabularySettings:

list

param VocabularySettings:

Custom vocabularies to apply to your transcript, with one entry per language. In each entry, you can reference a custom vocabulary you created or provide phrases inline. All entries must use the same type, either all by name or all inline.

If you specify Language, include exactly one entry, and its Language must match. If you use LanguageDetectionMode, you can include one entry for each language in LanguageOptions.

  • (dict) --

    A custom vocabulary for one language. Specify exactly one of VocabularyName or Phrases.

    • Language (string) -- [REQUIRED]

      The language this custom vocabulary applies to, as a base language code (for example, en). Each language can appear in only one entry.

    • VocabularyName (string) --

      The name of a custom vocabulary you created. The vocabulary must be in the READY state, and its language must match this entry's Language.

      Vocabulary names are case sensitive.

      Include either VocabularyName or Phrases in each entry, but not both.

    • Phrases (list) --

      Up to 100 phrases to use as a custom vocabulary, provided inline. You don't need to create the vocabulary first.

      Include either Phrases or VocabularyName in each entry, but not both.

      • (dict) --

        A phrase in an inline custom vocabulary.

        • Text (string) -- [REQUIRED]

          The phrase to recognize in your audio.

        • DisplayAs (string) --

          How the phrase is written in your transcript. If you don't include DisplayAs, the phrase is written as it appears in Text.

type VocabularyFilterSettings:

dict

param VocabularyFilterSettings:

Custom vocabulary filters to apply to your transcript, and how to apply them.

  • VocabularyFilterMethod (string) -- [REQUIRED]

    Specify how you want your custom vocabulary filter applied to your transcript.

    To replace words with ***, choose mask.

    To delete words, choose remove.

    To flag words without changing them, choose tag.

  • Filters (list) -- [REQUIRED]

    Custom vocabulary filters, with one entry per language. In each entry, you can reference a custom vocabulary filter you created or provide words inline. All entries must use the same type, either all by name or all inline.

    If you specify Language, include exactly one entry, and its Language must match. If you use LanguageDetectionMode, you can include one entry for each language in LanguageOptions.

    • (dict) --

      A custom vocabulary filter for one language. Specify exactly one of VocabularyFilterName or Words.

      • Language (string) -- [REQUIRED]

        The language this custom vocabulary filter applies to, as a base language code (for example, en). Each language can appear in only one entry.

      • VocabularyFilterName (string) --

        The name of a custom vocabulary filter you created. The filter's language must match this entry's Language.

        Vocabulary filter names are case sensitive.

        Include either VocabularyFilterName or Words in each entry, but not both.

      • Words (list) --

        The words to filter, provided inline. You don't need to create the vocabulary filter first.

        Include either Words or VocabularyFilterName in each entry, but not both.

        • (string) --

type ContentRedaction:

dict

param ContentRedaction:

Redacts personally identifiable information (PII) from your transcript. Amazon Transcribe returns the redacted transcript in RedactedResults.

If you set RedactionOutput to redacted_and_unredacted, Amazon Transcribe also returns the unredacted transcript in Results.

In Sync, content redaction has these limits:

  • Languages: English ( en), Spanish ( es), French ( fr), Italian ( it), German ( de), and Portuguese ( pt).

  • Language identification: If you use LanguageDetectionMode, you must also include LanguageOptions, and every language in it must be one of the languages above. A request that has no LanguageOptions, or that lists a language that isn't supported, returns a BadRequestException.

  • Regions: Content redaction isn't available in the South America (São Paulo) Region ( sa-east-1). It's available in the other Amazon Web Services Regions where Sync is available.

  • RedactionType (string) -- [REQUIRED]

    Specify the category of information you want to redact; PII (personally identifiable information) is the only valid value. You can use PiiEntityTypes to choose which types of PII you want to redact. If you do not include PiiEntityTypes in your request, all PII is redacted.

  • RedactionOutput (string) -- [REQUIRED]

    Specify if you want only a redacted transcript, or if you want a redacted and an unredacted transcript.

    When you choose redacted Amazon Transcribe creates only a redacted transcript.

    When you choose redacted_and_unredacted Amazon Transcribe creates a redacted and an unredacted transcript. For batch jobs, Amazon Transcribe creates two separate files. For TranscribeAudio, Amazon Transcribe returns them in RedactedResults and Results, or writes them as two separate files if you use OutputConfiguration.

  • PiiEntityTypes (list) --

    Specify which types of personally identifiable information (PII) you want to redact in your transcript. You can include as many types as you'd like, or you can select ALL. If you do not include PiiEntityTypes in your request, all PII is redacted.

    • (string) --

type OutputConfiguration:

dict

param OutputConfiguration:

Writes the transcript to an Amazon S3 location instead of returning it in the response. If you include OutputConfiguration, the response contains only the output location.

You must have write permission for the location you specify.

  • OutputMediaFileUri (string) -- [REQUIRED]

    The Amazon S3 location where you want your transcript written. For example:

    • s3://amzn-s3-demo-bucket/my-transcript.json

    • s3://amzn-s3-demo-bucket/transcripts/

    If the location ends with an object key, Amazon Transcribe writes the transcript to that key. If it is a bucket or ends with a forward slash ( /), it's treated as a prefix, and Amazon Transcribe writes the transcript under it to a file named with the request ID of your call and a .json extension.

    If you use ContentRedaction, Amazon Transcribe writes the redacted transcript to the same location and adds redacted- before the file name (for example, redacted-my-transcript.json). With redacted_and_unredacted, Amazon Transcribe writes both files.

    If an object already exists at that key, Amazon Transcribe overwrites it.

    In a response, this is the location where Amazon Transcribe wrote your transcript. If you requested redacted_and_unredacted output, this is the location of the unredacted transcript.

rtype:

dict

returns:

Response Syntax

{
    'OutputConfiguration': {
        'OutputMediaFileUri': 'string'
    },
    'TranscriptResponse': {
        'Metadata': {
            'LanguageCode': 'en-US'|'en-AB'|'en-AU'|'en-GB'|'en-IE'|'en-IN'|'en-WL'|'en-ZA'|'en-NZ'|'es-US'|'es-ES'|'es-MX'|'fr-FR'|'fr-CA'|'it-IT'|'de-DE'|'de-CH'|'ja-JP'|'pt-BR'|'pt-PT'|'zh-CN'|'zh-TW'|'zh-HK'|'ko-KR',
            'LanguageCodes': [
                {
                    'LanguageCode': 'en-US'|'en-AB'|'en-AU'|'en-GB'|'en-IE'|'en-IN'|'en-WL'|'en-ZA'|'en-NZ'|'es-US'|'es-ES'|'es-MX'|'fr-FR'|'fr-CA'|'it-IT'|'de-DE'|'de-CH'|'ja-JP'|'pt-BR'|'pt-PT'|'zh-CN'|'zh-TW'|'zh-HK'|'ko-KR',
                    'DurationInSeconds': ...
                },
            ],
            'MediaFormat': 'mp3'|'mp4'|'wav'|'flac'|'ogg'|'amr'|'webm'|'m4a',
            'MediaSampleRateHertz': 123,
            'SpeakersCount': 123,
            'NumberOfChannels': 123
        },
        'Results': {
            'Transcript': 'string',
            'Items': [
                {
                    'Id': 123,
                    'Content': 'string',
                    'StartTime': 123.0,
                    'EndTime': 123.0,
                    'LanguageCode': 'en-US'|'en-AB'|'en-AU'|'en-GB'|'en-IE'|'en-IN'|'en-WL'|'en-ZA'|'en-NZ'|'es-US'|'es-ES'|'es-MX'|'fr-FR'|'fr-CA'|'it-IT'|'de-DE'|'de-CH'|'ja-JP'|'pt-BR'|'pt-PT'|'zh-CN'|'zh-TW'|'zh-HK'|'ko-KR',
                    'ChannelLabel': 'string',
                    'SpeakerLabel': 'string',
                    'VocabularyFilterMatch': True|False,
                    'Redactions': [
                        {
                            'Type': 'BANK_ACCOUNT_NUMBER'|'BANK_ROUTING'|'CREDIT_DEBIT_NUMBER'|'CREDIT_DEBIT_CVV'|'CREDIT_DEBIT_EXPIRY'|'PIN'|'EMAIL'|'ADDRESS'|'NAME'|'PHONE'|'SSN'|'DATE_TIME'|'PASSPORT_NUMBER'|'DRIVER_ID'|'URL'|'AGE'|'USERNAME'|'PASSWORD'|'AWS_ACCESS_KEY'|'AWS_SECRET_KEY'|'IP_ADDRESS'|'MAC_ADDRESS'|'LICENSE_PLATE'|'VEHICLE_IDENTIFICATION_NUMBER'|'US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER'|'CA_HEALTH_NUMBER'|'CA_SOCIAL_INSURANCE_NUMBER'|'INTERNATIONAL_BANK_ACCOUNT_NUMBER'|'SWIFT_CODE'|'ALL'
                        },
                    ]
                },
            ]
        },
        'RedactedResults': {
            'Transcript': 'string',
            'Items': [
                {
                    'Id': 123,
                    'Content': 'string',
                    'StartTime': 123.0,
                    'EndTime': 123.0,
                    'LanguageCode': 'en-US'|'en-AB'|'en-AU'|'en-GB'|'en-IE'|'en-IN'|'en-WL'|'en-ZA'|'en-NZ'|'es-US'|'es-ES'|'es-MX'|'fr-FR'|'fr-CA'|'it-IT'|'de-DE'|'de-CH'|'ja-JP'|'pt-BR'|'pt-PT'|'zh-CN'|'zh-TW'|'zh-HK'|'ko-KR',
                    'ChannelLabel': 'string',
                    'SpeakerLabel': 'string',
                    'VocabularyFilterMatch': True|False,
                    'Redactions': [
                        {
                            'Type': 'BANK_ACCOUNT_NUMBER'|'BANK_ROUTING'|'CREDIT_DEBIT_NUMBER'|'CREDIT_DEBIT_CVV'|'CREDIT_DEBIT_EXPIRY'|'PIN'|'EMAIL'|'ADDRESS'|'NAME'|'PHONE'|'SSN'|'DATE_TIME'|'PASSPORT_NUMBER'|'DRIVER_ID'|'URL'|'AGE'|'USERNAME'|'PASSWORD'|'AWS_ACCESS_KEY'|'AWS_SECRET_KEY'|'IP_ADDRESS'|'MAC_ADDRESS'|'LICENSE_PLATE'|'VEHICLE_IDENTIFICATION_NUMBER'|'US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER'|'CA_HEALTH_NUMBER'|'CA_SOCIAL_INSURANCE_NUMBER'|'INTERNATIONAL_BANK_ACCOUNT_NUMBER'|'SWIFT_CODE'|'ALL'
                        },
                    ]
                },
            ]
        }
    }
}

Response Structure

  • (dict) --

    • OutputConfiguration (dict) --

      The Amazon S3 location where your transcript was written. Present only if you included OutputConfiguration in your request. In that case, TranscriptResponse isn't returned.

      • OutputMediaFileUri (string) --

        The Amazon S3 location where you want your transcript written. For example:

        • s3://amzn-s3-demo-bucket/my-transcript.json

        • s3://amzn-s3-demo-bucket/transcripts/

        If the location ends with an object key, Amazon Transcribe writes the transcript to that key. If it is a bucket or ends with a forward slash ( /), it's treated as a prefix, and Amazon Transcribe writes the transcript under it to a file named with the request ID of your call and a .json extension.

        If you use ContentRedaction, Amazon Transcribe writes the redacted transcript to the same location and adds redacted- before the file name (for example, redacted-my-transcript.json). With redacted_and_unredacted, Amazon Transcribe writes both files.

        If an object already exists at that key, Amazon Transcribe overwrites it.

        In a response, this is the location where Amazon Transcribe wrote your transcript. If you requested redacted_and_unredacted output, this is the location of the unredacted transcript.

    • TranscriptResponse (dict) --

      Your transcript and information about your audio. Present only if you didn't include OutputConfiguration in your request.

      • Metadata (dict) --

        Information about your audio, such as the detected language, format, and sample rate.

        • LanguageCode (string) --

          The language of your transcript, as a locale (for example, en-US). Present if you used LanguageDetectionMode.

        • LanguageCodes (list) --

          The language identified in your audio, and how long it's spoken. Present if you used LanguageDetectionMode.

          • (dict) --

            A language identified in your audio, and how long it's spoken.

            • LanguageCode (string) --

              The identified language, as a locale (for example, en-US).

            • DurationInSeconds (float) --

              The total time, in seconds, the identified language is spoken in your audio.

        • MediaFormat (string) --

          The format of your audio, as detected by Amazon Transcribe.

        • MediaSampleRateHertz (integer) --

          The sample rate of your audio, in hertz, as detected by Amazon Transcribe.

        • SpeakersCount (integer) --

          The number of speakers identified in your audio. Present if you enabled ShowSpeakerLabels.

        • NumberOfChannels (integer) --

          The number of audio channels in your media. Present if you enabled ChannelIdentification.

      • Results (dict) --

        Your unredacted transcript.

        If you set RedactionOutput to redacted, Amazon Transcribe doesn't return this field. Use RedactedResults instead.

        • Transcript (string) --

          The full text of your transcript.

          If you enabled ChannelIdentification, the text of channel ch_0 is followed by the text of channel ch_1.

        • Items (list) --

          The words and punctuation in your transcript, with timing and any labels you requested.

          • (dict) --

            A word or punctuation mark in your transcript. Labels such as SpeakerLabel and ChannelLabel are present only if you enabled the related feature.

            • Id (integer) --

              The position of this item in the transcript, starting at 0.

            • Content (string) --

              The word or punctuation mark. In RedactedResults, Amazon Transcribe replaces redacted words with [PII].

            • StartTime (float) --

              The time, in seconds from the start of your audio, when this item starts.

            • EndTime (float) --

              The time, in seconds from the start of your audio, when this item ends.

            • LanguageCode (string) --

              The language of this item, as a locale (for example, en-US).

            • ChannelLabel (string) --

              The audio channel this item came from ( ch_0 or ch_1). Present if you enabled ChannelIdentification.

              Item start and end times are measured from the start of the audio, separately for each channel.

            • SpeakerLabel (string) --

              The speaker of this item (for example, spk_0). Present if you enabled ShowSpeakerLabels.

            • VocabularyFilterMatch (boolean) --

              Indicates whether this item matched a word in your custom vocabulary filter. Present if you included VocabularyFilterSettings.

            • Redactions (list) --

              The types of personally identifiable information (PII) that Amazon Transcribe redacted from this item. Present only on redacted items in RedactedResults.

              • (dict) --

                A type of personally identifiable information (PII) redacted from an item.

                • Type (string) --

                  The type of PII that was redacted, for example NAME or SSN.

      • RedactedResults (dict) --

        Your transcript with personally identifiable information (PII) redacted. Present only if you included ContentRedaction in your request.

        • Transcript (string) --

          The full text of your transcript.

          If you enabled ChannelIdentification, the text of channel ch_0 is followed by the text of channel ch_1.

        • Items (list) --

          The words and punctuation in your transcript, with timing and any labels you requested.

          • (dict) --

            A word or punctuation mark in your transcript. Labels such as SpeakerLabel and ChannelLabel are present only if you enabled the related feature.

            • Id (integer) --

              The position of this item in the transcript, starting at 0.

            • Content (string) --

              The word or punctuation mark. In RedactedResults, Amazon Transcribe replaces redacted words with [PII].

            • StartTime (float) --

              The time, in seconds from the start of your audio, when this item starts.

            • EndTime (float) --

              The time, in seconds from the start of your audio, when this item ends.

            • LanguageCode (string) --

              The language of this item, as a locale (for example, en-US).

            • ChannelLabel (string) --

              The audio channel this item came from ( ch_0 or ch_1). Present if you enabled ChannelIdentification.

              Item start and end times are measured from the start of the audio, separately for each channel.

            • SpeakerLabel (string) --

              The speaker of this item (for example, spk_0). Present if you enabled ShowSpeakerLabels.

            • VocabularyFilterMatch (boolean) --

              Indicates whether this item matched a word in your custom vocabulary filter. Present if you included VocabularyFilterSettings.

            • Redactions (list) --

              The types of personally identifiable information (PII) that Amazon Transcribe redacted from this item. Present only on redacted items in RedactedResults.

              • (dict) --

                A type of personally identifiable information (PII) redacted from an item.

                • Type (string) --

                  The type of PII that was redacted, for example NAME or SSN.