SDK

C# SDK

Official .NET client library for Nur's Voice AI platform. Supports .NET 6.0+ with full async/await patterns.

Installation

Requires .NET 6.0 or higher. Install via NuGet Package Manager:

1dotnet add package Nur.AI

Quick Start

Create a client and generate your first speech using async/await:

using Nur.AI;
// Initialize client (uses NUR_API_KEY env var)
var client = new NurClient();
// Generate speech from text
var audio = await client.TTS.GenerateAsync(new TTSRequest
{
    Text = "Hello from C#! This is Nur's voice AI.",
    VoiceId = "rachel_v2",
    Language = "en"
});
// Save to file
await audio.SaveAsync("output.mp3");
Console.WriteLine($"Generated {audio.Duration:F2}s of audio");

Authentication

The SDK automatically reads your API key from the NUR_API_KEY environment variable. You can also configure it explicitly:

using Nur.AI;
// Option 1: Use environment variable
var client = new NurClient();
// Option 2: Explicit API key
var client = new NurClient("nur_your_api_key_here");
// Option 3: Custom configuration
var options = new NurClientOptions
{
    ApiKey = "nur_your_api_key_here",
    BaseUrl = "https://api.nur.ai",
    Timeout = TimeSpan.FromSeconds(60),
    MaxRetries = 3
};
var client = new NurClient(options);

Text to Speech

Generate natural-sounding speech with full type safety and IntelliSense:

// Basic generation
var audio = await client.TTS.GenerateAsync(new TTSRequest
{
    Text = "Converting text to natural speech.",
    VoiceId = "rachel_v2"
});
// With advanced options
var audio = await client.TTS.GenerateAsync(new TTSRequest
{
    Text = "Converting text to natural speech.",
    VoiceId = "rachel_v2",
    Language = "en",
    Speed = 1.0f,
    Pitch = 1.0f,
    OutputFormat = OutputFormat.Mp3,
    SampleRate = 24000,
    EnableSSML = true
});
// Save audio
await audio.SaveAsync("output.mp3");
// Get audio bytes
byte[] bytes = audio.ToBytes();
// Streaming generation
await foreach (var chunk in client.TTS.StreamAsync(new TTSRequest
{
    Text = "Streaming long-form content...",
    VoiceId = "rachel_v2"
}))
{
    Console.WriteLine($"Received {chunk.Length} bytes");
    // Process chunk
}

Speech to Text

High-accuracy transcription with speaker diarization:

// Basic transcription
var transcript = await client.STT.TranscribeAsync(new STTRequest
{
    File = "audio.mp3"
});
Console.WriteLine(transcript.Text);
// With speaker diarization and timestamps
var transcript = await client.STT.TranscribeAsync(new STTRequest
{
    File = "meeting.mp3",
    Language = "en",
    SpeakerDiarization = true,
    Timestamps = true,
    PunctuationEnabled = true,
    FilterProfanity = true
});
// Access segments with speaker info
foreach (var segment in transcript.Segments)
{
    Console.WriteLine($"[Speaker {segment.Speaker}] {segment.Text}");
    Console.WriteLine($"  Time: {segment.Start:F2}s - {segment.End:F2}s");
}
// Real-time streaming transcription
var stream = await client.STT.StreamTranscribeAsync(new StreamSTTRequest
{
    Language = "en",
    Timestamps = true
});
// Send audio chunks in background task
_ = Task.Run(async () =>
{
    using var fileStream = File.OpenRead("audio.mp3");
    var buffer = new byte[4096];
    int bytesRead;
    while ((bytesRead = await fileStream.ReadAsync(buffer)) > 0)
    {
        await stream.SendAsync(buffer.AsMemory(0, bytesRead));
    }
    await stream.CompleteAsync();
});
// Receive transcripts
await foreach (var result in stream.ReceiveAsync())
{
    Console.WriteLine($"Transcription: {result.Text} (final: {result.IsFinal})");
}

Voice Agents

Build real-time conversational AI with bidirectional streaming:

// Create a voice agent session
var session = await client.VoiceAgent.CreateSessionAsync(new VoiceAgentConfig
{
    VoiceId = "rachel_v2",
    Language = "en",
    SystemPrompt = "You are a helpful assistant.",
    Temperature = 0.7f,
    MaxTokens = 150
});
// Send audio from microphone in background task
_ = Task.Run(async () =>
{
    await foreach (var audioChunk in microphoneStream)
    {
        await session.SendAudioAsync(audioChunk);
    }
});
// Receive agent responses
await foreach (var response in session.ReceiveAsync())
{
    switch (response.Type)
    {
        case ResponseType.Transcript:
            Console.WriteLine($"User: {response.Transcript.Text}");
            break;
        case ResponseType.AgentText:
            Console.WriteLine($"Agent: {response.AgentText}");
            break;
        case ResponseType.Audio:
            // Play audio chunk
            PlayAudio(response.Audio);
            break;
    }
}

Configuration Options

All available client configuration options:

Property	Type	Default	Description
ApiKey	string	NUR_API_KEY	Your API key
BaseUrl	string	https://api.nur.ai	API base URL
Timeout	TimeSpan	30s	Request timeout
MaxRetries	int	3	Maximum retry attempts
RetryDelay	TimeSpan	1s	Delay between retries
HttpClient	HttpClient	Default	Custom HTTP client

Error Handling

The SDK provides typed exceptions for different failure scenarios:

using Nur.AI.Exceptions;
try
{
    var audio = await client.TTS.GenerateAsync(new TTSRequest
    {
        Text = "Hello world",
        VoiceId = "rachel_v2"
    });
}
catch (RateLimitException ex)
{
    Console.WriteLine($"Rate limited. Retry after {ex.RetryAfter} seconds");
    await Task.Delay(TimeSpan.FromSeconds(ex.RetryAfter));
    // Retry request...
}
catch (AuthenticationException ex)
{
    Console.WriteLine("Authentication failed: check your API key");
}
catch (NurApiException ex)
{
    Console.WriteLine($"API error [{ex.StatusCode}]: {ex.Message}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}
// Using cancellation tokens
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
try
{
    var audio = await client.TTS.GenerateAsync(
        new TTSRequest { Text = "Long text..." },
        cts.Token
    );
}
catch (OperationCanceledException)
{
    Console.WriteLine("Request timed out or was cancelled");
}