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.

    Making the Request

    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:

    curl --request POST \
      --url https://api.assemblyai.com/v2/transcript \
      --header 'authorization: YOUR-API-TOKEN' \
      --header 'content-type: application/json' \
      --data '{"audio_url": "https://s3-us-west-2.amazonaws.com/blog.assemblyai.com/audio/8-7-2018-post/7510.mp3"}'

    You'll get a response like this:

    {
        "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,
        "id": "5551722-f677-48a6-9287-39c0aafd9ac1",
        "language_model": "assemblyai_default",
        "punctuate": true,
        "status": "queued",
        "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!).

    Checking the Status

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

    Don't want to poll? Check out the webhooks guide.
    curl --request GET \
      --url https://api.assemblyai.com/v2/transcript/5551722-f677-48a6-9287-39c0aafd9ac1 \
      --header 'authorization: YOUR-API-TOKEN' 

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

    Getting the Result

    Once the status is "completed", you'll see a full JSON response 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."
            }
        ]
    }