Documentation

Changelog Blog Sign in Create your account

Reference

Transcript

This is an object representing a transcription. You can create them, retrieve them to see their status and results, and delete them.

The Transcript Object

Attribute	Description	Required
id string	The unique identifier of your transcription	Yes
status string	The status of your transcription. `queued`, `processing`, `completed`, or `error`	No
language_code string	The language of your audio file. Possible values are found in Supported Languages. The default value is `en_us`.	No
audio_url string	The URL of your media file to transcribe	No
text string	The text transcription of your media file	No
words array	A list of all the individual words transcribed	No
utterances array	When `dual_channel` or `speaker_labels` is enabled, a list of turn-by-turn utterances	No
confidence float	The confidence our model has in the transcribed text, between `0.0` and `1.0`	No
audio_duration float	The duration of your media file, in seconds	No
punctuate boolean	Enable Automatic Punctuation, can be `true` or `false`	No
format_text boolean	Enable Text Formatting, can be `true` or `false`	No
dual_channel boolean	Enable Dual Channel transcription, can be `true` or `false`	No
webhook_url string	The URL we should send webhooks to when your transcript is complete	No
webhook_status_code string	The status code we received from your server when delivering your webhook	No
auto_highlights_result array	The list of results when enabling Automatic Transcript Highlights	No
audio_start_from integer	The point in time, in milliseconds, to begin transcription from in your media file	No
audio_end_at integer	The point in time, in milliseconds, to stop transcribing in your media file	No
word_boost array	A list of custom vocabulary to boost accuracy for	No
boost_param string	The weight to apply to words/phrases in the `word_boost` array; can be `"low"`, `"default"`, or `"high"`	No
filter_profanity boolean	Filter profanity from the transcribed text, can be `true` or `false`	No
redact_pii boolean	Redact PII from the transcribed text, can be `true` or `false`	No
redact_pii_audio boolean	Generate a copy of the original media file with spoken PII "beeped" out, can be `true` or `false`	No
redact_pii_policies array	The list of PII Redaction policies to enable	No
redact_pii_sub string	The replacement logic for detected PII, can be `"entity_type"` or `"hash"`	No
speaker_labels boolean	Enable Speaker Diarization, can be `true` or `false`	No
content_safety boolean	Enable Content Safety Detection, can be `true` or `false`	No
iab_categories boolean	Enable Topic Detection, can be `true` or `false`	No
content_safety_labels array	The list of results when `content_safety` is `true`	No
iab_categories_result array	The list of results when `iab_categories` is `true`	No
custom_spelling array	Customize how words are spelled and formatted using `to` and `from` values	No
disfluencies boolean	Transcribe Filler Words, like "umm", in your media file; can be `true` or `false`	No
sentiment_analysis boolean	Enable Sentiment Analysis, can be `true` or `false`	No
auto_chapters boolean	Enable Auto Chapters, can be `true` or `false`	No
chapters array	When Auto Chapters is enabled, the list of Auto Chapters results	No
sentiment_analysis_results array	When Sentiment Analysis is enabled, the list of Sentiment Analysis results	No
entity_detection boolean	Enable Entity Detection, can be `true` or `false`	No
entities array	When Entity Detection is enabled, the list of detected Entities	No

Create a Transcript

Create a transcription.

Parameters

