Deepgram .NET SDK

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

Deepgram .NET SDK

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:

Add your audio input source (e.g., microphone)
Implement audio playback for the agent's responses
Handle any function calls if your agent uses them
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.

See the Examples for more info.

Projects

Get Projects

Returns all projects accessible by the API key.

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

var response = await manageClient.GetProjects();

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

See our API reference for more info.

See the Example for more info.

Get Project

Retrieves a specific project based on the provided project_id.

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

var response = await manageClient.GetProject(projectId);

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

See our API reference for more info.

See the Example for more info.

Update Project

Update a project.

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

var updateOptions = new ProjectSchema()
{
    Name = "Updated Project Name",
};

var response = await manageClient.UpdateProject(projectId, updateOptions);

Console.WriteLine($"Update result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Delete Project

Delete a project.

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

var response = await manageClient.DeleteProject(projectId);

Console.WriteLine($"Delete result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Keys

List Keys

Retrieves all keys associated with the provided project_id.

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

var response = await manageClient.GetKeys(projectId);

Console.WriteLine($"Keys: {response.APIKeys}");

See our API reference for more info.

See the Example for more info.

Get Key

Retrieves a specific key associated with the provided project_id.

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

var response = await manageClient.GetKey(projectId, keyId);

Console.WriteLine($"Key: {response.APIKey}");

See our API reference for more info.

See the Example for more info.

Create Key

Creates an API key with the provided scopes.

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

var createOptions = new KeySchema()
{
    Comment = "My API Key",
    Scopes = new List<string> { "admin" },
};

var response = await manageClient.CreateKey(projectId, createOptions);

Console.WriteLine($"Created key: {response.APIKeyID}");

See our API reference for more info.

See the Example for more info.

Delete Key

Deletes a specific key associated with the provided project_id.

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

var response = await manageClient.DeleteKey(projectId, keyId);

Console.WriteLine($"Delete result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Members

Get Members

Retrieves account objects for all of the accounts in the specified project_id.

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

var response = await manageClient.GetMembers(projectId);

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

See our API reference for more info.

See the Example for more info.

Remove Member

Removes member account for specified member_id.

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

var response = await manageClient.RemoveMember(projectId, memberId);

Console.WriteLine($"Remove result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Scopes

Get Member Scopes

Retrieves scopes of the specified member in the specified project.

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

var response = await manageClient.GetMemberScopes(projectId, memberId);

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

See our API reference for more info.

See the Example for more info.

Update Scope

Updates the scope for the specified member in the specified project.

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

var updateOptions = new ScopeSchema()
{
    Scope = "admin",
};

var response = await manageClient.UpdateMemberScopes(projectId, memberId, updateOptions);

Console.WriteLine($"Update result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Invitations

List Invites

Retrieves all invitations associated with the provided project_id.

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

var response = await manageClient.GetInvitations(projectId);

Console.WriteLine($"Invitations: {response.Invites}");

See our API reference for more info.

See the Example for more info.

Send Invite

Sends an invitation to the provided email address.

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

var inviteOptions = new InvitationSchema()
{
    Email = "user@example.com",
    Scope = "admin",
};

var response = await manageClient.SendInvitation(projectId, inviteOptions);

Console.WriteLine($"Invitation sent: {response.Message}");

See our API reference for more info.

See the Example for more info.

Delete Invite

Removes the specified invitation from the project.

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

var response = await manageClient.DeleteInvitation(projectId, email);

Console.WriteLine($"Delete result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Leave Project

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

var response = await manageClient.LeaveProject(projectId);

Console.WriteLine($"Leave result: {response.Message}");

See our API reference for more info.

See the Example for more info.

Usage

Get All Requests

Retrieves all requests associated with the provided project_id based on the provided options.

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

var response = await manageClient.GetUsageRequests(projectId);

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

See our API reference for more info.

See the Example for more info.

Get Request

Retrieves a specific request associated with the provided project_id.

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

var response = await manageClient.GetUsageRequest(projectId, requestId);

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

See our API reference for more info.

See the Example for more info.

Get Fields

Lists the features, models, tags, languages, and processing method used for requests in the specified project.

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

var response = await manageClient.GetUsageFields(projectId);

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

See our API reference for more info.

See the Example for more info.

Summarize Usage

Deprecated Retrieves the usage for a specific project. Use Get Project Usage Breakdown for a more comprehensive usage summary.

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

var response = await manageClient.GetUsageSummary(projectId);

Console.WriteLine($"Usage summary: {response.Usage}");

See our API reference for more info.

See the Example for more info.

Billing

Get All Balances

Retrieves the list of balance info for the specified project.

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

var response = await manageClient.GetBalances(projectId);

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

See our API reference for more info.

See the Example for more info.

Get Balance

Retrieves the balance info for the specified project and balance_id.

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

var response = await manageClient.GetBalance(projectId, balanceId);

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

See our API reference for more info.

See the Example for more info.

Models

Get All Project Models

Retrieves all models available for a given project.

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

var response = await manageClient.GetProjectModels(projectId);

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

See our API reference for more info.

See the Example for more info.

Get Model

Retrieves details of a specific model.

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

var response = await manageClient.GetProjectModel(projectId, modelId);

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

See our API reference for more info.

See the Example for more info.

On-Prem APIs

List On-Prem credentials

Lists sets of distribution credentials for the specified project.

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

var response = await selfHostedClient.ListSelfhostedCredentials(projectId);

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

See our API reference for more info.

Get On-Prem credentials

Returns a set of distribution credentials for the specified project.

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

var response = await selfHostedClient.GetSelfhostedCredentials(projectId, distributionCredentialsId);

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

See our API reference for more info.

Create On-Prem credentials

Creates a set of distribution credentials for the specified project.

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

var createOptions = new SelfhostedCredentialsSchema()
{
    Comment = "My on-prem credentials",
};

var response = await selfHostedClient.CreateSelfhostedCredentials(projectId, createOptions);

Console.WriteLine($"Created credentials: {response.CredentialsID}");

See our API reference for more info.

Delete On-Prem credentials

Deletes a set of distribution credentials for the specified project.

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

var response = await selfHostedClient.DeleteSelfhostedCredentials(projectId, distributionCredentialId);

Console.WriteLine($"Delete result: {response.Message}");

See our API reference for more info.

Logging

This SDK uses Serilog to perform all of its logging tasks. By default, this SDK will enable Information level messages and higher (ie Warning, Error, etc.) when you initialize the library as follows:

// Default logging level is "Information"
Library.Initialize();

To increase the logging output/verbosity for debug or troubleshooting purposes, you can set the Debug level but using this code:

Library.Initialize(LogLevel.Debug);

Testing

Unit Tests

Run:

   dotnet test Deepgram.Tests/Deepgram.Tests.csproj

Integration Tests

See the tests directory for integration tests and edge case validation beyond the unit tests.

Examples

See the examples directory for working code samples for different Deepgram SDK features.

Backwards Compatibility

We follow semantic versioning (semver) to ensure a smooth upgrade experience. Within a major version (like 6.*), we will maintain backward compatibility so your code will continue to work without breaking changes. When we release a new major version (like moving from 5.* to 6.*), we may introduce breaking changes to improve the SDK. We'll always document these changes clearly in our release notes to help you upgrade smoothly.

Older SDK versions will receive Priority 1 (P1) bug support only. Security issues, both in our code and dependencies, are promptly addressed. Significant bugs without clear workarounds are also given priority attention.

Development and Contributing

Interested in contributing? We ❤️ pull requests!

To make sure our community is safe for all, be sure to review and agree to our Code of Conduct. Then see the Contribution guidelines for more information.

Getting Help

We love to hear from you, so if you have questions, comments or find a bug in the project, please let us know! You can either:

Name		Name	Last commit message	Last commit date
Latest commit History 585 Commits
.devcontainer		.devcontainer
.github		.github
Deepgram.Microphone		Deepgram.Microphone
Deepgram.Tests		Deepgram.Tests
Deepgram		Deepgram
examples		examples
extras		extras
tests		tests

License

deepgram/deepgram-dotnet-sdk

Folders and files

Latest commit

History