Intelligence APIs that accept text inputs.
Endpoint
https://api.deepgram.com/v1/read
Summarization
Provides a brief summary of the input text.
Query Parameters
| Param | Description | Values |
|---|---|---|
| summarize | Enables summarization | - "False" (default) - "True" |
| language | The language of your input text. (Only English is supported at this time) | "en" |
Example Requests
Basic Text Request
curl -vX POST \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "YOUR_TEXT_HERE"}' \
"https://api.deepgram.com/v1/read?summarize=true&language=en"
Basic URL Request
curl -vX POST \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://YOUR_FILE_URL.txt"}' \
"https://api.deepgram.com/v1/read?summarize=true&language=en"
👀 Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.
Example Response
{
"metadata": {
"request_id": "6ab1afe9-da49-4688-86f5-ae2fde420ad4",
"created": "2023-11-28T04:49:56.034Z",
"language": "en",
"summary_info": {
"model_uuid": "67875a7f-c9c4-48a0-aa55-5bdb8a91c34a",
"input_tokens": 21,
"output_tokens": 33
}
},
"results": {
"summary": {
"text": "Jake calls the Honda dealership and speaks with Josh about the new Honda Civic 2023. Jake schedules a test drive for the hybrid model on Friday and provides his contact information.Josh confirms the appointment and tells Jake to call if he has any further questions."
}
}
}
Sentiment Analysis
Recognizes the sentiment of the entire transcript and detects shift in sentiment throughout the transcript.
Query Parameters
| Param | Description | Values |
|---|---|---|
| sentiment | Enables sentiment analysis | - "False" (default) - "True" |
| language | The language of your input audio (Only english is supported at this time) | "en" |
Example Requests
Basic text request
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?sentiment=true&language=en"
Basic URL request
curl -vX POST \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://YOUR_FILE_URL.txt"}' \
"https://api.deepgram.com/v1/read?sentiment=true&language=en"
Example Response
{
"metadata": {
"request_id": "7dcd719f-344b-4c72-a194-6bd1019d855c",
"created": "2023-12-01T15:54:39.681Z",
"language": "en",
"sentiment_info": {
"model_uuid": "80ab3179-d113-4254-bd6b-4a2f96498695",
"input_tokens": 22,
"output_tokens": 22
}
},
"results": {
"sentiments": {
"segments": [
{
"text": "Hi. Thank you for calling from premier phone services.",
"start_word": 0,
"end_word": 8,
"sentiment": "positive",
"sentiment_score": 0.7380304336547852
},
{
"text": "This call may be recorded for quality and training purposes.",
"start_word": 9,
"end_word": 18,
"sentiment": "neutral",
"sentiment_score": 0.057771213352680206
}
],
"average": {
"sentiment": "positive",
"sentiment_score": 0.39790084145285864
}
}
}
}
Response Properties
| Property | description |
|---|---|
| sentiments.segments | Spans of text covering your entire input that show when the sentiment shifts throughout the text. |
| sentiments.segments[i].sentiment | A rating for the given span of text. Can be either "positive", "neutral", or "negative". |
| sentiments.segments[i].sentiment_score | A floating point value between -1 and 1 representing the sentiment of the associated span of text. -1 being the most negative sentiment, and 1 being the most positive sentiment. |
| sentiments.average | The average sentiment for the entire input text |
Topic Detection
Detects topics throughout an entire transcript. Returns a list text segments and the topics found within each segment.
Query Parameters
| Param | Description | Values |
|---|---|---|
| topics | Enables topic detection | - "False" (default) - "True" |
| language | The language of your input text (Only english is supported at this time) | "en" |
| custom_topic | Optional. A custom topic you want the model to detect within your input text if present. Submit up to 100. | string |
| custom_topic_mode | 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 it's own detected topics in addition those submitted using the custom_topic param. | - "strict" - "extended" (default) |
Example Requests
Basic Text Request
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"
Basic URL Request
curl -vX POST \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://YOUR_FILE_URL.txt"}' \
"https://api.deepgram.com/v1/read?topics=true&language=en"
Custom Topic Request
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"
👀 Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.
Example Response
{
"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 }]
}
]
}
}
}
Intent Recognition
Recognizes speaker intent throughout an entire transcript. Returns a list text segments and the intents found within each segment.
Query Parameters
| Param | Description | Values |
|---|---|---|
| intents | Enables intent recognition | - "False" (default) - "True" |
| language | The language of your input text (Only english is supported at this time) | "en" |
| custom_intent | Optional. A custom intent you want the model to detect within your input text if present. Submit up to 100. | string |
| custom_intent_mode | Optional. Sets how the model will interpret strings submitted to the custom_intent param. When "strict", the model will only return intents submitted using the custom_intent param. When "extended", the model will return it's own detected intents in addition those submitted using the custom_intents param. | - "strict" - "extended" (default) |
Example Requests
Basic Text Request
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?intents=true&language=en"
Basic URL Request
curl -vX POST \
-H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://YOUR_FILE_URL.txt"}' \
"https://api.deepgram.com/v1/read?intents=true&language=en"
Custom Intent Request
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?intents=true&language=en&custom_intent_mode=strict&custom_intent=Upgrade%20Phone"
👀 Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.
Example Response
{
"metadata": {
"request_id": "65be7382-9d92-4373-bf5e-ef3a3d0cf56c",
"created": "2024-01-19T17:52:23.970Z",
"language": "en",
"intents_info": {
"model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc",
"input_tokens": 22,
"output_tokens": 4
}
},
"results": {
"intents": {
"segments": [
{
"text": "Can I upgrade my phone?",
"start_word": 12,
"end_word": 16,
"intents": [
{ "intent": "Upgrade phone", "confidence_score": 0.9750028 }
]
}
]
}
}
}
API Error and Warning Responses
Unsupported Language
Status 400
The request's 'language' param contains an unsupported language.
{
"err_code": "UNSUPPORTED_LANGUAGE",
"err_msg": "<api_name> isn't supported with <non supported language>. For more information, please visit our API documentation.",
"request_id": "XXXX"
}
Token Limit Exceeded
Status 400
The request's input length exceeded the 150k token limit per request.
{
"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
The request sent contained only a feature parameter (summarize, sentiment, topics, intents) OR only the 'language' parameter, but not both.
{
"err_code": "MISSING_QUERY_PARAM",
"err_msg": "You must include at least one valid feature param and the language query param",
"request_id": "XXXX"
}
Unknown Query Parameter
The request contained an invalid query parameter.
{
"err_code": "UNKOWN_QUERY_PARAM",
"err_msg": "The following query param is not valid: <invalid_param_passed>",
"request_id": "XXXX"
}