Topic Detection | Deepgram's Docs

Try this feature out in our API Playground.

topics boolean Default: false

Pre-recorded Streaming:Nova English (all available regions)

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

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

Parameter	Value	Type	Description
`topics`	`true`	boolean	Enables topic detection
`language`	`en`	string	The language of your input audio (Only English is supported at this time.)
`custom_topic`	ex: `animals`	string	Optional. A custom topic you want the model to detect within your input audio if present. Submit up to 100.
`custom_topic_mode`	`extended`, `strict`	string	Optional. 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:

JSON

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

JSON

"warnings": [
  {
    "parameter": "topics",
    "type": "unsupported_language",
    "message": "Topics is only supported for English."
  }
]

Warning Name	Warning Message
`unsupported_language`	Feature 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.

JSON

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