Deepgram API Playground

Try this feature out in our API Playground.

This guide walks you through transcribing pre-recorded audio with the Deepgram API using cURL or one of Deepgram's SDKs.

:::callout{intent="info"}
Before you start, you'll need to follow the steps in the [Make Your First API Request](/guides/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.
:::

## cURL

Replace `YOUR_DEEPGRAM_API_KEY` with your API key and run the following in a terminal or API client.

### Remote file

```curl
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://dpgr.am/spacewalk.wav"}' \
  --url 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true'
```

### Local file

Replace `@youraudio.wav` with the path to an audio file on your computer. See [Supported Audio Formats](/guides/guides-docs-supported-audio-formats) for accepted formats.

```curl
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true'
```

:::callout{intent="info"}
The above examples include `model=nova-3`, which tells the API to use Deepgram's latest model. Removing this parameter defaults to `model=base`.

They also include Deepgram's [Smart Formatting](/guides/formatting-smart-format) feature (`smart_format=true`), which formats currency amounts, phone numbers, email addresses, and more for enhanced readability.
:::

## SDKs

To transcribe pre-recorded audio using one of Deepgram's SDKs, follow these steps.

### Install the SDK and dependencies

Open your terminal, navigate to your project directory, and install the Deepgram SDK along with any required dependencies.

:::code-group
```shell title="JavaScript"
# Install the Deepgram JS SDK and dotenv
# https://github.com/deepgram/deepgram-js-sdk

npm install @deepgram/sdk dotenv
```

```shell title="Python"
# Install the Deepgram Python SDK and python-dotenv
# https://github.com/deepgram/deepgram-python-sdk

pip install deepgram-sdk python-dotenv
```

```shell title="C#"
# Install the Deepgram .NET SDK
# https://github.com/deepgram/deepgram-dotnet-sdk

dotnet add package Deepgram
```

```shell title="Go"
# Install the Deepgram Go SDK
# https://github.com/deepgram/deepgram-go-sdk

go get github.com/deepgram/deepgram-go-sdk
```

```shell title="Java"
# Install the Deepgram Java SDK
# https://github.com/deepgram/deepgram-java-sdk

# Maven — add to pom.xml:
# <dependency>
#   <groupId>com.deepgram</groupId>
#   <artifactId>deepgram-java-sdk</artifactId>
#   <version>0.9.0</version>
# </dependency>

# Gradle — add to build.gradle:
# implementation 'com.deepgram:deepgram-java-sdk:0.9.0'
```
:::

### Transcribe a remote file

Create a new file in your project and add the following code to transcribe a remote audio file by URL:

:::code-group
```javascript title="JavaScript"
// index.js (node example)

const { DeepgramClient } = require("@deepgram/sdk");
const dotenv = require("dotenv");
dotenv.config();

const transcribeUrl = 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 transcribeUrl method with the audio payload and options
  // STEP 3: Configure Deepgram options for audio analysis
  const result = await deepgram.listen.v1.media.transcribeUrl({
    url: "https://dpgr.am/spacewalk.wav",
    model: "nova-3",
    smart_format: true,
  });

  // STEP 4: Print the results
  console.dir(result, { depth: null });
};

transcribeUrl();
```

```python title="Python"
# main.py (python example)

import os
import dotenv

from deepgram import (
    DeepgramClient,
)

dotenv.load_dotenv()

def main():
    try:
        # STEP 1 Create a Deepgram client using the API key
        deepgram = DeepgramClient(api_key=os.getenv("DEEPGRAM_API_KEY"))

        # STEP 2 Call the transcribe_url method with the audio URL and options
        response = deepgram.listen.v1.media.transcribe_url(
            url="https://dpgr.am/bueller.wav",
            model="nova-3",
            smart_format=True,
        )
        print(f"response: {response}\n\n")

    except Exception as e:
        print(f"Exception: {e}")

if __name__ == "__main__":
    main()
```

```csharp title="C#"
// Program.cs (.NET example)

using Deepgram.Models.Listen.v1.REST;

namespace PreRecorded
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Initialize Library with default logging
            // Normal logging is "Info" level
            Library.Initialize();

            // create a ListenRESTClient directly (without using the factory method) with a API Key
            // set using the "DEEPGRAM_API_KEY" environment variable
            var deepgramClient = new ListenRESTClient();

            var response = await deepgramClient.TranscribeUrl(
                new UrlSource("https://dpgr.am/bueller.wav"),
                new PreRecordedSchema()
                {
                    Model = "nova-3",
                });

            Console.WriteLine(response);
            Console.ReadKey();

            // Teardown Library
            Library.Terminate();
        }
    }
}
```

```go title="Go"
// main.go (Go example)

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	prettyjson "github.com/hokaccha/go-prettyjson"

	prerecorded "github.com/deepgram/deepgram-go-sdk/pkg/api/prerecorded/v1"
	interfaces "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces"
	client "github.com/deepgram/deepgram-go-sdk/pkg/client/prerecorded"
)

// URL to the audio file to analyze
const (
	url string = "https://dpgr.am/spacewalk.wav"
)

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.PreRecordedTranscriptionOptions{
		Model:       "nova-3",
		SmartFormat: 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 := prerecorded.New(c)

	// STEP 5: send/process file to Deepgram
	res, err := dg.FromURL(ctx, url, options)
	if err != nil {
		fmt.Printf("FromURL 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 title="Java"
// Main.java (Java example)
// https://github.com/deepgram/deepgram-java-sdk

import java.util.Collections;
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.media.requests.ListenV1RequestUrl;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeRequestModel;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import com.deepgram.types.ListenV1Response;
import com.deepgram.types.ListenV1AcceptedResponse;

public class Main {
    public static void main(String[] args) {
        // Create a client using DEEPGRAM_API_KEY from the environment
        DeepgramClient client = DeepgramClient.builder().build();

        MediaTranscribeResponse result = client.listen().v1().media().transcribeUrl(
            ListenV1RequestUrl.builder()
                .url("https://dpgr.am/spacewalk.wav")
                .model(MediaTranscribeRequestModel.NOVA3)
                .smartFormat(true)
                .build()
        );

        result.visit(new MediaTranscribeResponse.Visitor<Void>() {
            @Override
            public Void visit(ListenV1Response response) {
                String transcript = response.getResults()
                    .getChannels().get(0)
                    .getAlternatives().orElse(Collections.emptyList()).get(0)
                    .getTranscript().orElse("");
                System.out.println(transcript);
                return null;
            }
            @Override
            public Void visit(ListenV1AcceptedResponse accepted) {
                System.out.println("Async request accepted: " + accepted.getRequestId());
                return null;
            }
        });
    }
}
```
:::

:::callout{intent="info"}
To transcribe a **local file** instead of a remote URL, use the `transcribeFile` (JavaScript), `transcribe_file` (Python), `TranscribeFile` (C#), `FromFile` (Go), or `transcribeFile` (Java) method. Pass the file's binary content and the same options. See the [Pre-Recorded Audio API reference](/guides/self-hosted-deployments-2-reference-speech-to-text-listen-pre-recorded) for details.
:::

### Transcribe a local file

:::code-group
```javascript title="JavaScript"
// index.js (node example)

const { DeepgramClient } = require("@deepgram/sdk");
const fs = require("fs");
const dotenv = require("dotenv");
dotenv.config();

const transcribeFile = 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 transcribeFile method with the audio payload and options
  // STEP 3: Configure Deepgram options for audio analysis
  const result = await deepgram.listen.v1.media.transcribeFile(
    // path to the audio file
    fs.createReadStream("spacewalk.mp3"),
    {
      model: "nova-3",
      smart_format: true,
    }
  );

  // STEP 4: Print the results
  console.dir(result, { depth: null });
};

transcribeFile();
```

```python title="Python"
# For more Python SDK migration guides, visit:
# https://github.com/deepgram/deepgram-python-sdk/tree/main/docs

# main.py (python example)

import os
import dotenv

from deepgram import (
    DeepgramClient,
)

dotenv.load_dotenv()

# Path to the audio file
AUDIO_FILE = "spacewalk.mp3"

def main():
    try:
        # STEP 1 Create a Deepgram client using the API key
        deepgram = DeepgramClient(api_key=os.getenv("DEEPGRAM_API_KEY"))

        # STEP 2: Call the transcribe_file method with the audio file and options
        with open(AUDIO_FILE, "rb") as audio_file:
            response = deepgram.listen.v1.media.transcribe_file(
                request=audio_file.read(),
                model="nova-3",
                smart_format=True,
            )

        # STEP 3: Print the response
        print(response.to_json(indent=4))

    except Exception as e:
        print(f"Exception: {e}")

if __name__ == "__main__":
    main()
```

```csharp title="C#"
// Program.cs (.NET example)

using Deepgram.Models.Listen.v1.REST;

namespace PreRecorded
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Initialize Library with default logging
            // Normal logging is "Info" level
            Library.Initialize();

            // use the client factory with a API Key set with the "DEEPGRAM_API_KEY" environment variable
            var deepgramClient = ClientFactory.CreateListenRESTClient();

            // check to see if the file exists
            if (!File.Exists(@"Bueller-Life-moves-pretty-fast.wav"))
            {
                Console.WriteLine("Error: File 'Bueller-Life-moves-pretty-fast.wav' not found.");
                return;
            }

            var audioData = File.ReadAllBytes(@"Bueller-Life-moves-pretty-fast.wav");
            var response = await deepgramClient.TranscribeFile(
                audioData,
                new PreRecordedSchema()
                {
                    Model = "nova-3",
                });

            Console.WriteLine($"\n\n{response}\n\n");
            Console.WriteLine("Press any key to exit...");
            Console.ReadKey();

            // Teardown Library
            Library.Terminate();
        }
    }
}
```

```go title="Go"
// main.go (Go example)

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	prettyjson "github.com/hokaccha/go-prettyjson"

	prerecorded "github.com/deepgram/deepgram-go-sdk/pkg/api/prerecorded/v1"
	interfaces "github.com/deepgram/deepgram-go-sdk/pkg/client/interfaces"
	client "github.com/deepgram/deepgram-go-sdk/pkg/client/prerecorded"
)

// path to the audio file
const (
	filePath string = "spacewalk.mp3"
)

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.PreRecordedTranscriptionOptions{
		Model:       "nova-3",
		SmartFormat: 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 := prerecorded.New(c)

	// STEP 5: send/process file to Deepgram
	res, err := dg.FromFile(ctx, filePath, &options)
	if err != nil {
		fmt.Printf("FromStream 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 title="Java"
// Main.java (Java example)
// https://github.com/deepgram/deepgram-java-sdk

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Collections;
import com.deepgram.DeepgramClient;
import com.deepgram.resources.listen.v1.media.types.MediaTranscribeResponse;
import com.deepgram.types.ListenV1Response;
import com.deepgram.types.ListenV1AcceptedResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        // STEP 1: Create a Deepgram client using DEEPGRAM_API_KEY from the environment
        DeepgramClient client = DeepgramClient.builder().build();

        // STEP 2: Read local file as bytes and transcribe
        byte[] audioData = Files.readAllBytes(Path.of("spacewalk.mp3"));
        MediaTranscribeResponse result = client.listen().v1().media().transcribeFile(audioData);

        // STEP 3: Print the results
        result.visit(new MediaTranscribeResponse.Visitor<Void>() {
            @Override
            public Void visit(ListenV1Response response) {
                System.out.println(response);
                return null;
            }
            @Override
            public Void visit(ListenV1AcceptedResponse accepted) {
                System.out.println("Request accepted: " + accepted.getRequestId());
                return null;
            }
        });
    }
}
```
:::

## Non-SDK code examples

For language-specific examples that don't use Deepgram's SDKs, see the [recipes repository](https://github.com/deepgram/recipes). We recommend trying the SDKs first.

## Results

Run your application from the terminal. Your transcript appears in your shell.

:::code-group
```shell title="JavaScript"
node index.js
```

```shell title="Python"
python main.py
```

```shell title="C#"
dotnet run
```

```shell title="Go"
go run main.go
```

```shell title="Java"
mvn compile exec:java -Dexec.mainClass="Main"
```
:::

:::callout{intent="warning"}
Deepgram does not store transcripts, so the API response is the only opportunity to retrieve the transcript. Save output or [return transcriptions to a callback URL for custom processing](/guides/results-processing-callback).
:::

### Analyze the response

When the file finishes processing (often after only a few seconds), you receive a JSON response:

**`JSON`**

```json JSON
{
  "metadata": {
    "transaction_key": "deprecated",
    "request_id": "2479c8c8-8185-40ac-9ac6-f0874419f793",
    "sha256": "154e291ecfa8be6ab8343560bcc109008fa7853eb5372533e8efdefc9b504c33",
    "created": "2024-02-06T19:56:16.180Z",
    "duration": 25.933313,
    "channels": 1,
    "models": [
      "30089e05-99d1-4376-b32e-c263170674af"
    ],
    "model_info": {
      "30089e05-99d1-4376-b32e-c263170674af": {
        "name": "2-general-nova",
        "version": "2024-01-09.29447",
        "arch": "nova-3"
      }
    }
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "transcript": "Yeah. As as much as, it's worth celebrating, the first, spacewalk, with an all female team, I think many of us are looking forward to it just being normal. And, I think if it signifies anything, It is, to honor the the women who came before us who, were skilled and qualified, and didn't get the the same opportunities that we have today.",
            "confidence": 0.99902344,
            "words": [
              {
                "word": "yeah",
                "start": 0.08,
                "end": 0.32,
                "confidence": 0.9975586,
                "punctuated_word": "Yeah."
              },
              {
                "word": "as",
                "start": 0.32,
                "end": 0.79999995,
                "confidence": 0.9921875,
                "punctuated_word": "As"
              }
            ],
            "paragraphs": {
              "transcript": "\nYeah. As as much as, it's worth celebrating...",
              "paragraphs": [
                {
                  "sentences": [
                    {
                      "text": "Yeah.",
                      "start": 0.08,
                      "end": 0.32
                    }
                  ],
                  "num_words": 63,
                  "start": 0.08,
                  "end": 25.52
                }
              ]
            }
          }
        ]
      }
    ]
  }
}
```

:::callout{intent="info"}
The response above is truncated for brevity. The full response includes a `words` entry for every word in the transcript and all sentences in the `paragraphs` object.
:::

In this response:

- `transcript`: the transcript for the audio segment being processed.
- `confidence`: a floating point value between 0 and 1 that indicates overall transcript reliability. Larger values indicate higher confidence.
- `words`: an object containing each `word` in the transcript, along with its `start` time and `end` time (in seconds) from the beginning of the audio stream, and a `confidence` value.
  - Because we passed the `smart_format: true` option, each word object also includes its `punctuated_word` value, which contains the transformed word after punctuation and capitalization are applied.

:::callout{intent="info"}
The `transaction_key` in the `metadata` field can be ignored. The result is always `"transaction_key": "deprecated"`.
:::

## Limits

- **File size**: Maximum 2 GB. For large video files, extract the audio stream first.
- **Rate limits**: Up to 100 concurrent requests per project for Nova, Base, and Enhanced models. For full details, see [API Rate Limits](/guides/self-hosted-deployments-2-reference-api-rate-limits).
- **Processing time**: Requests exceeding 10 minutes (Nova/Base/Enhanced) or 20 minutes (Whisper) return a `504: Gateway Timeout` error.

## What's next?

- [Feature overview](/guides/pre-recorded-audio-stt-pre-recorded-feature-overview): Review the full list of features available for pre-recorded speech-to-text.
- [Language](/guides/models-and-languages-language): Transcribe audio in other languages.
- [Streaming audio](/guides/streaming-audio-live-streaming-audio): Transcribe audio in real time.
- [Use cases](/guides/guides-docs-twilio-and-deepgram-stt): Explore ways to use Deepgram products.

***

## Related pages

- [Amazon SageMaker](./amazon-sagemaker-index.md)
- [Aura](./aura-index.md)
- [Changelog](../changelog.md)
- [Custom Vocabulary](./custom-vocabulary-index.md)
- [Deepgram's Docs](../index.md)
- [Deployment](./deployment-index.md)
- [Docker/Podman](./docker-podman-index.md)
- [Features](./features-index.md)
- [Flux TTS](./flux-tts-index.md)
- [Formatting](./formatting-index.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.