Transcribe — From audio file asynchronously
POST/transcribe-async
Generate a transcript from an audio file. Only audio/* mime types are supported. Common audio formats are accepted, including MP3 (MPEG), M4A/MP4 (AAC), WAV, FLAC, OGG, and WebM. The maximum duration is 60 minutes.
Request
Responses
- 200
Request received and processing started.
Operation spec
{
"method": "post",
"path": "/transcribe-async",
"operationId": "transcribe-async",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "The object containing all the information needed along with the audio file to transcribe.",
"properties": {
"speech_locales": {
"description": "An array of up to two locales for transcription. The speech-to-text engine automatically detects the spoken locale from this list.\n\nSupport for Haitian Creole (`HAITIAN_HT`) is experimental and access is limited — please reach out to get access. Haitian Creole cannot be combined with any other language: when transcribing Haitian Creole, `speech_locales` must contain exactly one entry.",
"type": "array",
"items": {
"type": "string",
"enum": [
"ENGLISH_US",
"ENGLISH_UK",
"SPANISH_ES",
"SPANISH_MX",
"FRENCH_FR",
"ARABIC_EG",
"ARABIC_LB",
"ARABIC_MA",
"ARABIC_SA",
"ARMENIAN_AM",
"BENGALI_IN",
"CANTONESE_CN",
"CROATIAN_HR",
"FILIPINO_PH",
"GERMAN_DE",
"GREEK_GR",
"GUJARATI_IN",
"HEBREW_IL",
"HINDI_IN",
"ITALIAN_IT",
"JAPANESE_JP",
"KHMER_KH",
"KOREAN_KR",
"MANDARIN_CN",
"PERSIAN_IR",
"POLISH_PL",
"PORTUGUESE_PT",
"PUNJABI_IN",
"RUSSIAN_RU",
"SERBIAN_RS",
"TAMIL_IN",
"TELUGU_IN",
"THAI_TH",
"URDU_IN",
"VIETNAMESE_VN",
"HAITIAN_HT"
],
"example": "ENGLISH_US",
"title": "speech_locale"
},
"minItems": 1,
"maxItems": 2,
"uniqueItems": true,
"title": "speech_locale_array"
},
"file_url": {
"type": "string",
"description": "The URL of the audio file to download & transcribe."
},
"split_by_sentence": {
"type": "boolean",
"default": false,
"description": "Indicates whether to segment transcription results at sentence boundaries. Default is false, meaning that a single transcript item may encompass multiple sentences, provided they are not delineated by pauses (silence) in the audio."
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
}
},
"required": [
"speech_locales",
"file_url"
],
"title": "transcribe_async_request"
}
}
}
},
"responses": {
"200": {
"description": "Request received and processing started.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "ONGOING",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
]
},
{
"title": "FAILED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"properties": {
"error_code": {
"type": "integer",
"example": 422
},
"error_message": {
"type": "string",
"example": "We can't generate the note when the transcript is too short."
}
},
"required": [
"error_code"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
]
},
{
"title": "SUCCEEDED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"description": "The generated transcript.",
"properties": {
"transcript": {
"type": "array",
"description": "Transcript items from the audio file.",
"items": {
"type": "object",
"description": "A portion of the transcribed consultation.",
"properties": {
"text": {
"type": "string",
"description": "The transcribed text.",
"example": "Also, I’m allergic to peanuts."
},
"speaker_type": {
"type": "string",
"enum": [
"DOCTOR",
"PATIENT",
"UNSPECIFIED"
],
"description": "Who said the text in this transcript item.",
"example": "DOCTOR",
"title": "speaker"
},
"locale": {
"description": "Locale for this transcript item, detected by the speech-to-text engine from the list of locales in the input.",
"type": "string",
"enum": [
"ENGLISH_US",
"ENGLISH_UK",
"SPANISH_ES",
"SPANISH_MX",
"FRENCH_FR",
"ARABIC_EG",
"ARABIC_LB",
"ARABIC_MA",
"ARABIC_SA",
"ARMENIAN_AM",
"BENGALI_IN",
"CANTONESE_CN",
"CROATIAN_HR",
"FILIPINO_PH",
"GERMAN_DE",
"GREEK_GR",
"GUJARATI_IN",
"HEBREW_IL",
"HINDI_IN",
"ITALIAN_IT",
"JAPANESE_JP",
"KHMER_KH",
"KOREAN_KR",
"MANDARIN_CN",
"PERSIAN_IR",
"POLISH_PL",
"PORTUGUESE_PT",
"PUNJABI_IN",
"RUSSIAN_RU",
"SERBIAN_RS",
"TAMIL_IN",
"TELUGU_IN",
"THAI_TH",
"URDU_IN",
"VIETNAMESE_VN",
"HAITIAN_HT"
],
"example": "ENGLISH_US",
"title": "speech_locale"
},
"start_offset_ms": {
"type": "integer",
"description": "Start time of this transcription item as the offset, in milliseconds, from the start of the audio file.",
"example": 65100
},
"end_offset_ms": {
"type": "integer",
"description": "End time of this transcription item as the offset, in milliseconds, from the start of the audio file. Equals the `start_time_ms` plus the duration of the related transcribed audio portion.",
"example": 69300
}
},
"required": [
"text",
"locale",
"start_offset_ms",
"end_offset_ms"
],
"title": "transcript_item"
},
"title": "transcript"
}
},
"required": [
"transcript"
],
"title": "async_transcription_succeeded_payload"
}
},
"required": [
"id",
"status"
]
}
],
"discriminator": {
"propertyName": "status",
"mapping": {
"ONGOING": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
],
"title": "async_request_ongoing"
},
"FAILED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"properties": {
"error_code": {
"type": "integer",
"example": 422
},
"error_message": {
"type": "string",
"example": "We can't generate the note when the transcript is too short."
}
},
"required": [
"error_code"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
],
"title": "async_request_failed"
},
"SUCCEEDED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"description": "The generated transcript.",
"properties": {
"transcript": {
"type": "array",
"description": "Transcript items from the audio file.",
"items": {
"type": "object",
"description": "A portion of the transcribed consultation.",
"properties": {
"text": {
"type": "string",
"description": "The transcribed text.",
"example": "Also, I’m allergic to peanuts."
},
"speaker_type": {
"type": "string",
"enum": [
"DOCTOR",
"PATIENT",
"UNSPECIFIED"
],
"description": "Who said the text in this transcript item.",
"example": "DOCTOR",
"title": "speaker"
},
"locale": {
"description": "Locale for this transcript item, detected by the speech-to-text engine from the list of locales in the input.",
"type": "string",
"enum": [
"ENGLISH_US",
"ENGLISH_UK",
"SPANISH_ES",
"SPANISH_MX",
"FRENCH_FR",
"ARABIC_EG",
"ARABIC_LB",
"ARABIC_MA",
"ARABIC_SA",
"ARMENIAN_AM",
"BENGALI_IN",
"CANTONESE_CN",
"CROATIAN_HR",
"FILIPINO_PH",
"GERMAN_DE",
"GREEK_GR",
"GUJARATI_IN",
"HEBREW_IL",
"HINDI_IN",
"ITALIAN_IT",
"JAPANESE_JP",
"KHMER_KH",
"KOREAN_KR",
"MANDARIN_CN",
"PERSIAN_IR",
"POLISH_PL",
"PORTUGUESE_PT",
"PUNJABI_IN",
"RUSSIAN_RU",
"SERBIAN_RS",
"TAMIL_IN",
"TELUGU_IN",
"THAI_TH",
"URDU_IN",
"VIETNAMESE_VN",
"HAITIAN_HT"
],
"example": "ENGLISH_US",
"title": "speech_locale"
},
"start_offset_ms": {
"type": "integer",
"description": "Start time of this transcription item as the offset, in milliseconds, from the start of the audio file.",
"example": 65100
},
"end_offset_ms": {
"type": "integer",
"description": "End time of this transcription item as the offset, in milliseconds, from the start of the audio file. Equals the `start_time_ms` plus the duration of the related transcribed audio portion.",
"example": 69300
}
},
"required": [
"text",
"locale",
"start_offset_ms",
"end_offset_ms"
],
"title": "transcript_item"
},
"title": "transcript"
}
},
"required": [
"transcript"
],
"title": "async_transcription_succeeded_payload"
}
},
"required": [
"id",
"status"
],
"title": "async_transcription_succeeded"
}
}
},
"title": "async_transcription"
}
}
}
}
}
}