Transcribe audio

Create a transcript from a media file that is accessible via a URL.

Authorizations

Authorization · string · header · required

Body

application/json

Params to create a transcript

The parameters for creating a transcript

audio_url · string<url> · required

The URL of the audio or video file to transcribe.

language_code · default: en_us

The language of your audio file. Possible values are found in Supported Languages. The default value is 'en_us'.

Available options:

en,

en_au,

en_uk,

en_us,

es,

fr,

de,

it,

pt,

nl,

af,

sq,

am,

ar,

hy,

as,

az,

ba,

eu,

be,

bn,

bs,

br,

bg,

my,

ca,

zh,

hr,

cs,

da,

et,

fo,

fi,

gl,

ka,

el,

gu,

ht,

ha,

haw,

he,

hi,

hu,

is,

id,

ja,

jw,

kn,

kk,

km,

ko,

lo,

la,

lv,

ln,

lt,

lb,

mk,

mg,

ms,

ml,

mt,

mi,

mr,

mn,

ne,

no,

nn,

oc,

pa,

ps,

fa,

pl,

ro,

ru,

sa,

sr,

sn,

sd,

si,

sk,

sl,

so,

su,

sw,

sv,

tl,

tg,

ta,

tt,

te,

th,

bo,

tr,

tk,

uk,

ur,

uz,

vi,

cy,

yi,

yo

language_detection · boolean · default: false

Enable Automatic language detection, either true or false.

language_confidence_threshold · number · default: 0

The confidence threshold for the automatically detected language. An error will be returned if the language confidence is below this threshold. Defaults to 0.

Required range: 0 <= x <= 1

speech_model · enum<string> | null · default: best

The speech model to use for the transcription. When null, the "best" model is used.

Available options:

best,

nano

punctuate · boolean · default: true

Enable Automatic Punctuation, can be true or false

format_text · boolean · default: true

Enable Text Formatting, can be true or false

disfluencies · boolean · default: false

Transcribe Filler Words, like "umm", in your media file; can be true or false

multichannel · boolean · default: false

Enable Multichannel transcription, can be true or false.

dual_channel · boolean · default: false · deprecated

Enable Dual Channel transcription, can be true or false.

webhook_url · string<url>

The URL to which we send webhook requests. We sends two different types of webhook requests. One request when a transcript is completed or failed, and one request when the redacted audio is ready if redact_pii_audio is enabled.

webhook_auth_header_name · string | null

The header name to be sent with the transcript completed or failed webhook requests

webhook_auth_header_value · string | null

The header value to send back with the transcript completed or failed webhook requests for added security

auto_highlights · boolean · default: false

Enable Key Phrases, either true or false

audio_start_from · integer

The point in time, in milliseconds, to begin transcribing in your media file

audio_end_at · integer

The point in time, in milliseconds, to stop transcribing in your media file

word_boost · string[]

The list of custom vocabulary to boost transcription probability for

boost_param · enum<string>

How much to boost specified words

Available options:

low,

default,

high

filter_profanity · boolean · default: false

Filter profanity from the transcribed text, can be true or false

redact_pii · boolean · default: false

Redact PII from the transcribed text using the Redact PII model, can be true or false

redact_pii_audio · boolean · default: false

Generate a copy of the original media file with spoken PII "beeped" out, can be true or false. See PII redaction for more details.

redact_pii_audio_quality · enum<string>

Controls the filetype of the audio created by redact_pii_audio. Currently supports mp3 (default) and wav. See PII redaction for more details.

Available options:

mp3,

wav

Example:

"mp3"

redact_pii_policies · enum<string>[]

The list of PII Redaction policies to enable. See PII redaction for more details.

Show child attributes

redact_pii_sub · enum<string> | null · default: hash

The replacement logic for detected PII, can be "entity_type" or "hash". See PII redaction for more details. The replacement logic for detected PII, can be "entity_name" or "hash". See PII redaction for more details.

Available options:

entity_name,

hash

speaker_labels · boolean · default: false

Enable Speaker diarization, can be true or false

speakers_expected · integer | null