Attribute	Description
audio_url string required	The URL of your media file to transcribe
language_code string	The language of your audio file. Possible values are found in Supported Languages. The default value is `en_us`.
punctuate boolean	Enable Automatic Punctuation, can be `true` or `false`
format_text boolean	Enable Text Formatting, can be `true` or `false`
dual_channel boolean	Enable Dual Channel transcription, can be `true` or `false`
webhook_url string	The URL we should send webhooks to when your transcript is complete
audio_start_from integer	The point in time, in milliseconds, to begin transcription from in your media file
audio_end_at integer	The point in time, in milliseconds, to stop transcribing in your media file
word_boost array	A list of custom vocabulary to boost accuracy for
boost_param string	The weight to apply to words/phrases in the `word_boost` array; can be `"low"`, `"default"`, or `"high"`
filter_profanity boolean	Filter profanity from the transcribed text, can be `true` or `false`
redact_pii boolean	Redact PII from the transcribed text, can be `true` or `false`
redact_pii_audio boolean	Generate a copy of the original media file with spoken PII "beeped" out, can be `true` or `false`
redact_pii_policies array	The list of PII Redaction policies to enable
redact_pii_sub string	The replacement logic for detected PII, can be `"entity_type"` or `"hash"`
speaker_labels boolean	Enable Speaker Diarization, can be `true` or `false`
content_safety boolean	Enable Content Safety Detection, can be `true` or `false`
iab_categories boolean	Enable Topic Detection, can be `true` or `false`
custom_spelling array	Customize how words are spelled and formatted using `to` and `from` values
disfluencies boolean	Transcribe Filler Words, like "umm", in your media file; can be `true` or `false`
sentiment_analysis boolean	Enable Sentiment Analysis, can be `true` or `false`
auto_chapters boolean	Enable Auto Chapters, can be `true` or `false`
entity_detection boolean	Enable Entity Detection, can be `true` or `false`

POST /v2/transcript

import requests
endpoint = "https://api.assemblyai.com/v2/transcript"
json = {
    "audio_url": "https://bit.ly/3yxKEIY"
}
headers = {
    "authorization": "YOUR-API-TOKEN",
    "content-type": "application/json"
}
response = requests.post(endpoint, json=json, headers=headers)
print(response.json())

API Response

{
   "id":"5zk8mzqo3-1d32-4a14-9e6a-da9412ca0579",
   "language_model":"assemblyai_default",
   "acoustic_model":"assemblyai_default",
   "language_code":"en_us",
   "status":"completed",
   "audio_url":"https://bit.ly/3yxKEIY",
   "text":"Hi, Barbara...",
   "words":[
      {
         "text":"Hi,",
         "start":850,
         "end":900,
         "confidence":0.97422,
         "speaker":null
      },
      ...
   ]
   "utterances":null,
   "confidence":0.836845694444445,
   "audio_duration":25,
   "punctuate":true,
   "format_text":true,
   "dual_channel":false,
   "webhook_url":null,
   "webhook_status_code":null,
   "speed_boost":false,
   "auto_highlights_result":null,
   "auto_highlights":false,
   "audio_start_from":null,
   "audio_end_at":null,
   "word_boost":[...],
   "boost_param":null,
   "filter_profanity":false,
   "redact_pii":false,
   "redact_pii_audio":false,
   "redact_pii_audio_quality":null,
   "redact_pii_policies":null,
   "redact_pii_sub":null,
   "speaker_labels":false,
   "content_safety":false,
   "iab_categories":false,
   "content_safety_labels":{...},
   "iab_categories_result":{...},
   "custom_spelling": null,
   "disfluencies":false,
   "sentiment_analysis":false,
   "auto_chapters":false,
   "chapters":null,
   "sentiment_analysis_results":null,
   "entity_detection":false,
   "entities":null
}

Get a Transcript

Get the detailed information of a specific transcript by id.

GET /v2/transcript/:id

1 
2 
3

curl \
  --url https://api.assemblyai.com/v2/transcript/:id \
  --header 'authorization: YOUR-API-TOKEN'

API Response

