# Transcribe and analyze pre-recorded audio and video

**POST** `/v1/listen`

Transcribe audio and video using Deepgram's speech-to-text REST API

Base URL: `https://agent.deepgram.com`

Tags: `media`

## Authorization

| Option | Scheme | Type | Sent as | Scopes |
| --- | --- | --- | --- | --- |
| Option 1 | `ApiKeyAuth` | `apiKey` | header `Authorization` | — |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `callback` | `string` | No | URL to which we'll make the callback request |
| `callback_method` | `string` | No | HTTP method by which the callback request will be made Allowed values: `POST`, `PUT`. |
| `extra` | — | No | Arbitrary key-value pairs that are attached to the API response for usage in downstream processing |
| `sentiment` | `boolean` | No | Recognizes the sentiment throughout a transcript or text |
| `summarize` | — | No | Summarize content. For Listen API, supports string version option. For Read API, accepts boolean only. |
| `tag` | — | No | Label your requests for the purpose of identification during usage reporting |
| `topics` | `boolean` | No | Detect topics throughout a transcript or text |
| `custom_topic` | — | No | Custom topics you want the model to detect within your input audio or text if present Submit up to `100`. |
| `custom_topic_mode` | `string` | No | 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 Allowed values: `extended`, `strict`. |
| `intents` | `boolean` | No | Recognizes speaker intent throughout a transcript or text |
| `custom_intent` | — | No | Custom intents you want the model to detect within your input audio if present |
| `custom_intent_mode` | `string` | No | Sets how the model will interpret intents 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 its own detected intents in the `custom_intent` param. Allowed values: `extended`, `strict`. |
| `detect_entities` | `boolean` | No | Identifies and extracts key entities from content in submitted audio |
| `detect_language` | — | No | Identifies the dominant language spoken in submitted audio |
| `diarize` | `boolean` | No | Deprecated: use `diarize_model` instead. Recognize speaker changes. Each word in the transcript will be assigned a speaker number starting at 0. **Deprecated.** |
| `diarize_model` | `string` | No | Select and enable a specific diarization model version. Specifying this parameter enables diarization and selects the model — you do not need to also set the deprecated `diarize=true` parameter. For batch, supported values are `latest` (currently v2), `v1`, and `v2`. For streaming, supported values are `latest` (currently v1) and `v1`; `v2` returns a validation error on streaming requests. Allowed values: `latest`, `v1`, `v2`. |
| `dictation` | `boolean` | No | Dictation mode for controlling formatting with dictated speech |
| `encoding` | `string` | No | Specify the expected encoding of your submitted audio Allowed values: `linear16`, `flac`, `mulaw`, `amr-nb`, `amr-wb`, `opus`, `speex`, `g729`. |
| `filler_words` | `boolean` | No | Filler Words can help transcribe interruptions in your audio, like "uh" and "um" |
| `keyterm` | `array` | No | Key term prompting improves recognition of specialized terminology and brands. Only compatible with Nova-3. `keyterm` accepts plain terms only. Unlike the legacy `keywords` feature, it does not support weights or intensifiers. Appending one (for example, `keyterm=term:0.15`) is not rejected—the weight is silently ignored and the entire value is treated as a literal keyterm. To boost multiple separate keyterms, repeat the `keyterm` parameter (for example, `keyterm=term1&keyterm=term2`). To boost one multi-word phrase as a single keyterm, join the words with `%20` or `+` (for example, `keyterm=customer%20service`). Do not separate keyterms with commas, semicolons, or line breaks. |
| `keywords` | — | No | Keywords can boost or suppress specialized terminology and brands. `keywords` is not supported with Nova-3 models; use `keyterm` instead. |
| `language` | `string` | No | The [BCP-47 language tag](https://tools.ietf.org/html/bcp47) that hints at the primary spoken language. Depending on the Model and API endpoint you choose only certain languages are available |
| `measurements` | `boolean` | No | Spoken measurements will be converted to their corresponding abbreviations |
| `model` | — | No | AI model used to process submitted audio |
| `multichannel` | `boolean` | No | Transcribe each audio channel independently |
| `numerals` | `boolean` | No | Numerals converts numbers from written format to numerical format |
| `paragraphs` | `boolean` | No | Splits audio into paragraphs to improve transcript readability |
| `profanity_filter` | `boolean` | No | Profanity Filter looks for recognized profanity and converts it to the nearest recognized non-profane word or removes it from the transcript completely |
| `punctuate` | `boolean` | No | Add punctuation and capitalization to the transcript |
| `redact` | — | No | Redaction removes sensitive information from your transcripts |
| `replace` | — | No | Search for terms or phrases in submitted audio and replaces them |
| `search` | — | No | Search for terms or phrases in submitted audio |
| `smart_format` | `boolean` | No | Apply formatting to transcript output. When set to true, additional formatting will be applied to transcripts to improve readability |
| `utterances` | `boolean` | No | Segments speech into meaningful semantic units |
| `utt_split` | `number` (double) | No | Seconds to wait before detecting a pause between words in submitted audio |
| `version` | — | No | Version of an AI model to use |
| `mip_opt_out` | `boolean` | No | Opts out requests from the Deepgram Model Improvement Program. Refer to our Docs for pricing impacts before setting this to true. https://dpgr.am/deepgram-mip |

## Request body

Optional. Media type: `application/json`

Transcribe an audio or video file

### Example request body

```json
{
  "url": "https://example.com"
}
```

## Responses

| Status | Description | Media type |
| --- | --- | --- |
| `200` | Returns either transcription results, or a request_id when using a callback. | `application/json` |
| `400` | Invalid Request | `application/json` |

### Example response: 200 — Returns either transcription results, or a request_id when using a callback.

```json
{
  "request_id": "00000000-0000-0000-0000-000000000000"
}
```

### Example response: 400 — Invalid Request

```json
{
  "metadata": {
    "channels": 0,
    "created": "2026-06-09T00:00:00Z",
    "diarize_info": {
      "arch": "string",
      "model_uuid": "string"
    },
    "duration": 0,
    "intents_info": {
      "input_tokens": 0,
      "model_uuid": "string",
      "output_tokens": 0
    },
    "model_info": {},
    "models": [
      "string"
    ],
    "request_id": "00000000-0000-0000-0000-000000000000",
    "sentiment_info": {
      "input_tokens": 0,
      "model_uuid": "string",
      "output_tokens": 0
    },
    "sha256": "string",
    "summary_info": {
      "input_tokens": 0,
      "model_uuid": "string",
      "output_tokens": 0
    },
    "tags": [
      "string"
    ],
    "topics_info": {
      "input_tokens": 0,
      "model_uuid": "string",
      "output_tokens": 0
    },
    "transaction_key": "deprecated"
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "confidence": "string",
            "entities": [
              {
                "confidence": "string",
                "end_word": "string",
                "label": "string",
                "raw_value": "string",
                "start_word": "string",
                "value": "string"
              }
            ],
            "paragraphs": {
              "paragraphs": [
                {
                  "end": "string",
                  "num_words": 0,
                  "sentences": [],
                  "speaker": 0,
                  "start": "string"
                }
              ],
              "transcript": "string"
            },
            "summaries": [
              {
                "end_word": "string",
                "start_word": "string",
                "summary": "string"
              }
            ],
            "topics": [
              {
                "end_word": "string",
                "start_word": "string",
                "text": "string",
                "topics": [
                  "string"
                ]
              }
            ],
            "transcript": "string",
            "words": [
              {
                "confidence": "string",
                "end": "string",
                "speaker": 0,
                "speaker_confidence": "string",
                "start": "string",
                "word": "string"
              }
            ]
          }
        ],
        "detected_language": "string",
        "search": [
          {
            "hits": [
              {
                "confidence": "string",
                "end": "string",
                "snippet": "string",
                "start": "string"
              }
            ],
            "query": "string"
          }
        ]
      }
    ],
    "intents": {
      "segments": [
        {
          "end_word": 0
        }
      ]
    }
  }
}
```

## Related pages

- [Analyze text content](./text_analyze.md)
- [audio](./tags/audio.md)
- [balances](./tags/balances.md)
- [breakdown](./tags/breakdown.md)
- [configurations](./tags/configurations.md)
- [Create a Project Invite](./invites_create.md)
- [Create a Project Key](./keys_create.md)
- [Create a Project Self-Hosted Distribution Credential](./distributioncredentials_create.md)
- [Create an Agent Configuration](./configurations_create.md)
- [Create an Agent Variable](./variables_create.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.