Tells the speaker label model how many speakers it should attempt to identify, up to 10. See Speaker diarization for more details.

content_safety · boolean · default: false

Enable Content Moderation, can be true or false

content_safety_confidence · integer · default: 50

The confidence threshold for the Content Moderation model. Values must be between 25 and 100.

Required range: 25 <= x <= 100

iab_categories · boolean · default: false

Enable Topic Detection, can be true or false

custom_spelling · object[]

Customize how words are spelled and formatted using to and from values

Show child attributes

sentiment_analysis · boolean · default: false

Enable Sentiment Analysis, can be true or false

auto_chapters · boolean · default: false

Enable Auto Chapters, can be true or false

entity_detection · boolean · default: false

Enable Entity Detection, can be true or false

speech_threshold · number | null · default: 0

Reject audio files that contain less than this fraction of speech. Valid values are in the range [0, 1] inclusive.

Required range: 0 <= x <= 1

summarization · boolean · default: false

Enable Summarization, can be true or false

summary_model · enum<string>

The model to summarize the transcript

Available options:

informative,

conversational,

catchy

summary_type · enum<string>

The type of summary

Available options:

bullets,

bullets_verbose,

gist,

headline,

paragraph

custom_topics · boolean · default: false

Enable custom topics, either true or false

topics · string[]

The list of custom topics

Response

200

application/json

Transcript created and queued for processing

A transcript object

id · string<uuid> · required

The unique identifier of your transcript

audio_url · string<url> · required

The URL of the media that was transcribed

status · enum<string> · required

The status of your transcript. Possible values are queued, processing, completed, or error.

Available options:

queued,

processing,

completed,

error

language_confidence_threshold · number | null · required

The confidence threshold for the automatically detected language. An error will be returned if the language confidence is below this threshold.

Required range: 0 <= x <= 1

language_confidence · number | null · required

The confidence score for the detected language, between 0.0 (low confidence) and 1.0 (high confidence)

Required range: 0 <= x <= 1

speech_model · enum<string> | null · required

The speech model used for the transcription. When null, the default model is used. The speech model to use for the transcription.

Available options:

best,

nano

webhook_auth · boolean · required

Whether webhook authentication details were provided

auto_highlights · boolean · required

Whether Key Phrases is enabled, either true or false

redact_pii · boolean · required

Whether PII Redaction is enabled, either true or false

summarization · boolean · required

Whether Summarization is enabled, either true or false

language_model · string · required · deprecated

The language model that was used for the transcript

acoustic_model · string · required · deprecated

The acoustic model that was used for the transcript

language_code

The language of your audio file. Possible values are found in Supported Languages. The default value is 'en_us'.

The language of your audio file. Possible values are found in Supported Languages. The default value is 'en_us'.

Available options:

en,

en_au,

en_uk,

en_us,

es,

fr,

de,

it,

pt,

nl,

af,

sq,

am,

ar,

hy,

as,

az,

ba,

eu,

be,

bn,

bs,

br,

bg,

my,

ca,

zh,

hr,

cs,

da,

et,

fo,

fi,

gl,

ka,

el,

gu,

ht,

ha,

haw,

he,

hi,

hu,

is,

id,

ja,

jw,

kn,

kk,

km,

ko,

lo,

la,

lv,

ln,

lt,

lb,

mk,

mg,

ms,

ml,

mt,

mi,

mr,

mn,

ne,

no,

nn,

oc,

pa,

ps,

fa,

pl,

ro,

ru,

sa,

sr,

sn,

sd,

si,

sk,

sl,

so,

su,

sw,

sv,

tl,

tg,

ta,

tt,

te,

th,

bo,

tr,

tk,

uk,

ur,

uz,

vi,

cy,

yi,

yo

language_detection · boolean | null

Whether Automatic language detection is enabled, either true or false

text · string | null

The textual transcript of your media file

words · object[] | null

An array of temporally-sequential word objects, one for each word in the transcript. See Speech recognition for more information.

Show child attributes

utterances · object[] | null

When dual_channel or speaker_labels is enabled, a list of turn-by-turn utterance objects. See Speaker diarization for more information.

Show child attributes

confidence · number | null

