Summarization

🛝

Try this feature out in our API Playground!

Deepgram’s Summarization feature summarizes the content of the submitted audio and returns a brief summary in the JSON response.

Enable Feature

To enable Summarization V2, use the following parameter in the query string when you call Deepgram’s /listen endpoint :

summarize=v2

To transcribe audio from a file on your computer, run the following curl command in a terminal or your favorite API client.

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?summarize=v2'

🚧

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Query Parameters

Analyze Response

When the file is finished processing, you’ll receive a JSON response that has the following basic structure:

{
  "metadata": {...},
  "results": {
        "channels": [
            {
                "alternatives": [...]
            }
        ],        
        "summary": { 
            "result":"success"
            "short": "Jake calls the Honda dealership and speaks with Josh about the new Honda Civic 2023. Jake schedules a test drive for the hybrid model on Friday and provides his contact information.Josh confirms the appointment and tells Jake to call if he has any further questions."
        }
  }
}

The summary object contains:

• result: Status of the request (success | failure).
• short: Short summary of the audio being summarized.

This summarization feature produces one summary across all channels so that the summary field ranks at the same place in the JSON response as the channels array.

🚧

The JSON response for Summarization V2 (summarize=v2) differs from the JSON response for Summarization V1 (summarize=true).

API Error and Warning Response

Error

If you request Summarization V2 with an unsupported language by specifying a language code such as summarize=v2&language=es, you will get an error message like the one below.

{
    "err_code": "Bad Request",
    "err_msg": "Summarization v2 not supported for non-English languages",
    "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Warning

If you request Summarization V2 with automatic language detection such as summarize=v2&detect_language=true, where the detected language is unsupported (Spanish, for example), you will get the response, including a transcript and a warning object.

"warnings": [
    {
      "parameter": "TEXT",
      "type": "unsupported_language",
      "message": "TEXT"
    }
]

Example Warning

Here is an example of the JSON structure of a request with warning object:

{
 "metadata": {
...
       },
       "warnings": [
           {
            "parameter": "summarize",
            "type": "unsupported_language",
            "message": "Summarization isn’t supported for the detected language."
           }
       ],
   },
 "results": {
       "channels": [
            {
                "alternatives": [...]
            }
        ], 
        "summary": 
          { 
            "result": "failure", 
            "short": "The summarization feature is currently only available in English. Please check out our API documentation for more details."
      }
    }
}

📘

Summarization - V1

This guide explains Deepgram's Summarization V2. The guide to Deepgram's deprecated summarization feature V1 can be found here.