Topic Detection
Deepgram API Playground
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.
"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
Section titled “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
Section titled “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.
Basic URL Request
Section titled “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
Section titled “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.
Query Parameters
Section titled “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
Section titled “Analyze Response”When the file is finished processing, you’ll receive a JSON response that has the following basic structure:
{
"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
Section titled “API Error Responses”Unsupported Language
Section titled “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.
{
"err_code":"INVALID_QUERY_PARAMETER",
"err_msg":"Request specified unsupported language: <language_name>. Only English is supported.",
"request_id":"XXXX"
}Token Limit Exceeded
Section titled “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.
{
"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
Section titled “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.
{
"err_code":"INVALID_QUERY_PARAMETER",
"err_msg":"Failed to deserialize query parameters: missing field `language`",
"request_id":"XXX"
}