The confidence score for the transcript, between 0.0 (low confidence) and 1.0 (high confidence)

Required range: 0 <= x <= 1

audio_duration · integer | null

The duration of this transcript object's media file, in seconds

punctuate · boolean | null

Whether Automatic Punctuation is enabled, either true or false

format_text · boolean | null

Whether Text Formatting is enabled, either true or false

disfluencies · boolean | null

Transcribe Filler Words, like "umm", in your media file; can be true or false

multichannel · boolean | null

Whether Multichannel transcription was enabled in the transcription request, either true or false

audio_channels · integer

The number of audio channels in the audio file. This is only present when multichannel is enabled.

dual_channel · boolean | null · deprecated

Whether Dual channel transcription was enabled in the transcription request, either true or false

webhook_url · string<url> | null

The URL to which we send webhook requests. We sends two different types of webhook requests. One request when a transcript is completed or failed, and one request when the redacted audio is ready if redact_pii_audio is enabled.

webhook_status_code · integer | null

The status code we received from your server when delivering the transcript completed or failed webhook request, if a webhook URL was provided

webhook_auth_header_name · string | null

The header name to be sent with the transcript completed or failed webhook requests

speed_boost · boolean | null · deprecated

Whether speed boost is enabled

auto_highlights_result · object | null

An array of results for the Key Phrases model, if it is enabled. See Key Phrases for more information.

An array of results for the Key Phrases model, if it is enabled. See Key phrases for more information.

Show child attributes

Example:

{
  "status": "success",
  "results": [
    {
      "count": 1,
      "rank": 0.08,
      "text": "air quality alerts",
      "timestamps": [{ "start": 3978, "end": 5114 }]
    },
    {
      "count": 1,
      "rank": 0.08,
      "text": "wide ranging air quality consequences",
      "timestamps": [{ "start": 235388, "end": 238694 }]
    },
    {
      "count": 1,
      "rank": 0.07,
      "text": "more wildfires",
      "timestamps": [{ "start": 230972, "end": 232354 }]
    },
    {
      "count": 1,
      "rank": 0.07,
      "text": "air pollution",
      "timestamps": [{ "start": 156004, "end": 156910 }]
    },
    {
      "count": 3,
      "rank": 0.07,
      "text": "weather systems",
      "timestamps": [
        { "start": 47344, "end": 47958 },
        { "start": 205268, "end": 205818 },
        { "start": 211588, "end": 213434 }
      ]
    },
    {
      "count": 2,
      "rank": 0.06,
      "text": "high levels",
      "timestamps": [
        { "start": 121128, "end": 121646 },
        { "start": 155412, "end": 155866 }
      ]
    },
    {
      "count": 1,
      "rank": 0.06,
      "text": "health conditions",
      "timestamps": [{ "start": 152138, "end": 152666 }]
    },
    {
      "count": 2,
      "rank": 0.06,
      "text": "Peter de Carlo",
      "timestamps": [
        { "start": 18948, "end": 19930 },
        { "start": 268298, "end": 269194 }
      ]
    },
    {
      "count": 1,
      "rank": 0.06,
      "text": "New York City",
      "timestamps": [{ "start": 125768, "end": 126274 }]
    },
    {
      "count": 1,
      "rank": 0.05,
      "text": "respiratory conditions",
      "timestamps": [{ "start": 152964, "end": 153786 }]
    },
    {
      "count": 3,
      "rank": 0.05,
      "text": "New York",
      "timestamps": [
        { "start": 125768, "end": 126034 },
        { "start": 171448, "end": 171938 },
        { "start": 176008, "end": 176322 }
      ]
    },
    {
      "count": 3,
      "rank": 0.05,
      "text": "climate change",
      "timestamps": [
        { "start": 229548, "end": 230230 },
        { "start": 244576, "end": 245162 },
        { "start": 263348, "end": 263950 }
      ]
    },
    {
      "count": 1,
      "rank": 0.05,
      "text": "Johns Hopkins University Varsity",
      "timestamps": [{ "start": 23972, "end": 25490 }]
    },
    {
      "count": 1,
      "rank": 0.05,
      "text": "heart conditions",
      "timestamps": [{ "start": 153988, "end": 154506 }]
    },
    {
      "count": 1,
      "rank": 0.05,
      "text": "air quality warnings",
      "timestamps": [{ "start": 12308, "end": 13434 }]
    }
  ]
}

