​
Installation

Install the React SDK using your preferred package manager:

npm install @outspeed/react

​
Prerequisites

Before using the React SDK, you’ll need:

  1. Outspeed API Key: Get your API key from the Outspeed Dashboard
  2. Backend Token Endpoint: A server endpoint to generate ephemeral keys for client authentication

​
Backend Setup

The React SDK requires a backend endpoint to generate ephemeral tokens for secure client authentication. Create a /token endpoint on your server:

// Add JSON middleware to parse request body
app.use(express.json());

app.post('/token', async (req, res) => {
  try {
    const { model } = req.body;
    
    // Validate the model
    if (model !== 'outspeed-v1') {
      return res.status(400).json({ 
        error: 'Invalid model. Only outspeed-v1 is supported.' 
      });
    }

    // Create session with Outspeed API
    const response = await fetch('https://api.outspeed.com/v1/realtime/sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OUTSPEED_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(req.body),
    });

    if (!response.ok) {
      const error = await response.text();
      console.error('Token generation error:', error);
      return res.status(response.status).json({ 
        error: 'Failed to generate token' 
      });
    }

    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('Token generation error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

​
Environment Variables

Add your Outspeed API key to your server’s environment variables:

OUTSPEED_API_KEY=your_outspeed_api_key_here

Never expose your Outspeed API key in client-side code. Always generate ephemeral tokens on your backend server.

​
Session Configuration

The React SDK uses a SessionConfig object to configure voice sessions:

import { type SessionConfig } from '@outspeed/client';

const sessionConfig: SessionConfig = {
  model: 'outspeed-v1',
  instructions: 'You are a helpful assistant.',
  voice: 'david', // Voice names must be lowercase. Find more voices at dashboard.outspeed.com
  turn_detection: {
    type: 'semantic_vad',
  },
  first_message: 'Hello! How can I help you today?', // Optional welcome message
};

​
Configuration Options

OptionTypeDescription
modelstringMust be "outspeed-v1"
instructionsstringSystem prompt for the AI assistant
voicestringVoice ID to use for speech synthesis
turn_detectionobjectVoice activity detection settings
first_messagestringOptional initial message from assistant

You can find available voices for outspeed-v1 at dashboard.outspeed.com

​
Next Steps

Now that you have the SDK installed and configured, you can start building voice AI applications: