Summarization — Deepgram

summarize boolean Default: false

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

Summarization accepts an input text and analyzes the text. It then summarizes the content of the submitted text and returns a brief summary in the JSON response.

JSON

1  "results": {
2     "summary": {
3       "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."
4     }
5   }

Enable Feature

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

summarize=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_HERE"}' \
> 	"https://api.deepgram.com/v1/read?summarize=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)

cURL

$ 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"

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
`summarize`	`true`	boolean	Enables summarization. The output response will include a `summary` object, and within that object will be a `text`property that contains a short summary of the entire text.
`language`	`en`	string	The language of your input text (Only English is supported at this time)

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": "6ab1afe9-da49-4688-86f5-ae2fde420ad4",
4     "created": "2023-11-28T04:49:56.034Z",
5     "language": "en",
6     "summary_info": {
7       "model_uuid": "67875a7f-c9c4-48a0-aa55-5bdb8a91c34a",
8       "input_tokens": 21,
9       "output_tokens": 33
10     }
11   },
12   "results": {
13     "summary": {
14       "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."
15     }
16   }
17 }

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

The summary object contains:

text: Short summary of the audio being summarized.

API Error Responses

Unsupported Language

Status 400

If you request Summarization with an unsupported language by specifying a language code such as summarize=true&language=es or summarize=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 (summarize) 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 }

1	"results": {
2	"summary": {
3	"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."
4	}
5	}

$	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"

1	{
2	"metadata": {
3	"request_id": "6ab1afe9-da49-4688-86f5-ae2fde420ad4",
4	"created": "2023-11-28T04:49:56.034Z",
5	"language": "en",
6	"summary_info": {
7	"model_uuid": "67875a7f-c9c4-48a0-aa55-5bdb8a91c34a",
8	"input_tokens": 21,
9	"output_tokens": 33
10	}
11	},
12	"results": {
13	"summary": {
14	"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."
15	}
16	}
17	}

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	}

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	}

1	{
2	"err_code":"INVALID_QUERY_PARAMETER",
3	"err_msg":"Failed to deserialize query parameters: missing field `language`",
4	"request_id":"XXX"
5	}