audio_start_from · integer | null

The point in time, in milliseconds, in the file at which the transcription was started

audio_end_at · integer | null

The point in time, in milliseconds, in the file at which the transcription was terminated

word_boost · string[]

The list of custom vocabulary to boost transcription probability for

boost_param · string | null

The word boost parameter value

filter_profanity · boolean | null

Whether Profanity Filtering is enabled, either true or false

redact_pii_audio · boolean | null

Whether a redacted version of the audio file was generated, either true or false. See PII redaction for more information.

redact_pii_audio_quality · enum<string> | null

The audio quality of the PII-redacted audio file, if redact_pii_audio is enabled. See PII redaction for more information.

Controls the filetype of the audio created by redact_pii_audio. Currently supports mp3 (default) and wav. See PII redaction for more details.

Available options:

mp3,

wav

Example:

"mp3"

redact_pii_policies · enum<string>[] | null

The list of PII Redaction policies that were enabled, if PII Redaction is enabled. See PII redaction for more information.

Show child attributes

redact_pii_sub · enum<string>

The replacement logic for detected PII, can be "entity_type" or "hash". See PII redaction for more details.

Available options:

entity_name,

hash

speaker_labels · boolean | null

Whether Speaker diarization is enabled, can be true or false

speakers_expected · integer | null

Tell the speaker label model how many speakers it should attempt to identify, up to 10. See Speaker diarization for more details.

content_safety · boolean | null

Whether Content Moderation is enabled, can be true or false

content_safety_labels · object | null

An array of results for the Content Moderation model, if it is enabled. See Content moderation for more information.

Show child attributes

Example:

{
  "status": "success",
  "results": [
    {
      "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US. Skylines from Maine to Maryland to Minnesota are gray and smoggy. And in some places, the air quality warnings include the warning to stay inside. We wanted to better understand what's happening here and why, so we called Peter de Carlo, an associate professor in the Department of Environmental Health and Engineering at Johns Hopkins University Varsity. Good morning, professor. Good morning.",
      "labels": [
        {
          "label": "disasters",
          "confidence": 0.8142836093902588,
          "severity": 0.4093044400215149
        }
      ],
      "sentences_idx_start": 0,
      "sentences_idx_end": 5,
      "timestamp": { "start": 250, "end": 28840 }
    }
  ],
  "summary": {
    "disasters": 0.9940800441842205,
    "health_issues": 0.9216489289040967
  },
  "severity_score_summary": {
    "disasters": {
      "low": 0.5733263024656846,
      "medium": 0.42667369753431533,
      "high": 0
    },
    "health_issues": {
      "low": 0.22863814977924785,
      "medium": 0.45014154926938227,
      "high": 0.32122030095136983
    }
  }
}

iab_categories · boolean | null

Whether Topic Detection is enabled, can be true or false

iab_categories_result · object | null

The result of the Topic Detection model, if it is enabled. See Topic Detection for more information.

Show child attributes

Example:

