SDK

Rust SDK

High-performance Rust client library for Nur's Voice AI platform. Zero-cost abstractions with async/await support.

Installation

Requires Rust 1.70 or higher. Add to your Cargo.toml:

[dependencies]
nur-ai = "0.1.0"
tokio = { version = "1", features = ["full"] }

Quick Start

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

use nur_ai::{Client, TTSRequest};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client (uses NUR_API_KEY env var)
    let client = Client::new()?;
    // Generate speech from text
    let audio = client.tts()
        .generate(TTSRequest {
            text: "Hello from Rust! This is Nur's voice AI.".to_string(),
            voice_id: "rachel_v2".to_string(),
            language: Some("en".to_string()),
            ..Default::default()
        })
        .await?;
    // Save to file
    audio.save("output.mp3").await?;
    println!("Generated {:.2}s of audio", audio.duration());
    Ok(())
}

Authentication

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

use nur_ai::{Client, Config};
use std::time::Duration;
// Option 1: Use environment variable
let client = Client::new()?;
// Option 2: Explicit API key
let client = Client::with_api_key("nur_your_api_key_here")?;
// Option 3: Custom configuration
let config = Config::builder()
    .api_key("nur_your_api_key_here")
    .base_url("https://api.nur.ai")
    .timeout(Duration::from_secs(60))
    .max_retries(3)
    .build()?;
let client = Client::with_config(config);

Text to Speech

Generate natural-sounding speech with full type safety:

use nur_ai::{TTSRequest, OutputFormat};
// Basic generation
let audio = client.tts()
    .generate(TTSRequest {
        text: "Converting text to natural speech.".to_string(),
        voice_id: "rachel_v2".to_string(),
        ..Default::default()
    })
    .await?;
// With advanced options
let audio = client.tts()
    .generate(TTSRequest {
        text: "Converting text to natural speech.".to_string(),
        voice_id: "rachel_v2".to_string(),
        language: Some("en".to_string()),
        speed: Some(1.0),
        pitch: Some(1.0),
        output_format: Some(OutputFormat::Mp3),
        sample_rate: Some(24000),
        enable_ssml: Some(true),
    })
    .await?;
// Save audio
audio.save("output.mp3").await?;
// Get audio bytes
let bytes = audio.as_bytes();
// Streaming generation
let mut stream = client.tts()
    .stream(TTSRequest {
        text: "Streaming long-form content...".to_string(),
        voice_id: "rachel_v2".to_string(),
        ..Default::default()
    })
    .await?;
while let Some(chunk) = stream.next().await {
    let chunk = chunk?;
    println!("Received {} bytes", chunk.len());
    // Process chunk
}

Speech to Text

High-accuracy transcription with speaker diarization:

use nur_ai::STTRequest;
use tokio::fs::File;
// Basic transcription
let transcript = client.stt()
    .transcribe(STTRequest {
        file: "audio.mp3".to_string(),
        ..Default::default()
    })
    .await?;
println!("{}", transcript.text);
// With speaker diarization and timestamps
let transcript = client.stt()
    .transcribe(STTRequest {
        file: "meeting.mp3".to_string(),
        language: Some("en".to_string()),
        speaker_diarization: Some(true),
        timestamps: Some(true),
        punctuation_enabled: Some(true),
        filter_profanity: Some(true),
    })
    .await?;
// Access segments with speaker info
for segment in &transcript.segments {
    println!(
        "[Speaker {}] {}",
        segment.speaker,
        segment.text
    );
    println!("  Time: {:.2}s - {:.2}s", segment.start, segment.end);
}
// Real-time streaming transcription
let mut stream = client.stt()
    .stream_transcribe(Default::default())
    .await?;
// Send audio chunks in background task
tokio::spawn(async move {
    let mut file = File::open("audio.mp3").await.unwrap();
    let mut buffer = vec![0u8; 4096];
    loop {
        let n = file.read(&mut buffer).await.unwrap();
        if n == 0 { break; }
        stream.send(&buffer[..n]).await.unwrap();
    }
    stream.finish().await.unwrap();
});
// Receive transcripts
while let Some(result) = stream.next().await {
    let result = result?;
    println!(
        "Transcription: {} (final: {})",
        result.text,
        result.is_final
    );
}

Voice Agents

Build real-time conversational AI with bidirectional streaming:

use nur_ai::{VoiceAgentConfig, ResponseType};
use tokio::sync::mpsc;
// Create a voice agent session
let session = client.voice_agent()
    .create_session(VoiceAgentConfig {
        voice_id: "rachel_v2".to_string(),
        language: "en".to_string(),
        system_prompt: "You are a helpful assistant.".to_string(),
        temperature: 0.7,
        max_tokens: 150,
        ..Default::default()
    })
    .await?;
let (tx, mut rx) = mpsc::channel(100);
// Send audio from microphone in background task
tokio::spawn(async move {
    while let Some(audio_chunk) = microphone_stream.next().await {
        if let Err(e) = session.send_audio(audio_chunk).await {
            eprintln!("Error sending audio: {}", e);
            break;
        }
    }
});
// Receive agent responses
while let Some(response) = session.receive().await? {
    match response.response_type {
        ResponseType::Transcript => {
            println!("User: {}", response.transcript.unwrap().text);
        }
        ResponseType::AgentText => {
            println!("Agent: {}", response.agent_text.unwrap());
        }
        ResponseType::Audio => {
            // Play audio chunk
            play_audio(&response.audio.unwrap());
        }
    }
}

Configuration Options

All available client configuration options:

Method	Type	Default	Description
api_key()	String	NUR_API_KEY	Your API key
base_url()	&str	https://api.nur.ai	API base URL
timeout()	Duration	30s	Request timeout
max_retries()	u32	3	Maximum retry attempts
retry_delay()	Duration	1s	Delay between retries
user_agent()	&str	nur-rust/0.1.0	HTTP user agent

Error Handling

The SDK provides a comprehensive error type with pattern matching:

use nur_ai::{Error, ErrorKind};
let result = client.tts()
    .generate(TTSRequest {
        text: "Hello world".to_string(),
        voice_id: "rachel_v2".to_string(),
        ..Default::default()
    })
    .await;
match result {
    Ok(audio) => {
        println!("Success!");
    }
    Err(e) => match e.kind() {
        ErrorKind::RateLimit { retry_after } => {
            println!("Rate limited. Retry after {} seconds", retry_after);
            tokio::time::sleep(Duration::from_secs(*retry_after)).await;
            // Retry request...
        }
        ErrorKind::Authentication => {
            eprintln!("Authentication failed: check your API key");
        }
        ErrorKind::Api { status_code, message } => {
            eprintln!("API error [{}]: {}", status_code, message);
        }
        ErrorKind::Network => {
            eprintln!("Network error: {}", e);
        }
        ErrorKind::Timeout => {
            eprintln!("Request timed out");
        }
        _ => {
            eprintln!("Unexpected error: {}", e);
        }
    }
}
// Using the ? operator with custom error types
async fn process_audio() -> Result<(), Box<dyn std::error::Error>> {
    let audio = client.tts()
        .generate(TTSRequest {
            text: "Hello".to_string(),
            voice_id: "rachel_v2".to_string(),
            ..Default::default()
        })
        .await?;
    audio.save("output.mp3").await?;
    Ok(())
}