Quickstart

Follow these steps to get started with Neuphonic:

1. Get Your API Key - Head over to our Playground to generate an API key.
2. Install an SDK - Install our Python SDK or JavaScript SDK.
3. Try an Example - Try out some simple examples.

Get Your API Key

Navigate to our Playground and create an account. Then, go to the API Keys section using the navigation bar on the left, and click "Generate New API Key".

warning

Save this API Key in a secure location. We do not store API keys, and you will not be able to view it again.

Install an SDK

Python SDK

We currently offer a Python SDK supporting Python versions 3.9 and above.

pip install pyneuphonic

To run the example program below, you must also install an additional dependency to enable audio playback through your machine's speakers.

pip install pyaudio

Next, store your API key in an environment variable. You can do this either at the project level using a .env file, or globally so that any project using pyneuphonic can access it.

macOS/Linux

# Set the environment variable globally, macOS / Linux
echo "export NEUPHONIC_API_KEY=<YOUR API KEY HERE>" >> ~/.zshrc
source ~/.zshrc

Windows

# Set the environment variable globally, example for Windows (Command Prompt)
setx NEUPHONIC_API_KEY "<YOUR API KEY HERE>"

Using .env file

# Set environment variable locally with a .env file
export NEUPHONIC_API_KEY=<YOUR API KEY HERE>

The example applications below assumes that the environment variable is set globally for simplicity. However, you can modify it to use a .env file and the python-dotenv package to load the environment variable.

Try an Example Application

Simple Text to Speech

Here is a demonstration of how to use our Server Side Events (SSE) endpoint to create audio for the phrase "Hello, world!". Feel free to modify the phrase to anything you like!

import os
from pyneuphonic import Neuphonic, TTSConfig
from pyneuphonic.player import AudioPlayer

# Load the API key from the environment
client = Neuphonic(api_key=os.environ.get('NEUPHONIC_API_KEY'))

sse = client.tts.SSEClient()

# TTSConfig is a pydantic model so check out the source code for all valid options
tts_config = TTSConfig(
    speed=1.05,
    lang_code='en', # replace the lang_code with the desired language code.
    voice_id='<VOICE_ID>'  # use client.voices.list() to view all available voices
)

# Create an audio player with `pyaudio`
with AudioPlayer() as player:
    response = sse.send('Hello, world!', tts_config=tts_config)
    player.play(response)

    player.save_audio('output.wav')  # save the audio to a .wav file

Agents (Chatbots)

Our Agents feature enables you to create personalized agents with custom prompts and interact with them. Here is an example of how to build a basic chatbot with a straightforward system prompt instructing it to respond in 10 words or fewer and greet the user with "Hi, how can I help you today?"

import os
import asyncio

# See AgentConfig model for full list of parameters to configure the agent
from pyneuphonic import Neuphonic, Agent, AgentConfig

async def main():
    # Load the API key from the environment
    client = Neuphonic(api_key=os.environ.get('NEUPHONIC_API_KEY'))

    agent_id = client.agents.create(
        name='Agent 1',
        prompt='You are a helpful agent. Answer in 10 words or less.',
        greeting='Hi, how can I help you today?'
    ).data['agent_id']

    # All additional keyword arguments (such as `agent_id` and `tts_model`) are passed as
    # parameters to the model. See AgentConfig model for full list of parameters.
    agent = Agent(client, agent_id=agent_id, tts_model='neu_hq')

    try:
        await agent.start()

        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        await agent.stop()

asyncio.run(main())

Running the example will have the chatbot greet you. You can reply by speaking, and your input will be processed by a speech recognition system. A GPT-4o LLM, combined with Neuphonic's text to speech engine will generate the response. Give it a go!

JavaScript SDK

We currently offer a JavaScript SDK supporting Node.js versions 18 and above.

npm install @neuphonic/neuphonic-js

Try an Example Application

For the examples below, ensure you have your NEUPHONIC_API_KEY environment variable set in your active environment (or a ".env" file). You can simply execute these scripts using ts-node or build and run them in a normal NodeJS environment.

Simple Text to Speech

Here is a demonstration of how to use our Server Side Events (SSE) endpoint to create audio for the phrase "Hello, world!". Feel free to modify the phrase to anything you like!

import { writeFileSync } from 'fs';
import { createClient, toWav } from '@neuphonic/neuphonic-js';
import * as dotenv from 'dotenv';

// Load environment variables from .env file
dotenv.config(); 

// Initialize Neuphonic client
const client = createClient({ apiKey: process.env.NEUPHONIC_API_KEY || '' });

// Text to synthesize
const msg = `Hello how are you?`;

// Create SSE TTS connection
const sse = await client.tts.sse({
  speed: 1.00,
  lang_code: 'en',
  voice_id: 'e564ba7e-aa8d-46a2-96a8-8dffedade48f', // choose a voice (client.voices.list() to view all)
});

// Send text and receive synthesized audio
const res = await sse.send(msg);

// Save audio to WAV buffer
const wavData = Buffer.from(toWav(res.audio));

// Write to output file
writeFileSync('output.wav', wavData);

Websocket Text to Speech

Here is a demonstration of how to use our WebSocket endpoint to create continuous audio for multiple phrases.

import * as dotenv from 'dotenv';
import * as fs from 'fs';
import * as path from 'path';
import { createClient, toWav } from '@neuphonic/neuphonic-js';

// Load environment variables from .env file
dotenv.config();

// Initialize Neuphonic client
const client = createClient({ apiKey: process.env.NEUPHONIC_API_KEY || '' });

// Establish a WebSocket TTS connection
const ws = await client.tts.websocket({
    speed: 1.00,
    lang_code: 'en'
});

let byteLen = 0;
const chunks: Uint8Array[] = [];

const msgs = [`Hello how are you?<STOP>`, `This is a test of the Neuphonic websocket API.<STOP>`, `Goodbye!<STOP>`];

// Processing multiple messages
for (const msg of msgs) {
    // Get chunks of the data as soon as they are ready (more responsive)
    for await (const chunk of ws.send(msg)) {
        // While receiving chunks, you can:
        // - send the data back to a frontend client, or
        // - collect it to save as a file
        chunks.push(chunk.audio);
        byteLen += chunk.audio.byteLength;
    }
}

// Merging all chunks into single Uint8Array array for saving
let offset = 0;
const allAudio = new Uint8Array(byteLen);
chunks.forEach(chunk => {
    allAudio.set(chunk, offset);
    offset += chunk.byteLength;
});

// Save data to file
const wav = toWav(allAudio);
const outPath = path.join('output.wav');
fs.writeFileSync(outPath, wav);

// Close the Websocket when done
await ws.close();