{
   "id":"5zk8mzqo3-1d32-4a14-9e6a-da9412ca0579",
   "language_model":"assemblyai_default",
   "acoustic_model":"assemblyai_default",
   "language_code":"en_us",
   "status":"completed",
   "audio_url":"https://cdn.assemblyai.com/upload/feb33bc1-3e55-4af6-be91-9670ce209083",
   "text":"Hi, Barbara...",
   "words":[
      {
         "text":"Hi,",
         "start":850,
         "end":900,
         "confidence":0.97422,
         "speaker":null
      },
      ...
   ]
   "utterances":null,
   "confidence":0.836845694444445,
   "audio_duration":25,
   "punctuate":true,
   "format_text":true,
   "dual_channel":false,
   "webhook_url":null,
   "webhook_status_code":null,
   "speed_boost":false,
   "auto_highlights_result":null,
   "auto_highlights":false,
   "audio_start_from":null,
   "audio_end_at":null,
   "word_boost":[...],
   "boost_param":null,
   "filter_profanity":false,
   "redact_pii":false,
   "redact_pii_audio":false,
   "redact_pii_audio_quality":null,
   "redact_pii_policies":null,
   "redact_pii_sub":null,
   "speaker_labels":false,
   "content_safety":false,
   "iab_categories":false,
   "content_safety_labels":{...},
   "iab_categories_result":{...},
   "custom_spelling": null,
   "disfluencies":false,
   "sentiment_analysis":false,
   "auto_chapters":false,
   "chapters":null,
   "sentiment_analysis_results":null,
   "entity_detection":false,
   "entities":null
}

Get all Sentences of a Transcript

Query for only the sentences of a transcript by id.

GET /v2/transcript/:id/sentences

1 
2 
3

curl \
  --url https://api.assemblyai.com/v2/transcript/:id/sentences \
  --header 'authorization: YOUR-API-TOKEN' \

Response

{
   "sentences":[
      {
         "text":"I'm up here on the International Space Station.",
         "start":770,
         "end":10710,
         "confidence":0.97,
         "words":[
            {"text": "I'm.", "start": 100, "end": 1000, "confidence": 0.99},
            ...
         ]
      },
      {
         "text":"Are you in a bed?",
         "start":39070,
         "end":50250,
         "confidence":0.99,
         "words":[
            {"text": "Are", "start": 45, "end": 290, "confidence": 0.99},
            ...
         ]
      },
        ...
    ],
    "id": "3otc28umy-25ae-4446-b133-70e244be5208",
    "confidence": 0.951530612244907,
    "audio_duration": 521.352
}

Get all Paragraphs of a Transcript

Query for only the paragraphs of a transcript by id.

GET /v2/transcript/:id/paragraphs

1 
2 
3

curl \
  --url https://api.assemblyai.com/v2/transcript/:id/paragraphs \
  --header 'authorization: YOUR-API-TOKEN' \

Response

{
   "paragraphs":[
      {
         "text":"Hello. I'm Sunny Williams. I'm up here on the International Space Station. So this is No two. This is a really cool module.",
         "start":770,
         "end":10710,
         "confidence":0.97,
         "words":[
            {"text": "Hello.", "start": 100, "end": 1000, "confidence": 0.99},
            ...
         ]
      },
      {
         "text":"Are you in a bed? Not really, because it doesn't matter. You don't really have the sensation of lying down. You just sit in your sleeping bag. So Here's one sleep station right here.",
         "start":39070,
         "end":50250,
         "confidence":0.99,
         "words":[
            {"text": "Are.", "start": 45, "end": 290, "confidence": 0.99},
            ...
         ]
      },
      ...
    ],
    "id": "3otc28umy-25ae-4446-b133-70e244be5208",
    "confidence": 0.951530612244907,
    "audio_duration": 521.352
}

Get All Transcripts

List all your transcripts.

Parameters

All of the below parameters are optional.

Attribute	Description
limit integer	Max results to return in a single response, between `1` and `200` inclusive
status string	Filter by transcript status, `"processing"`, `"queued"`, `"completed"`, or `"error"`
created_on string	Only return transcripts created on this date; format: `"YYYY-MM-DD"`
before_id string	Return transcripts that were created before this id
after_id string	Return transcripts that were created after this id
throttled_only boolean	Only return throttled transcripts, overrides status filter

GET /v2/transcript

1 
2 
3

curl \
  --url https://api.assemblyai.com/v2/transcript \
  --header 'authorization: YOUR-API-TOKEN' \

Response

