Topic Detection | Deepgram's Docs

Try this feature out in our API Playground.

topics boolean Default: false

English (all available regions)

Topic Detection accepts an input text, divides it into a list of segments comprised of sections of the text, and identifies key topics found within each segment.

JSON

 "results": {
    "topics": {
      "segments": [
        {
          "text": "Hi I'm calling to get a refund on my recent purchase. Sure I'd be happy to help you with that. What was the number for you order?",
          "start_word": 0,
          "end_word": 26,
          "topics": [
            { "topic": "Refund", "confidence_score": 0.91318 },
            { "topic": "Order Number", "confidence_score": 0.95342 }
          ]
        },
        {
          "text": "Ok thanks for that. It looks like you made this purchase online, is that correct? Yes I ordered this online on your website a few days ago.",
          "start_word": 45,
          "end_word": 72,
          "topics": [
            {
              "topic": "Online Transacation", "confidence_score": 0.741929
            }
          ]
        }
      ]
    }
  }

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

Enable Feature

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

topics=true

Basic Text Request

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

cURL

curl -vX POST \
 -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"text": "YOUR_TEXT_INPUT"}' \
 "https://api.deepgram.com/v1/read?topics=true&language=en"

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Basic URL Request

To analyze text from a hosted file, run the following curl command in a terminal or your favorite API client. (Try testing it out with the hosted file https://static.deepgram.com/examples/aura.txt)

Custom Topics Request

To tell the model to only return topics from your own custom list of topics, add custom_topic_mode=strict and custom_topic= followed by the list of topics. (Use the URL encoding%20 to represent a space between each word in the list.)

If you want to return your own custom list of topics in addition to Deegpram’s list of topics, set custom_topic_mode=extended and add your custom list.

cURL

curl -vX POST \
 -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"text": "YOUR_TEXT_INPUT"}' \
 "https://api.deepgram.com/v1/read?topics=true&language=en&custom_topic_mode=strict&custom_topic=refund&custom_topic=online_transaction&custom_topic=Order%20Number"

Read our Text Intelligence Getting Started guide, which will walk you through making a basic text request and a basic URL request with the Deepgram SDKs.

Query Parameters

Parameter	Value	Type	Description
`topics`	`true`	boolean	Enables Topic Detection
`language`	`en`	string	The language of your input text (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 text 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": {
    "request_id": "c313ae16-2c3b-4c51-87a6-920a8aa1d899",
    "created": "2023-11-28T01:44:27.083Z",
    "language": "en",
    "topics_info": {
      "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc",
      "input_tokens": 22,
      "output_tokens": 4
    }
  },
  "results": {
    "topics": {
      "segments": [
        {
          "text": "Hi I'm calling to get a refund on my recent purchase. Sure I'd be happy to help you with that. What was the number for you order?",
          "start_word": 0,
          "end_word": 26,
          "topics": [
            { "topic": "Refund", "confidence_score": 0.91318 },
            { "topic": "Order Number", "confidence_score": 0.95342 }
          ]
        },
        {
          "text": "Ok thanks for that. It looks like you made this purchase online, is that correct? Yes I ordered this online on your website a few days ago.",
          "start_word": 45,
          "end_word": 72,
          "topics": [{ "topic": "Online Transacation", "confidence_score": 0.741929 }]
        }
      ]
    }
  }
}

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 Error Responses

Unsupported Language

Status 400

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 error message below.

JSON

{
  "err_code":"INVALID_QUERY_PARAMETER",
  "err_msg":"Request specified unsupported language: <language_name>. Only English is supported.",
  "request_id":"XXXX"
}

Token Limit Exceeded

Status 400

If the request’s input length exceeded the 150k token rate limit per request, you will get the error message below.

JSON

{
  "err_code": "TOKEN_LIMIT_EXCEEDED",
  "err_msg": "Text input for <api_name> currently supports up to 150K tokens. Please revise your text input to fit within the defined token limit. For more information, please visit our API documentation.",
  "request_id": "XXXX"
}

Missing Query Parameter

Status 400

If the request sent contained only the feature parameter (topics) but not the language parameter, you will receive this error.

JSON

{
  "err_code":"INVALID_QUERY_PARAMETER",
  "err_msg":"Failed to deserialize query parameters: missing field `language`",
  "request_id":"XXX"
}