Skip to content

deepgram/deepgram-dotnet-sdk

BranchesTags

Repository files navigation

Deepgram .NET SDK

NuGet Build Status Contributor Covenant Discord

Official .NET SDK for Deepgram. Power your apps with world-class speech and Language AI models.

Documentation

You can learn more about the Deepgram API at developers.deepgram.com.

Requirements

This SDK supports the following versions:

  • .NET 8.0
  • .NET Standard 2.0

Installation

To install the latest version of the .NET SDK using NuGet, run the following command from your terminal in your project's directory:

dotnet add package Deepgram

Or use the NuGet package Manager. Right click on project and select manage NuGet packages.

Getting an API Key

🔑 To access the Deepgram API, you will need a free Deepgram API Key.

Initialization

All of the examples below will require initializing the Deepgram client and inclusion of imports.

using Deepgram;
using Deepgram.Models.Listen.v1.REST;
using Deepgram.Models.Speak.v1.REST;
using Deepgram.Models.Analyze.v1;
using Deepgram.Models.Manage.v1;
using Deepgram.Models.Authenticate.v1;

// Initialize Library with default logging
Library.Initialize();

// Create client using the client factory
var deepgramClient = ClientFactory.CreateListenRESTClient();

Pre-Recorded (Synchronous)

Remote Files (Synchronous)

Transcribe audio from a URL.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var deepgramClient = ClientFactory.CreateListenRESTClient();

// Define Deepgram Options
var response = await deepgramClient.TranscribeUrl(
    new UrlSource("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"),
    new PreRecordedSchema()
    {
        Model = "nova-3",
    });

// Writes to Console
Console.WriteLine($"Transcript: {response.Results.Channels[0].Alternatives[0].Transcript}");

See our API reference for more info.

See the Example for more info.

Local Files (Synchronous)

Transcribe audio from a file.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var deepgramClient = ClientFactory.CreateListenRESTClient();

// Check if file exists
if (!File.Exists("audio.wav"))
{
    Console.WriteLine("Error: File 'audio.wav' not found.");
    return;
}
// Define Deepgram Options
var audioData = File.ReadAllBytes("audio.wav");
var response = await deepgramClient.TranscribeFile(
    audioData,
    new PreRecordedSchema()
    {
        Model = "nova-3",
    });
// Writes to Console
Console.WriteLine($"Transcript: {response.Results.Channels[0].Alternatives[0].Transcript}");

See our API reference for more info.

See the Example for more info.

Pre-Recorded (Asynchronous / Callbacks)

Remote Files (Asynchronous)

Transcribe audio from a URL with callback.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var deepgramClient = ClientFactory.CreateListenRESTClient();

// Define Deepgram Options
var response = await deepgramClient.TranscribeUrl(
    new UrlSource("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"),
    new PreRecordedSchema()
    {
        Model = "nova-3",
        CallBack = "https://your-callback-url.com/webhook",
    });

// Writes to Console
Console.WriteLine($"Request ID: {response.RequestId}");

See our API reference for more info.

Local Files (Asynchronous)

Transcribe audio from a file with callback.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var deepgramClient = ClientFactory.CreateListenRESTClient();

var audioData = File.ReadAllBytes("audio.wav");
var response = await deepgramClient.TranscribeFile(
    audioData,
    new PreRecordedSchema()
    {
        Model = "nova-3",
        CallBack = "https://your-callback-url.com/webhook",
    });

Console.WriteLine($"Request ID: {response.RequestId}");

See our API reference for more info.

Streaming Audio

Transcribe streaming audio.

using Deepgram;
using Deepgram.Models.Listen.v2.WebSocket;
using Deepgram.Models.Speak.v2.WebSocket;
using Deepgram.Models.Agent.v2.WebSocket;

// Initialize Library with default logging
Library.Initialize();

// Create WebSocket client
var liveClient = ClientFactory.CreateListenWebSocketClient();
// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key

// Subscribe to transcription results
await liveClient.Subscribe(new EventHandler<ResultResponse>((sender, e) =>
{
    if (!string.IsNullOrEmpty(e.Channel.Alternatives[0].Transcript))
    {
        Console.WriteLine($"Transcript: {e.Channel.Alternatives[0].Transcript}");
    }
}));

// Connect to Deepgram
var liveSchema = new LiveSchema()
{
    Model = "nova-3",
};
await liveClient.Connect(liveSchema);

// Stream audio data to Deepgram
byte[] audioData = GetAudioData(); // Your audio source
liveClient.Send(audioData);

// Keep connection alive while streaming
await Task.Delay(TimeSpan.FromSeconds(30));

// Stop the connection
await liveClient.Stop();

See our API reference for more info.

See the Examples for more info.

Voice Agent

Configure a Voice Agent.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var agentClient = ClientFactory.CreateAgentWebSocketClient();

// Subscribe to key events
await agentClient.Subscribe(new EventHandler<ConversationTextResponse>
((sender, e) =>
{
    Console.WriteLine($"Agent: {e.Text}");
}));
await agentClient.Subscribe(new EventHandler<AudioResponse>((sender, e) =>
{
    // Handle agent's audio response
    Console.WriteLine("Agent speaking...");
}));

// Configure agent settings
var settings = new SettingsSchema()
{
    Language = "en",
    Agent = new AgentSchema()
    {
        Think = new ThinkSchema()
        {
            Provider = new ProviderSchema()
            {
                Type = "open_ai",
                Model = "gpt-4o-mini",
            },
            Prompt = "You are a helpful AI assistant.",
        },
        Listen = new ListenSchema()
        {
            Provider = new ProviderSchema()
            {
                Type = "deepgram",
                Model = "nova-3",
            },
        },
        // Option 1: Single Provider (Backward Compatibility)
        Speak = new SpeakSchema()
        {
            Provider = new ProviderSchema()
            {
                Type = "deepgram",
                Model = "aura-2-thalia-en",
            },
        },

        // Option 2: Multiple Providers with Fallback Support
        // Uncomment the section below and comment out the single provider above
        // to use multiple TTS providers for enhanced reliability
        /*
        Speak = new SpeakSchema()
        {
            SpeakProviders = new List<SpeakProviderConfig>
            {
                // Primary provider: Deepgram
                new SpeakProviderConfig
                {
                    Provider = new ProviderSchema()
                    {
                        Type = "deepgram",
                        Model = "aura-2-zeus-en",
                    }
                },
                // Fallback provider: OpenAI
                new SpeakProviderConfig
                {
                    Provider = new ProviderSchema()
                    {
                        Type = "open_ai",
                        Model = "tts-1",
                        Voice = "shimmer",
                    },
                    Endpoint = new EndpointSchema()
                    {
                        URL = "https://api.openai.com/v1/audio/speech",
                        Headers = new Dictionary<string, string>
                        {
                            { "authorization", "Bearer {{OPENAI_API_KEY}}" }
                        }
                    }
                }
            }
        },
        */
    },
    Greeting = "Hello, I'm your AI assistant.",
};

// Connect to Deepgram Voice Agent
await agentClient.Connect(settings);

// Keep connection alive
await Task.Delay(TimeSpan.FromSeconds(30));

// Cleanup
await agentClient.Stop();

This example demonstrates:

  • Setting up a WebSocket connection for Voice Agent
  • Configuring the agent with speech, language, and audio settings
  • Handling various agent events (speech, transcripts, audio)
  • Sending audio data and keeping the connection alive

For a complete implementation, you would need to:

  1. Add your audio input source (e.g., microphone)
  2. Implement audio playback for the agent's responses
  3. Handle any function calls if your agent uses them
  4. Add proper error handling and connection management

Text to Speech REST

Convert text into speech using the REST API.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var speakClient = ClientFactory.CreateSpeakRESTClient();

var response = await speakClient.ToFile(
    new TextSource("Hello world!"),
    "output.wav",
    new SpeakSchema()
    {
        Model = "aura-2-thalia-en",
    });

Console.WriteLine($"Audio saved to: output.wav");

See our API reference for more info.

See the Example for more info.

Text to Speech Streaming

Convert streaming text into speech using a WebSocket.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var speakClient = ClientFactory.CreateSpeakWebSocketClient();

// Subscribe to audio responses
await speakClient.Subscribe(new EventHandler<AudioResponse>((sender, e) =>
{
    // Handle the generated audio data
    Console.WriteLine("Received audio data");
}));

// Configure speak options
var speakSchema = new SpeakSchema()
{
    Model = "aura-2-thalia-en",
    Encoding = "linear16",
    SampleRate = 16000,
};

// Connect to Deepgram
await speakClient.Connect(speakSchema);

// Send text to convert to speech
await speakClient.SendText("Hello, this is a text to speech example.");
await speakClient.Flush();

// Wait for completion and cleanup
await speakClient.WaitForComplete();
await speakClient.Stop();

See our API reference for more info.

See the Examples for more info.

Text Intelligence

Analyze text.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var analyzeClient = ClientFactory.CreateAnalyzeClient();

// Check if file exists
if (!File.Exists("text_to_analyze.txt"))
{
    Console.WriteLine("Error: File 'text_to_analyze.txt' not found.");
    return;
}

var textData = File.ReadAllBytes("text_to_analyze.txt");
var response = await analyzeClient.AnalyzeFile(
    textData,
    new AnalyzeSchema()
    {
        Model = "nova-3"
        // Configure Read Options
    });

Console.WriteLine($"Analysis Results: {response}");

See our API reference for more info.

See the Examples for more info.

Authentication

Grant Token

Creates a temporary token with a 30-second TTL.

// Set "DEEPGRAM_API_KEY" environment variable to your Deepgram API Key
var authClient = ClientFactory.CreateAuthClient();

var response = await authClient.GrantToken();

Console.WriteLine($"Token: {response.AccessToken}");

See our API reference for more info.