ElevenLabs - What is Netra? | Technical documentation

ElevenLabs provides high-quality text-to-speech synthesis with natural-sounding voices and support for multiple languages. Netra helps you track voice synthesis operations, monitor audio generation metrics, and analyze usage patterns.

Installation

pip install elevenlabs netra-sdk

npm install elevenlabs netra-sdk

Usage

Initialize Netra before using ElevenLabs:

import os
from netra import Netra

Netra.init(
    app_name="elevenlabs-tts-service",
    headers=f"x-api-key={os.environ.get('NETRA_API_KEY')}"
)

import Netra from 'netra-sdk';

await Netra.init({
  appName: 'elevenlabs-tts-service',
  headers: `x-api-key=${process.env.NETRA_API_KEY}`
});

Examples

Automatic Tracing with Decorators

Track ElevenLabs operations automatically using Netra decorators:

from elevenlabs import ElevenLabs
from netra.decorators import task
import os

client = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))

@task()
def synthesize_speech(text: str, voice_id: str) -> bytes:
    """Generate speech from text using ElevenLabs."""
    audio = client.text_to_speech.convert(
        voice_id=voice_id,
        text=text,
        model_id="eleven_turbo_v2",
        voice_settings={
            "stability": 0.5,
            "similarity_boost": 0.75
        }
    )
    
    # Collect audio chunks
    audio_bytes = b""
    for chunk in audio:
        audio_bytes += chunk
    
    return audio_bytes

@task()
def synthesize_with_emotions(text: str, voice_id: str, emotion: str) -> bytes:
    """Generate emotional speech using advanced models."""
    audio = client.text_to_speech.convert(
        voice_id=voice_id,
        text=text,
        model_id="eleven_turbo_v2_5",
        voice_settings={
            "stability": 0.6,
            "similarity_boost": 0.8,
            "style": 0.5,
            "use_speaker_boost": True
        }
    )
    
    audio_bytes = b""
    for chunk in audio:
        audio_bytes += chunk
    
    return audio_bytes

# Usage
audio_data = synthesize_speech(
    "Hello, this is a test of ElevenLabs speech synthesis.",
    "pNInz6obpgDQGcFmaJgB"
)

import { ElevenLabsClient } from 'elevenlabs';
import { task } from 'netra-sdk';

const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });

class TTSService {
  @task()
  async synthesizeSpeech(text: string, voiceId: string): Promise<Buffer> {
    const audio = await client.textToSpeech.convert(voiceId, {
      text,
      model_id: 'eleven_turbo_v2',
      voice_settings: {
        stability: 0.5,
        similarity_boost: 0.75
      }
    });

    const chunks: Buffer[] = [];
    for await (const chunk of audio) {
      chunks.push(chunk);
    }
    
    return Buffer.concat(chunks);
  }

  @task()
  async synthesizeWithEmotions(
    text: string,
    voiceId: string,
    emotion: string
  ): Promise<Buffer> {
    const audio = await client.textToSpeech.convert(voiceId, {
      text,
      model_id: 'eleven_turbo_v2_5',
      voice_settings: {
        stability: 0.6,
        similarity_boost: 0.8,
        style: 0.5,
        use_speaker_boost: true
      }
    });

    const chunks: Buffer[] = [];
    for await (const chunk of audio) {
      chunks.push(chunk);
    }
    
    return Buffer.concat(chunks);
  }
}

// Usage
const service = new TTSService();
await service.synthesizeSpeech(
  'Hello, this is a test of ElevenLabs speech synthesis.',
  'pNInz6obpgDQGcFmaJgB'
);

Manual Span Creation with Action Tracking

For detailed control over tracing and action tracking:

from elevenlabs import ElevenLabs
from netra import SpanWrapper, ActionModel, UsageModel
import os
import time

client = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))

def synthesize_with_tracking(text: str, voice_id: str) -> bytes:
    """Generate speech with detailed tracking."""
    span = SpanWrapper("elevenlabs-synthesis")
    span.start()
    
    try:
        start_time = time.time_ns()
        span.set_attribute("voice_id", voice_id)
        span.set_attribute("text_length", len(text))
        span.set_attribute("model", "eleven_turbo_v2")
        
        audio = client.text_to_speech.convert(
            voice_id=voice_id,
            text=text,
            model_id="eleven_turbo_v2",
            voice_settings={
                "stability": 0.5,
                "similarity_boost": 0.75
            }
        )
        
        # Collect audio chunks
        audio_bytes = b""
        for chunk in audio:
            audio_bytes += chunk
        
        end_time = time.time_ns()
        duration_ms = (end_time - start_time) / 1_000_000
        
        # Track the TTS API operation
        action = ActionModel(
            start_time=str(start_time),
            action="API",
            action_type="TTS_SYNTHESIS",
            metadata={
                "provider": "elevenlabs",
                "voice_id": voice_id,
                "model": "eleven_turbo_v2",
                "text_length": str(len(text)),
                "audio_size_bytes": str(len(audio_bytes)),
                "duration_ms": str(duration_ms)
            },
            success=True
        )
        span.set_action([action])
        
        # Track usage
        usage = UsageModel(
            model="eleven_turbo_v2",
            usage_type="characters",
            units_used=len(text),
            cost_in_usd=len(text) * 0.00003  # $0.30 per 1000 characters
        )
        span.set_usage([usage])
        
        span.set_status({"code": 1, "message": "Success"})
        span.end()
        
        return audio_bytes
        
    except Exception as e:
        span.set_error(e)
        span.set_status({"code": 2, "message": "Error"})
        span.end()
        raise

# Usage
audio_data = synthesize_with_tracking(
    "This is tracked speech synthesis with detailed metrics.",
    "pNInz6obpgDQGcFmaJgB"
)

import { ElevenLabsClient } from 'elevenlabs';
import { SpanWrapper, ActionModel } from 'netra-sdk';

const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });

async function synthesizeWithTracking(text: string, voiceId: string): Promise<Buffer> {
  const span = new SpanWrapper('elevenlabs-synthesis');
  span.start();

  try {
    const startTime = Date.now();
    span.setAttribute('voice_id', voiceId);
    span.setAttribute('text_length', text.length);
    span.setAttribute('model', 'eleven_turbo_v2');

    const audio = await client.textToSpeech.convert(voiceId, {
      text,
      model_id: 'eleven_turbo_v2',
      voice_settings: { stability: 0.5, similarity_boost: 0.75 }
    });

    const chunks: Buffer[] = [];
    for await (const chunk of audio) {
      chunks.push(chunk);
    }
    
    const audioBuffer = Buffer.concat(chunks);
    const duration = Date.now() - startTime;

    // Track the TTS API operation
    const action: ActionModel = {
      start_time: (startTime * 1000000).toString(),
      action: 'API',
      action_type: 'TTS_SYNTHESIS',
      metadata: {
        provider: 'elevenlabs',
        voice_id: voiceId,
        model: 'eleven_turbo_v2',
        text_length: text.length.toString(),
        audio_size_bytes: audioBuffer.length.toString(),
        duration_ms: duration.toString()
      },
      success: true
    };
    span.setAction([action]);

    span.setUsage({
      model: 'eleven_turbo_v2',
      usage_type: 'characters',
      units_used: text.length,
      cost_in_usd: text.length * 0.00003
    });

    span.setStatus({ code: 1, message: 'Success' });
    span.end();

    return audioBuffer;
  } catch (error) {
    span.setError(error as Error);
    span.setStatus({ code: 2, message: 'Error' });
    span.end();
    throw error;
  }
}

// Usage
await synthesizeWithTracking(
  'This is tracked speech synthesis with detailed metrics.',
  'pNInz6obpgDQGcFmaJgB'
);

from elevenlabs import ElevenLabs
from netra import SpanWrapper, ActionModel, UsageModel
import os
import time

client = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))

def synthesize_with_tracking(text: str, voice_id: str) -> bytes:
    """Generate speech with detailed tracking."""
    span = SpanWrapper("elevenlabs-synthesis")
    span.start()
    
    try:
        start_time = time.time_ns()
        span.set_attribute("voice_id", voice_id)
        span.set_attribute("text_length", len(text))
        span.set_attribute("model", "eleven_turbo_v2")
        
        audio = client.text_to_speech.convert(
            voice_id=voice_id,
            text=text,
            model_id="eleven_turbo_v2",
            voice_settings={
                "stability": 0.5,
                "similarity_boost": 0.75
            }
        )
        
        # Collect audio chunks
        audio_bytes = b""
        for chunk in audio:
            audio_bytes += chunk
        
        end_time = time.time_ns()
        duration_ms = (end_time - start_time) / 1_000_000
        
        # Track the TTS API operation
        action = ActionModel(
            start_time=str(start_time),
            action="API",
            action_type="TTS_SYNTHESIS",
            metadata={
                "provider": "elevenlabs",
                "voice_id": voice_id,
                "model": "eleven_turbo_v2",
                "text_length": str(len(text)),
                "audio_size_bytes": str(len(audio_bytes)),
                "duration_ms": str(duration_ms)
            },
            success=True
        )
        span.set_action([action])
        
        # Track usage
        usage = UsageModel(
            model="eleven_turbo_v2",
            usage_type="characters",
            units_used=len(text),
            cost_in_usd=len(text) * 0.00003  # $0.30 per 1000 characters
        )
        span.set_usage([usage])
        
        span.set_status({"code": 1, "message": "Success"})
        span.end()
        
        return audio_bytes
        
    except Exception as e:
        span.set_error(e)
        span.set_status({"code": 2, "message": "Error"})
        span.end()
        raise

# Usage
audio_data = synthesize_with_tracking(
    "This is tracked speech synthesis with detailed metrics.",
    "pNInz6obpgDQGcFmaJgB"
)

Next Steps

Netra Documentation - Learn more about Netra’s observability features
ElevenLabs API - Explore ElevenLabs text-to-speech capabilities

​Installation

​Usage

​Examples

​Automatic Tracing with Decorators

​Manual Span Creation with Action Tracking

​Next Steps