SDK

Go SDK

Official Go client library for Nur's Voice AI platform. Build production-ready voice applications with idiomatic Go.

Installation

Requires Go 1.21 or higher. Install using go get:

1go get github.com/nur-ai/nur-go

Quick Start

Create a client and generate your first speech in seconds:

package main
import (
    "context"
    "fmt"
    "log"
    nur "github.com/nur-ai/nur-go"
)
func main() {
    // Initialize client (uses NUR_API_KEY env var)
    client := nur.NewClient()
    // Generate speech from text
    audio, err := client.TTS.Generate(context.Background(), &nur.TTSRequest{
        Text:     "Hello from Go! This is Nur's voice AI.",
        VoiceID:  "rachel_v2",
        Language: "en",
    })
    if err != nil {
        log.Fatal(err)
    }
    // Save to file
    if err := audio.Save("output.mp3"); err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Generated %.2fs of audio\n", audio.Duration)
}

Authentication

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

package main
import nur "github.com/nur-ai/nur-go"
func main() {
    // Option 1: Use environment variable
    client := nur.NewClient()
    // Option 2: Explicit API key
    client := nur.NewClient(nur.WithAPIKey("nur_your_api_key_here"))
    // Option 3: Custom configuration
    client := nur.NewClient(
        nur.WithAPIKey("nur_your_api_key_here"),
        nur.WithBaseURL("https://api.nur.ai"),
        nur.WithTimeout(60 * time.Second),
        nur.WithMaxRetries(3),
    )
}

Text to Speech

Generate natural-sounding speech from text with customizable voices and settings:

// Basic generation
audio, err := client.TTS.Generate(ctx, &nur.TTSRequest{
    Text:    "Converting text to natural speech.",
    VoiceID: "rachel_v2",
})
// With advanced options
audio, err := client.TTS.Generate(ctx, &nur.TTSRequest{
    Text:           "Converting text to natural speech.",
    VoiceID:        "rachel_v2",
    Language:       "en",
    Speed:          1.0,
    Pitch:          1.0,
    OutputFormat:   "mp3",
    SampleRate:     24000,
    EnableSSML:     true,
})
// Save audio
err = audio.Save("output.mp3")
// Get audio bytes
bytes := audio.Bytes()
// Streaming generation
stream, err := client.TTS.Stream(ctx, &nur.TTSRequest{
    Text:    "Streaming long-form content...",
    VoiceID: "rachel_v2",
})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
for {
    chunk, err := stream.Next()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatal(err)
    }
    // Process chunk
    fmt.Printf("Received %d bytes\n", len(chunk))
}

Speech to Text

Transcribe audio files with high accuracy and optional speaker diarization:

// Basic transcription
transcript, err := client.STT.Transcribe(ctx, &nur.STTRequest{
    File: "audio.mp3",
})
fmt.Println(transcript.Text)
// With speaker diarization and timestamps
transcript, err := client.STT.Transcribe(ctx, &nur.STTRequest{
    File:                "meeting.mp3",
    Language:            "en",
    SpeakerDiarization:  true,
    Timestamps:          true,
    PunctuationEnabled:  true,
    FilterProfanity:     true,
})
// Access segments with speaker info
for _, segment := range transcript.Segments {
    fmt.Printf("[Speaker %s] %s\n", segment.Speaker, segment.Text)
    fmt.Printf("  Time: %.2fs - %.2fs\n", segment.Start, segment.End)
}
// Real-time streaming transcription
stream, err := client.STT.StreamTranscribe(ctx, &nur.StreamSTTRequest{
    Language:   "en",
    Timestamps: true,
})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
// Send audio chunks
go func() {
    for audioChunk := range audioSource {
        if err := stream.Send(audioChunk); err != nil {
            log.Fatal(err)
        }
    }
    stream.CloseSend()
}()
// Receive transcripts
for {
    result, err := stream.Recv()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Transcription: %s (final: %v)\n", result.Text, result.IsFinal)
}

Voice Agents

Build real-time conversational AI agents with bidirectional streaming:

// Create a voice agent session
session, err := client.VoiceAgent.CreateSession(ctx, &nur.VoiceAgentConfig{
    VoiceID:        "rachel_v2",
    Language:       "en",
    SystemPrompt:   "You are a helpful assistant.",
    Temperature:    0.7,
    MaxTokens:      150,
})
if err != nil {
    log.Fatal(err)
}
defer session.Close()
// Handle bidirectional streaming
errChan := make(chan error)
// Send audio from microphone
go func() {
    for audioChunk := range microphoneStream {
        if err := session.SendAudio(audioChunk); err != nil {
            errChan <- err
            return
        }
    }
}()
// Receive agent responses
go func() {
    for {
        response, err := session.Receive()
        if err == io.EOF {
            break
        }
        if err != nil {
            errChan <- err
            return
        }
        // Handle different response types
        switch response.Type {
        case nur.ResponseTypeTranscript:
            fmt.Printf("User: %s\n", response.Transcript.Text)
        case nur.ResponseTypeAgentText:
            fmt.Printf("Agent: %s\n", response.AgentText)
        case nur.ResponseTypeAudio:
            // Play audio chunk
            playAudio(response.Audio)
        }
    }
}()
// Wait for completion or error
select {
case err := <-errChan:
    log.Fatal(err)
case <-ctx.Done():
    fmt.Println("Session ended")
}

Configuration Options

All available client configuration options:

Option	Type	Default	Description
WithAPIKey	string	NUR_API_KEY	Your API key
WithBaseURL	string	https://api.nur.ai	API base URL
WithTimeout	time.Duration	30s	Request timeout
WithMaxRetries	int	3	Maximum retry attempts
WithRetryDelay	time.Duration	1s	Delay between retries
WithHTTPClient	*http.Client	http.DefaultClient	Custom HTTP client

Error Handling

The SDK provides typed errors for different failure scenarios:

import (
    "errors"
    nur "github.com/nur-ai/nur-go"
)
audio, err := client.TTS.Generate(ctx, &nur.TTSRequest{
    Text:    "Hello world",
    VoiceID: "rachel_v2",
})
if err != nil {
    var apiErr *nur.APIError
    var rateLimitErr *nur.RateLimitError
    var authErr *nur.AuthenticationError
    switch {
    case errors.As(err, &rateLimitErr):
        fmt.Printf("Rate limited. Retry after %d seconds\n", rateLimitErr.RetryAfter)
        time.Sleep(time.Duration(rateLimitErr.RetryAfter) * time.Second)
        // Retry request...
    case errors.As(err, &authErr):
        log.Fatal("Authentication failed: check your API key")
    case errors.As(err, &apiErr):
        fmt.Printf("API error [%d]: %s\n", apiErr.StatusCode, apiErr.Message)
    default:
        log.Fatal("Unexpected error:", err)
    }
}
// Context timeout handling
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
audio, err := client.TTS.Generate(ctx, &nur.TTSRequest{
    Text: "Long text...",
})
if errors.Is(err, context.DeadlineExceeded) {
    fmt.Println("Request timed out")
}