v0.4.0¶

Release Date: December 31, 2025

Bug fixes, improved testing infrastructure, and new utilities for voice settings and audio conversion.

Highlights¶

This release fixes JSON decoding errors when the ElevenLabs API returns null for nullable fields, adds integration tests to catch similar issues in the future, and introduces voice settings presets for different platforms.

Bug Fixes¶

Fixed: Null Handling in API Responses¶

Fixed JSON decoding errors when the API returns null for nullable $ref fields. This affected multiple endpoints including:

/v1/voices - manual_verification, settings, sharing fields
/v1/models - various nullable fields
/v1/user - subscription-related fields
/v1/history - history item fields
And 205+ other nullable fields across the API

Before (error):

decode response: decode GetVoicesResponseModel: callback: decode field "voices":
callback: decode VoiceResponseModel: callback: decode field "fine_tuning":
decode FineTuningResponseModel: callback: decode field "manual_verification":
decode ManualVerificationResponseModel: "{" expected: unexpected byte 110 'n'

After: Works correctly, null values are handled gracefully.

Root Cause¶

This was caused by ogen-go/ogen#1358 where ogen generates Opt* types instead of OptNil* types for nullable $ref fields in OpenAPI specs.

Solution¶

We created ogen-tools, a post-processing tool that fixes the generated code:

# After ogen generation
go run github.com/agentplexus/ogen-tools/cmd/ogen-fixnull@latest internal/api/oas_json_gen.go
go run github.com/agentplexus/ogen-tools/cmd/ogen-fixerror@latest internal/api/oas_response_decoders_gen.go

This is now integrated into the SDK's generate.sh script.

New Features¶

Voice Settings Presets¶

Added pre-configured voice settings for different platforms and use cases:

// Educational platforms
settings := elevenlabs.VoiceSettingsForUdemy()     // Neutral, clear, consistent
settings := elevenlabs.VoiceSettingsForCoursera()  // Slightly expressive, engaging
settings := elevenlabs.VoiceSettingsForEdX()       // Very stable, highly intelligible

// Social media
settings := elevenlabs.VoiceSettingsForInstagram() // Energetic, polished
settings := elevenlabs.VoiceSettingsForTikTok()    // High energy, attention-grabbing
settings := elevenlabs.VoiceSettingsForYouTube()   // Engaging, sustainable for 5-20 min

// Long-form audio
settings := elevenlabs.VoiceSettingsForPodcast()   // Conversational, natural
settings := elevenlabs.VoiceSettingsForAudiobook() // Consistent, easy to listen to

See Voice Settings Presets for details on each preset.

Audio Conversion Utilities¶

New utilities for working with PCM audio output:

// Generate PCM audio
resp, _ := client.TextToSpeech().Generate(ctx, &elevenlabs.TTSRequest{
    VoiceID:      voiceID,
    Text:         "Hello",
    OutputFormat: "pcm_44100",
})

// Convert PCM to WAV
wavData, _ := elevenlabs.PCMToWAV(resp.Audio, 44100)

// Or convert from bytes
wavData, _ := elevenlabs.PCMBytesToWAV(pcmBytes, 44100)

// Parse sample rate from format string
sampleRate, _ := elevenlabs.ParsePCMSampleRate("pcm_44100") // returns 44100

Enhanced Error Handling¶

New ParseAPIError() function to extract detailed error information from API errors:

resp, err := client.TextToSpeech().Generate(ctx, req)
if err != nil {
    if apiErr := elevenlabs.ParseAPIError(err); apiErr != nil {
        fmt.Printf("Status: %d, Message: %s\n", apiErr.StatusCode, apiErr.Message)
    }
    log.Fatal(err)
}

New helper function:

IsForbiddenError(err) - Returns true if the error is a 403 Forbidden error

Output Format Validation¶

TTS requests now validate output formats. Available formats:

Category	Formats
MP3	`mp3_22050_32`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128` (default), `mp3_44100_192`
PCM	`pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_32000`, `pcm_44100`, `pcm_48000`
Opus	`opus_48000_32`, `opus_48000_64`, `opus_48000_96`, `opus_48000_128`, `opus_48000_192`
Telephony	`ulaw_8000`, `alaw_8000`

Testing Infrastructure¶

Integration Tests¶

Added integration tests that run against the real ElevenLabs API to catch null handling and other issues:

ELEVENLABS_API_KEY=your_key go test -v -tags=integration ./...

Tests added:

Test	Endpoint	Purpose
`TestVoicesListNullHandling`	`/v1/voices`	Verifies nullable fields in voice responses
`TestModelsListNullHandling`	`/v1/models`	Verifies nullable fields in model responses
`TestUserGetNullHandling`	`/v1/user`	Verifies nullable fields in user/subscription
`TestHistoryListNullHandling`	`/v1/history`	Verifies nullable fields in history items

See Testing Documentation for details.

Developer Experience¶

Updated Code Generation¶

The generate.sh script now includes automatic post-processing:

#!/bin/bash
# generate.sh workflow:
# 1. Convert OpenAPI 3.1 → 3.0.3 (ogen compatibility)
# 2. Run ogen to generate Go code
# 3. Post-process: Fix null handling (ogen-fixnull)
# 4. Post-process: Fix error body preservation (ogen-fixerror)
# 5. go mod tidy
# 6. Verify build

New Files¶

File	Purpose
`audio.go`	PCM to WAV conversion utilities
`audio_test.go`	Unit tests for audio utilities
`voicesettings.go`	Platform-specific voice presets
`integration_test.go`	Real API integration tests

Documentation¶

New: Testing documentation (docsrc/contributing/testing.md)
New: Voice settings presets guide (docsrc/utilities/voicesettings.md)
Updated: MkDocs navigation with new sections

Installation¶

go get github.com/agentplexus/go-elevenlabs@v0.4.0

Upgrade Notes¶

This release is backward compatible. The null handling fix resolves errors that previously caused API calls to fail, so existing code should work better without changes.

If you were working around null handling errors with custom code, you can remove those workarounds.

Dependencies¶

Added: github.com/agentplexus/ogen-tools/ogenerror - For parsing ogen error details