{
  "status": "success",
  "results": [
    {
      "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US. Skylines from Maine to Maryland to Minnesota are gray and smoggy. And in some places, the air quality warnings include the warning to stay inside. We wanted to better understand what's happening here and why, so we called Peter de Carlo, an associate professor in the Department of Environmental Health and Engineering at Johns Hopkins University Varsity. Good morning, professor. Good morning.",
      "labels": [
        {
          "relevance": 0.988274097442627,
          "label": "Home&Garden>IndoorEnvironmentalQuality"
        },
        {
          "relevance": 0.5821335911750793,
          "label": "NewsAndPolitics>Weather"
        },
        {
          "relevance": 0.0042327106930315495,
          "label": "MedicalHealth>DiseasesAndConditions>LungAndRespiratoryHealth"
        },
        {
          "relevance": 0.0033971222583204508,
          "label": "NewsAndPolitics>Disasters"
        },
        {
          "relevance": 0.002469958271831274,
          "label": "BusinessAndFinance>Business>GreenSolutions"
        },
        {
          "relevance": 0.0014376690378412604,
          "label": "MedicalHealth>DiseasesAndConditions>Cancer"
        },
        {
          "relevance": 0.0014294233405962586,
          "label": "Science>Environment"
        },
        {
          "relevance": 0.001234519761055708,
          "label": "Travel>TravelLocations>PolarTravel"
        },
        {
          "relevance": 0.0010231725173071027,
          "label": "MedicalHealth>DiseasesAndConditions>ColdAndFlu"
        },
        {
          "relevance": 0.0007445293595083058,
          "label": "BusinessAndFinance>Industries>PowerAndEnergyIndustry"
        }
      ],
      "timestamp": { "start": 250, "end": 28840 }
    }
  ],
  "summary": {
    "NewsAndPolitics>Weather": 1,
    "Home&Garden>IndoorEnvironmentalQuality": 0.9043831825256348,
    "Science>Environment": 0.16117265820503235,
    "BusinessAndFinance>Industries>EnvironmentalServicesIndustry": 0.14393523335456848,
    "MedicalHealth>DiseasesAndConditions>LungAndRespiratoryHealth": 0.11401086300611496,
    "BusinessAndFinance>Business>GreenSolutions": 0.06348437070846558,
    "NewsAndPolitics>Disasters": 0.05041387677192688,
    "Travel>TravelLocations>PolarTravel": 0.01308488193899393,
    "HealthyLiving": 0.008222488686442375,
    "MedicalHealth>DiseasesAndConditions>ColdAndFlu": 0.0022315620444715023,
    "MedicalHealth>DiseasesAndConditions>HeartAndCardiovascularDiseases": 0.00213034451007843,
    "HealthyLiving>Wellness>SmokingCessation": 0.001540527562610805,
    "MedicalHealth>DiseasesAndConditions>Injuries": 0.0013950627762824297,
    "BusinessAndFinance>Industries>PowerAndEnergyIndustry": 0.0012570273829624057,
    "MedicalHealth>DiseasesAndConditions>Cancer": 0.001097781932912767,
    "MedicalHealth>DiseasesAndConditions>Allergies": 0.0010148967849090695,
    "MedicalHealth>DiseasesAndConditions>MentalHealth": 0.000717321818228811,
    "Style&Fashion>PersonalCare>DeodorantAndAntiperspirant": 0.0006022014422342181,
    "Technology&Computing>Computing>ComputerNetworking": 0.0005461975233629346,
    "MedicalHealth>DiseasesAndConditions>Injuries>FirstAid": 0.0004885646631009877
  }
}

custom_spelling · object[] | null

Customize how words are spelled and formatted using to and from values

Show child attributes

auto_chapters · boolean | null

Whether Auto Chapters is enabled, can be true or false

chapters · object[] | null

An array of temporally sequential chapters for the audio file

Show child attributes

summary_type · string | null

The type of summary generated, if Summarization is enabled

summary_model · string | null

The Summarization model used to generate the summary, if Summarization is enabled

summary · string | null

The generated summary of the media file, if Summarization is enabled

custom_topics · boolean | null

Whether custom topics is enabled, either true or false

topics · string[]

The list of custom topics provided if custom topics is enabled

sentiment_analysis · boolean | null

Whether Sentiment Analysis is enabled, can be true or false

sentiment_analysis_results · object[] | null

An array of results for the Sentiment Analysis model, if it is enabled. See Sentiment Analysis for more information.

Show child attributes

entity_detection · boolean | null

Whether Entity Detection is enabled, can be true or false

entities · object[] | null

An array of results for the Entity Detection model, if it is enabled. See Entity detection for more information.

Show child attributes

speech_threshold · number | null

Defaults to null. Reject audio files that contain less than this fraction of speech. Valid values are in the range [0, 1] inclusive.

Required range: 0 <= x <= 1

throttled · boolean | null

True while a request is throttled and false when a request is no longer throttled

error · string

Error message of why the transcript failed