Transcribing an audio file/recording

    The simplest way to use the API is to submit the URL to a publicly available audio file. The API will download the audio file, transcribe it, and return the transcription to you when it's complete.

    Need to upload files instead? Check out the upload endpoint.

    Submit an audio file for transcription

    First, you'll need to submit your audio URL to the API for processing. The URL must point to an audio file, and must be publicly accessible. Any file format is fine. The request to do that looks like this:

    You'll get a response like this:

    {
        # keep track of the id for later
        "id": "5551722-f677-48a6-9287-39c0aafd9ac1",
        # note that the status is currently "queued"
        "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
    }

    The important things to note are that the id is "5551722-f677-48a6-9287-39c0aafd9ac1" and the status is "queued" (when you run this API command, your id will be different!).

    Check the status of the transcription

    Now that the audio file has been submitted for transcription, we can make requests to GET the status of the transcription, and eventually the result of the transcription.

    Don't want to poll? Check out the webhooks guide.

    You'll get a response like this:

    {
        # keep track of the id for later
        "id": "ozfv3zim7-9725-4b54-9b71-f527bc21e5ab",
        # note that the status is now "processing"
        "status": "processing",        
        "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
    }

    The status will go from "queued" to "processing" to "completed". If there's an error transcribing your file, the status will go to "error" and there will be an "error" key in the response JSON which will contain more information.

    Get the final transcription result

    Once the status is "completed", you'll see a full JSON response with your transcription text, like this:

    {
        "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."
            }
        ]
    }