Skip to main content

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 Application - Try out one of our example programs.

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​

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.

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

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!