Topic Detection

Detects topics throughout a transcript.

topics boolean   Default: false

🛝

Try this feature out in our API Playground!

Deepgram’s Topic Detection feature identifies key topics within the transcript, returning a list of text segments and the topics found within each segment.

The list of topics that can be identified is not a fixed list; this TSLM powered feature is able to generate topics based on the context of the language content in the transcript. You may also choose to use the optional custom-topic parameter to provide a custom topic you want detected if present within your audio.

Enable Feature

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

topics=true

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?topics=true'

🚧

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Query Parameters

ParameterValueTypeDescription
topicstruebooleanEnables topic detection
languageenstringThe language of your input audio (Only English is supported at this time.)
custom_topicex: animalsstringOptional. A custom topic you want the model to detect within your input audio if present. Submit up to 100.
custom_topic_modeextended, strictstringOptional. Sets how the model will interpret strings submitted to the custom_topic param. When strict, the model will only return topics submitted using the custom_topic param. When extended, the model will return its own detected topics in addition to those submitted using the custom_topic param.

Analyze Response

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

{
  "metadata": {...},
  "results": {
    "channels": [
      {
        "alternatives": [...]
      }
    ],
    "topics": {
      "segments": [
        {
          "text": "Can I upgrade my phone?",
          "start_word": 13,
          "end_word": 17,
          "topics": [
            { "topic": "Phone upgrade", "confidence_score": 0.9661531 }
          ]
        }
      ]
    }
  }
}

The response object values for topics are:

  • segments: The list of segments of text identified by the model as containing notable topics.
  • topic: The name of the topic detected by the model.
  • confidence_score: a floating point from 0 to 1 representing the models confidence in this prediction.

API Warning Response

Warning

If you request Topic Detection with an unsupported language by specifying a language code such as topics=true&language=es or topics=true&detect_language=true where the detected language is unsupported, you will get the warning message below.

"warnings": [
  {
    "parameter": "topics",
    "type": "unsupported_language",
    "message": "Topics is only supported for English."
  }
]
Warning NameWarning Message
unsupported_languageFeature isn't supported with the specified or detected language.

Example Warning

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

{
 "metadata": {
...
       },
     "warnings": [
       {
         "parameter": "topic",
         "type": "unsupported_language",
         "message": "Topics is only supported for English."
       }
     ]
   },
 "results": {
       "channels": [
            {
                "alternatives": [...]
            }
        ], 

    }
}

Use Cases

Some examples of uses for Topic Detection include:

  • Customers who want to help their Quality Assurance team analyze conversations to identify trends and patterns based on discussed topics.
  • Customers who need to extract meaningful and actionable insights from conversations and audio data based on discussed topics.
  • Customers who want to enhance search capabilities by tagging conversations based on identified topics.