{
  "page_details": {
    "limit": 100,
    "result_count": 0,
    "current_url": "https://api.assemblyai.com/v2/transcript",
    "prev_url": null,
    "next_url": null
  },
  "transcripts": [
    {
      "id": "5551722-f677-48a6-9287-39c0aafd9ac1",
      "status": "queued",
      "acoustic_model": "assemblyai_default",
      "audio_duration": null,
      "audio_url": "https://bit.ly/3yxKEIY",
      "confidence": null,
      "dual_channel": null,
      "format_text": true,
      "language_model": "assemblyai_default",
      "punctuate": true,
      "text": null,
      "utterances": null,
      "webhook_status_code": null,
      "webhook_url": null,
      "words": null,
    }
  ]
}

Delete a Transcript

Permanently delete a transcript by id. The record of the transcript will exist and remain queryable, however, all fields containing sensitive data (like text transcriptions) will be permanently deleted.

Upload

Uploads can be used to upload media files directly to the AssemblyAI API for transcription.

The Upload Object

Attribute	Description
upload_url string	A URL that points to your audio file, accessible only by AssemblyAI's servers

Creating an Upload

Upload a file to our servers for transcription. Learn more at Uploading Local Files for Transcription

Headers

Attribute	Value
Transfer-Encoding	chunked

Body

The contents of your media file.

POST /v2/upload

import requests
filename = "/path/to/foo.wav"
def read_file(filename, chunk_size=5242880):
    with open(filename, 'rb') as _file:
        while True:
            data = _file.read(chunk_size)
            if not data:
                break
            yield data

headers = {'authorization': "YOUR-API-TOKEN"} response = requests.post('https://api.assemblyai.com/v2/upload',
                        headers=headers,
                        data=read_file(filename))

print(response.json())

API Response

{"upload_url": "https://cdn.assemblyai.com/upload/ccbbbfaf-f319-4455-9556-272d48faaf7f"}

Stream

If you're working with short bursts of audio, less than 15 seconds, you can send the audio data directly to the /v2/stream endpoint which will return a transcript to you within a few hundred milliseconds, directly in the request-response loop.

Audio Requirements

The audio data you send to this endpoint has to comply with a strict format. This is because we don't do any transcoding to your data, we send it directly to the model for transcription. You can send the content of a .wav file to this endpoint, or raw data read directly from a microphone. Either way, you must record your audio in the following format to use this endpoint:

16-bit Signed Integer PCM encoding (ie, a .wav file)
8khz sampling rate
128kbps bitrate
16-bit Precision
Single channel
Headless (ie, strip any headers from wav files)
15 seconds or less of audio per request

POST Params

When making a POST request to this endpoint, you should include the following parameters.

Param	Example	Info	Required
`audio_data`	`UklGRtjIAABXQVZFZ…`	Raw audio data, base64 encoded. This can be the raw data recorded directly from a microphone or read from a wav file.	Yes
`format_text`	`true`	This is set to `false` by default; however, a developer can add auto formatting of text by setting it to `true`.	No
`punctuate`	`true`	This is set to `false` by default; however, a developer can add auto punctuation by setting it to `true`.	No

base64 encoding:

base64 encoding is a simple way to encode your raw audio data so that it can be included as a JSON parameter in your POST request. Most programming languages have very simple built-in functions for encoding binary data to base64.

POST Response

Depending on how much audio data you send, the API will respond within 100-750 milliseconds. The following keys will be in the JSON response.

Param	Example	Info
`id`	`5551722-f677-48a6-9287-39c0aafd9ac1`	The unique id of your transcription.
`status`	`completed`	The status of your transcription.
`confidence`	`0.956`	The confidence score of the entire transcription, between 0 and 1.
`text`	`You know Demons on TV like...`	The complete transcription for your audio.
`words`	`[{"confidence": 1.0, "end": 440, "start": 0, "text": "You"}, ...]`	An array of objects, with the information for each word in the transcription text. Will include the start/end time (in milliseconds) of the word and the confidence score of the word.
`created`	`2019-06-27 22:26:47.048512`	The timestamp for your request

POST	/v2/transcript
GET	/v2/transcript
GET	/v2/transcript/:id
GET	/v2/transcript/:id/sentences
GET	/v2/transcript/:id/paragraphs
DELETE	/v2/transcript/:id