Quickstart

This Quickstart should take you 2 minutes!

Submit an audio file for transcription

Here's a quick example that shows how to transcribe an audio file that's accessible via a URL (for example in an S3 bucket, on your server, via the Twilio API, etc).

Need to upload files to the API directly? Jump to the tutorial on uploading files to the API.

You'll get a response like this:

{
    # keep track of the "id" to query for the status of your transcript later!
    "id": "5551722-f677-48a6-9287-39c0aafd9ac1",
    # notice here that the status shows as "queued" for now
    "status": "queued",
    "acoustic_model": "assemblyai_default",
    "audio_duration": null,
    "audio_url": "https://s3-us-west-2.amazonaws.com/blog.assemblyai.com/audio/8-7-2018-post/7510.mp3",
    "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
}

You'll see the id of your transcript is "5551722-f677-48a6-9287-39c0aafd9ac1" and the status is "queued" (when you make this API call, your id will be different!).

Get the transcription result

The status goes from "queued" to "processing" to "completed" as the transcript processes. You can poll with GET requests (below) to check the status of your transcription.

You'll have to make repeated GET requests until the status is "completed" or "error" if the audio file failed to process. You'll see a full JSON response like the one below once the status is "completed". By default, the transcription text will have punctuation and casing automatically added, but you can disable that feature.

{
    "acoustic_model": "assemblyai_default",
    "audio_duration": 12.0960090702948,
    "audio_url": "https://s3-us-west-2.amazonaws.com/blog.assemblyai.com/audio/8-7-2018-post/7510.mp3",
    "confidence": 0.956,
    "dual_channel": null,
    "format_text": true,
    "id": "5551722-f677-48a6-9287-39c0aafd9ac1",
    "language_model": "assemblyai_default",
    "punctuate": true,
    "status": "completed",
    "text": "You know Demons on TV like that and and for people to expose themselves to being rejected on TV or humiliated by fear factor or.",
    "utterances": null,
    "webhook_status_code": null,
    "webhook_url": null,
    "words": [
        {
            "confidence": 1.0,
            "end": 440,
            "start": 0,
            "text": "You"
        },
        ...
        {
            "confidence": 0.96,
            "end": 10060,
            "start": 9600,
            "text": "factor"
        },
        {
            "confidence": 0.97,
            "end": 10260,
            "start": 10080,
            "text": "or."
        }
    ]
}

Next steps

Next up, we recommend reading about: