Topic Detection

Topic Detection detects topics throughout the input text.

topics boolean   Default: false

English (all available regions)

Deepgram API Playground Try this feature out in our API Playground!

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
1 "results": {
2    "topics": {
3      "segments": [
4        {
5          "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?",
6          "start_word": 0,
7          "end_word": 26,
8          "topics": [
9            { "topic": "Refund", "confidence_score": 0.91318 },
10            { "topic": "Order Number", "confidence_score": 0.95342 }
11          ]
12        },
13        {
14          "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.",
15          "start_word": 45,
16          "end_word": 72,
17          "topics": [
18            {
19              "topic": "Online Transacation", "confidence_score": 0.741929
20            }
21          ]
22        }
23      ]
24    }
25  }

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_intent_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

ParameterValueTypeDescription
topicstruebooleanEnables Topic Detection
languageenstringThe language of your input text (Only English is supported at this time.)
custom_topicex: animalsstringOptional. A custom topic you want the model to detect within your input text 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:

JSON
1{
2  "metadata": {
3    "request_id": "c313ae16-2c3b-4c51-87a6-920a8aa1d899",
4    "created": "2023-11-28T01:44:27.083Z",
5    "language": "en",
6    "topics_info": {
7      "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc",
8      "input_tokens": 22,
9      "output_tokens": 4
10    }
11  },
12  "results": {
13    "topics": {
14      "segments": [
15        {
16          "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?",
17          "start_word": 0,
18          "end_word": 26,
19          "topics": [
20            { "topic": "Refund", "confidence_score": 0.91318 },
21            { "topic": "Order Number", "confidence_score": 0.95342 }
22          ]
23        },
24        {
25          "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.",
26          "start_word": 45,
27          "end_word": 72,
28          "topics": [{ "topic": "Online Transacation", "confidence_score": 0.741929 }]
29        }
30      ]
31    }
32  }
33}

Use the API reference or the API Playground to view the detailed response.

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
1{
2  "err_code":"INVALID_QUERY_PARAMETER",
3  "err_msg":"Request specified unsupported language: <language_name>. Only English is supported.",
4  "request_id":"XXXX"
5}

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
1{
2  "err_code": "TOKEN_LIMIT_EXCEEDED",
3  "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.",
4  "request_id": "XXXX"
5}

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
1{
2  "err_code":"INVALID_QUERY_PARAMETER",
3  "err_msg":"Failed to deserialize query parameters: missing field `language`",
4  "request_id":"XXX"
5}
Built with