> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.deepgram.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.deepgram.com/_mcp/server. # Getting Started Deepgram API Playground Try this feature out in our API Playground. \ In this guide, you'll learn how to analyze text using Deepgram's text intelligence features: Summarization, Topic Detection, Intent Recognition, and Sentiment Analysis. The code examples use [Deepgram's SDKs](/home). > **Info** > > Before you start, you'll need to follow the steps in the [Make Your First API Request](/guides/fundamentals/make-your-first-api-request) guide to obtain a Deepgram API key, and configure your environment if you are choosing to use a Deepgram SDK. ## Purpose Text Intelligence analyzes text content using four types of analysis: [Summarization](/docs/text-summarization), [Topic Detection](/docs/text-topic-detection), [Intent Recognition](/docs/text-intention-recognition), and [Sentiment Analysis](/docs/text-sentiment-analysis). You can send text as a string, local file, or hosted URL to receive structured analysis results. ## Make the Request A request made using one of the text intelligence features will follow the same form for each of the features; therefore, this guide will walk you through how to make one request, and you can use the feature(s) of your choice depending on which feature you want to use (Summarization, Topic Detection, Intent Recognition, or Sentiment Analysis). ### Choose a Text A text source can be sent to Deepgram as text (a text string or local text file) or as a url (hosted text file). These are referred to as a **basic text request** (string of text such as `"This is a string of text."`) or a **basic url request** (a hosted url such as `https://YOUR_FILE_URL.txt`). ### Basic Text Request This example shows how to analyze a **local text file** as your text source. **`JavaScript`** ```javascript JavaScript const { DeepgramClient } = require("@deepgram/sdk"); const fs = require("fs"); // path to text file const text = fs.readFileSync("text.txt").toString(); const analyzeText = async () => { // STEP 1: Create a Deepgram client using the API key const deepgram = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY }); // STEP 2: Call the analyze method with the text payload and options // STEP 3: Configure Deepgram options for text analysis const result = await deepgram.read.v1.text.analyze({ language: "en", sentiment: true, // intents: true, // summarize: true, // topics: true, body: { text }, }); // STEP 4: Print the results console.dir(result, { depth: null }); }; analyzeText(); ``` **`Python`** ```python Python # For more Python SDK migration guides, visit: # https://github.com/deepgram/deepgram-python-sdk/tree/main/docs import os from dotenv import load_dotenv from deepgram import ( DeepgramClient, ) load_dotenv() # Path to the text file TEXT_FILE = "conversation.txt" API_KEY = os.getenv("DEEPGRAM_API_KEY") def main(): try: # STEP 1 Create a Deepgram client using the API key deepgram = DeepgramClient(api_key=API_KEY) with open(TEXT_FILE, "r") as file: text_data = file.read() # STEP 2: Call the analyze method with the text and options response = deepgram.read.v1.text.analyze( request={"text": text_data}, language="en", sentiment=True, # intents=True, # summarize=True, # topics=True, ) print(response.to_json(indent=4)) except Exception as e: print(f"Exception: {e}") if __name__ == "__main__": main() ``` **`Go`** ```go Go package main import ( "context" "encoding/json" "fmt" "os" prettyjson "github.com/hokaccha/go-prettyjson" analyze "github.com/deepgram/deepgram-go-sdk/pkg/api/analyze/v1" client "github.com/deepgram/deepgram-go-sdk/pkg/client/analyze" interfaces "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces" ) // path to the text file to analyze const ( filePath string = "./conversation.txt" ) func main() { // STEP 1: init Deepgram client library client.InitWithDefault() // STEP 2: define context to manage the lifecycle of the request ctx := context.Background() // STEP 3: define options for the request rOptions := interfaces.AnalyzeOptions{ Language: "en", Sentiment: true, // Summarize: true, // Topics: true, // Intents: true, } // STEP 4: create a Deepgram client using default settings // NOTE: you can set your API KEY in your bash profile by typing the following line in your shell: // export DEEPGRAM_API_KEY = "YOUR_DEEPGRAM_API_KEY" c := client.NewWithDefaults() dg := analyze.New(c) // STEP 5: send/process file to Deepgram res, err := dg.FromFile(ctx, filePath, rOptions) if err != nil { fmt.Printf("FromFile failed. Err: %v\n", err) os.Exit(1) } // STEP 6: get the JSON response data, err := json.Marshal(res) if err != nil { fmt.Printf("json.Marshal failed. Err: %v\n", err) os.Exit(1) } // STEP 7: make the JSON pretty prettyJson, err := prettyjson.Format(data) if err != nil { fmt.Printf("prettyjson.Marshal failed. Err: %v\n", err) os.Exit(1) } fmt.Printf("\n\nResult:\n%s\n\n", prettyJson) } ``` **`Java`** ```java Java // Main.java (Java example) // https://github.com/deepgram/deepgram-java-sdk import com.deepgram.DeepgramClient; import com.deepgram.resources.read.v1.text.requests.TextAnalyzeRequest; import com.deepgram.types.ReadV1Request; import com.deepgram.types.ReadV1RequestText; import com.deepgram.types.ReadV1Response; public class Main { public static void main(String[] args) throws Exception { DeepgramClient client = DeepgramClient.builder().build(); // Read text from a local file String text = new String(java.nio.file.Files.readAllBytes(java.nio.file.Path.of("conversation.txt"))); ReadV1RequestText textBody = ReadV1RequestText.builder().text(text).build(); TextAnalyzeRequest request = TextAnalyzeRequest.builder() .body(ReadV1Request.of(textBody)) .language("en") .sentiment(true) // .summarize(true) // .topics(true) // .intents(true) .build(); ReadV1Response response = client.read().v1().text().analyze(request); System.out.println(response); } } ``` ### Basic URL Request This example shows how to analyze a **hosted url file** as your text source. **`JavaScript`** ```javascript JavaScript const { DeepgramClient } = require("@deepgram/sdk"); const analyzeUrl = async () => { // STEP 1: Create a Deepgram client using the API key const deepgram = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY }); // STEP 2: Call the analyze method with the hosted url source and options // STEP 3: Configure Deepgram options for text analysis const result = await deepgram.read.v1.text.analyze({ language: "en", sentiment: true, // intents: true, // summarize: true, // topics: true, body: { url: "https://static.deepgram.com/examples/aura.txt" }, }); // STEP 4: Print the results console.dir(result, { depth: null }); }; analyzeUrl(); ``` **`Python`** ```python Python # For more Python SDK migration guides, visit: # https://github.com/deepgram/deepgram-python-sdk/tree/main/docs import os from dotenv import load_dotenv from deepgram import ( DeepgramClient, ) load_dotenv() API_KEY = os.getenv("DEEPGRAM_API_KEY") def main(): try: # STEP 1 Create a Deepgram client using the API key deepgram = DeepgramClient(api_key=API_KEY) # STEP 2: Call the analyze method with the URL and options response = deepgram.read.v1.text.analyze( request={"url": "https://static.deepgram.com/examples/aura.txt"}, language="en", sentiment=True, # intents=True, # summarize=True, # topics=True, ) print(response.to_json(indent=4)) except Exception as e: print(f"Exception: {e}") if __name__ == "__main__": main() ``` **`Go`** ```go Go package main import ( "context" "encoding/json" "fmt" "os" prettyjson "github.com/hokaccha/go-prettyjson" analyze "github.com/deepgram/deepgram-go-sdk/pkg/api/analyze/v1" client "github.com/deepgram/deepgram-go-sdk/pkg/client/analyze" interfaces "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces" ) // URL to the file to be sent to Deepgram const ( url string = "https://static.deepgram.com/examples/aura.txt" ) func main() { // STEP 1: init Deepgram client library client.InitWithDefault() // STEP 2: define context to manage the lifecycle of the request ctx := context.Background() // STEP 3: define options for the request options := interfaces.AnalyzeOptions{ Language: "en", Sentiment: true, // Summarize: true, // Topics: true, // Intents: true, } // STEP 4: create a Deepgram client using default settings // NOTE: you can set your API KEY in your bash profile by typing the following line in your shell: // export DEEPGRAM_API_KEY = "YOUR_DEEPGRAM_API_KEY" c := client.NewWithDefaults() dg := analyze.New(c) // STEP 5: send/process file to Deepgram res, err := dg.FromURL(ctx, url, options) if err != nil { fmt.Printf("FromFile failed. Err: %v\n", err) os.Exit(1) } // STEP 6: get the JSON response data, err := json.Marshal(res) if err != nil { fmt.Printf("json.Marshal failed. Err: %v\n", err) os.Exit(1) } // STEP 7: make the JSON pretty prettyJson, err := prettyjson.Format(data) if err != nil { fmt.Printf("prettyjson.Marshal failed. Err: %v\n", err) os.Exit(1) } fmt.Printf("\n\nResult:\n%s\n\n", prettyJson) } ``` **`Java`** ```java Java // Main.java (Java example) // https://github.com/deepgram/deepgram-java-sdk import com.deepgram.DeepgramClient; import com.deepgram.resources.read.v1.text.requests.TextAnalyzeRequest; import com.deepgram.types.ReadV1Request; import com.deepgram.types.ReadV1RequestUrl; import com.deepgram.types.ReadV1Response; public class Main { public static void main(String[] args) throws Exception { DeepgramClient client = DeepgramClient.builder().build(); ReadV1RequestUrl urlBody = ReadV1RequestUrl.builder() .url("https://static.deepgram.com/examples/aura.txt") .build(); TextAnalyzeRequest request = TextAnalyzeRequest.builder() .body(ReadV1Request.of(urlBody)) .language("en") .sentiment(true) // .summarize(true) // .topics(true) // .intents(true) .build(); ReadV1Response response = client.read().v1().text().analyze(request); System.out.println(response); } } ``` ### Start the Application Run your application from the terminal. **`JavaScript`** ```javascript JavaScript # Run your application using the file you created in the previous step # Example: node index.js node index.js ``` **`Python`** ```shell Python # Run your application using the file you created in the previous step # Example: python deepgram_test.py python YOUR_PROJECT_NAME.py ``` **`Go`** ```shell Go # Run your application using the file you created in the previous step # Example: go run main.go go run YOUR_PROJECT_NAME.go ``` **`Java`** ```shell Java mvn compile exec:java -Dexec.mainClass="Main" ``` ### See Results Your results will appear in your shell. ## Analyze the Response When the file is finished processing (often after only a few seconds), you’ll receive a JSON response: **`summarization`** ```json summarization { "metadata": { "request_id": "aff28024-3006-49e2-b70d-aabff2c23655", "created": "2024-01-30T15:22:33.604Z", "language": "en", "summary_info": { "model_uuid": "67875a7f-c9c4-48a0-aa55-5bdb8a91c34a", "input_tokens": 107, "output_tokens": 63 } }, "results": { "summary": { "text": "The speaker discusses the advances in speech recognition and spoken language understanding, citing examples such as the development of new transformer architectures for dealing with conversational audio and the use of model research for accurate transcriptions. They also mention the use of novel transformer architectures for handling conversational audio and the challenges of natural language understanding." } } } ``` **`topic detection`** ```json topic detection { "metadata": { "request_id": "6a0bdf68-ac01-47ae-96e3-b8fec7cb6477", "created": "2024-01-30T15:27:45.331Z", "language": "en", "topics_info": { "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc", "input_tokens": 118, "output_tokens": 12 } }, "results": { "topics": { "segments": [ { "text": "For nearly a decade, we’ve worked tirelessly to advance the art of the possible in speech recognition and spoken language understanding.", "start_word": 1, "end_word": 21, "topics": [ { "topic": "Speech recognition", "confidence_score": 0.926069 } ] }, { "text": "Along the way, we’ve transcribed trillions of spoken words into highly accurate transcriptions.", "start_word": 21, "end_word": 33, "topics": [ { "topic": "Transcripts", "confidence_score": 0.052929323 } ] }, { "text": "Our model research team has developed novel transformer architectures equipped to deal with the nuances of conversational audio–across different languages, accents, and dialects, while handling disfluencies and the changing rhythms, tones, cadences, and inflections that occur in natural, back-and-forth conversations.", "start_word": 34, "end_word": 73, "topics": [ { "topic": "Conversational audio", "confidence_score": 0.63991606 } ] } ] } } } ``` **`intent recognition`** ```json intent recognition { "metadata": { "request_id": "55dd2a7e-9fde-48c6-8db0-b00a98291c5a", "created": "2024-01-30T15:29:38.662Z", "language": "en", "intents_info": { "model_uuid": "80ab3179-d113-4254-bd6b-4a2f96498695", "input_tokens": 118, "output_tokens": 14 } }, "results": { "intents": { "segments": [ { "text": "Our model research team has developed novel transformer architectures equipped to deal with the nuances of conversational audio–across different languages, accents, and dialects, while handling disfluencies and the changing rhythms, tones, cadences, and inflections that occur in natural, back-and-forth conversations.", "start_word": 34, "end_word": 73, "intents": [ { "intent": "Propose novel transformer architectures", "confidence_score": 0.0000743953 }, { "intent": "Address conversational audio", "confidence_score": 0.07617511 } ] } ] } } } ``` **`sentiment analysis`** ```json sentiment analysis { "metadata": { "request_id": "7c5516be-366c-499f-b0ff-11bc058f631a", "created": "2024-01-30T15:30:22.130Z", "language": "en", "sentiment_info": { "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc", "input_tokens": 118, "output_tokens": 118 } }, "results": { "sentiments": { "segments": [ { "text": "For nearly a decade, we’ve worked tirelessly to advance the art of the possible in speech recognition and spoken language understanding. Along the way, we’ve transcribed trillions of spoken words into highly accurate transcriptions.", "start_word": 0, "end_word": 33, "sentiment": "positive", "sentiment_score": 0.5421093702316284 }, { "text": "Our model research team has developed novel transformer architectures equipped to deal with the nuances of conversational audio–across different languages, accents, and dialects, while handling disfluencies and the changing rhythms, tones, cadences, and inflections that occur in natural, back-and-forth conversations.", "start_word": 34, "end_word": 73, "sentiment": "neutral", "sentiment_score": 0.27087897062301636 } ], "average": { "sentiment": "positive", "sentiment_score": 0.3812099715410653 } } } } ``` Following are explanations of each of the example responses. Be sure to click the tabs in the code block above to view the example response for each text analysis feature. ### Summarization In the `metadata` object, we see: * `summary_info`: information about the model used and the input/output tokens. Summarization pricing is based on the number of input and output tokens. Read more at [deepgram.com/pricing](https://deepgram.com/pricing). In the `results` object, we see: * `summary`: the `text` property in this object gives you the summary of the text you requested to be analyzed. ### Topic Detection In the `metadata` object, we see: * `topics_info`: information about the model used and the input/output tokens. Topic Detection pricing is based on the number of input and output tokens. Read more at [deepgram.com/pricing](https://deepgram.com/pricing). In the `results` object, we see: * `topics`(object): contains the data about Topic Detection. * `segments`: each segment object contains a span of text taken from the input text; this `text` segment is analyzed for its topic. * `topics`(array): a list of topic objects, each containing the `topic` and a `confidence_score`. * `topic`: Deepgram analyzes the segmented text to identify the main topic of each. * `confidence_score`: a floating point value between 0 and 1 indicating the overall reliability of the analysis. ### Intent Recognition In the `metadata` object, we see: * `intents_info`: information about the model used and the input/output tokens. Intent Recognition pricing is based on the number of input and output tokens. Read more at [deepgram.com/pricing](https://deepgram.com/pricing). In the `results` object, we see: * `intents`(object): contains the data about Intent Recognition. * `segments`: each segment object contains a span of text taken from the input text; this `text` segment is analyzed for its intent. * `intents`(array): a list of intent objects, each containing the `intent` and a `confidence_score`. * `intent`: Deepgram analyzes the segmented text to identify the intent of each. * `confidence_score`: a floating point value between 0 and 1 indicating the overall reliability of the analysis. ### Sentiment Analysis In the `metadata` object, we see: * `sentiment_info`: information about the model used and the input/output tokens. Sentiment Analysis pricing is based on the number of input and output tokens. Read more at [deepgram.com/pricing](https://deepgram.com/pricing). In the `results` object, we see: * `sentiments`(object): contains the data about Sentiment Analysis. * `segments`: each segment object contains a span of text taken from the input text; these segments of text show when the sentiment shifts throughout the text, and each one is analyzed for its sentiment. * `sentiment` can be `positive`, `negative`, or `neutral`. * `sentiment_score`: a floating point value between -1 and 1 representing the sentiment of the associated span of text, with -1 being the most negative sentiment, and 1 being the most positive sentiment. * `average`: the average sentiment for the entire input text. ## Constraints Here are a few constraints to keep in mind when making your request. ### Language At this time, text analysis features only work for English language texts. You must add a language parameter and set it to English when you make a text analysis request. **`Python`** ```python Python response = client.read.v1.text.analyze( request={"text": "Your text here"}, language="en", summarize=True, ) ``` ### Token Limit The input token limit is 150K tokens. When that limit is exceeded, a `400` error will be thrown. **`JSON`** ```json JSON { "err_code": "TOKEN_LIMIT_EXCEEDED", "err_msg": "Text input 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" } ```