Quickstart

Prerequisites

Before you can make any requests, you must first create an API key. You can create one in the Playground. The API key must be included in all subsequent requests in the X-API-Key header, including on the WebSocket handshake.

Obtain a list of available voices

Before generating audio from your text, you must first select the ID of the voice you’d like to use. To view a list of available voices, send the following request:

curl https://api.respeecher.com/v1/public/tts/en-rt/voices \
     -H "X-API-Key: <ApiKey>"

The result should look something like this:

[
  {
    "id": "samantha",
    "gender": "female",
    "accent": "American",
    "sampling_params": {
      "temperature": 0.6,
      "top_k": -1,
      "top_p": 0.8,
      "min_p": 0,
      "presence_penalty": 0,
      "repetition_penalty": 2,
      "frequency_penalty": 2
    }
  },
  {
    "id": "amara",
    "gender": "female",
    "accent": "Indian",
    "sampling_params": {
      "temperature": 0.7,
      "top_k": 66,
      "top_p": 0.8,
      "min_p": 0,
      "presence_penalty": 0,
      "repetition_penalty": 1.4,
      "frequency_penalty": 0.8
    }
  }
]

Generate your first audio with the Bytes endpoint

Now that you have the ID of the voice you would like to use you can make a POST request to the Bytes endpoint and generate some audio data. Redirect the output to a file by appending --output result.wav or > result.wav to the curl command. The file result.wav can then be listened to in any audio player.

curl -X POST https://api.respeecher.com/v1/public/tts/en-rt/tts/bytes \
     -H "X-API-Key: <ApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "transcript": "Hello, World!",
  "voice": {
    "id": "samantha"
  }
}'

Stream audio with the Server-Sent Events endpoint

curl -X POST https://api.respeecher.com/v1/public/tts/en-rt/tts/sse \
     -H "X-API-Key: <ApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "transcript": "Hello, World!",
  "voice": {
    "id": "samantha"
  }
}'

{"type": "chunk", "data": "..."}

import json
import base64
import numpy as np
import soundfile as sf
sample_rate = 22050
infile = "result.json"
outfile = "result.wav"
with open(infile, "r", encoding="utf-8") as f:
    data = [json.loads(line) for line in f]
chunks = []
for chunk in data:
    audio_bytes = base64.b64decode(chunk["data"])
    audio = np.frombuffer(audio_bytes, dtype=np.float32)
    chunks.append(audio)
full_audio = np.concatenate(chunks)
sf.write(outfile, full_audio, sample_rate)

Stream audio via WebSockets

The API also supports streaming audio via WebSockets. Here is a quick example implementation of a Python client that supports real-time playback using the WebSocket endpoint:

import json
import base64
import pyaudio
import numpy as np
from websocket import create_connection
voice = "<the id of the voice you want to use>"
# connect to pyaudio for audio output
pa = pyaudio.PyAudio()
stream = pa.open(
    format=pyaudio.paFloat32, channels=1, rate=22050, output=True
)
# connect to the websocket
ws = create_connection("wss://<endpoint>/tts/websocket", header=["X-Api-Key: <ApiKey>"])
while True:
    # read input
    try:
        text = input("> ")
    except EOFError:
        break
    # send the input text to the websocket
    transcript = json.dumps({
        "transcript": text, "voice": {"id": voice}, "context_id": ""
    })
    ws.send_text(transcript)
    # receive the result
    chunks = []
    while True:
        chunk = json.loads(ws.recv())
        if chunk.get("type") == "done":
            break
        audio_bytes = base64.b64decode(chunk.get("data", b''))
        stream.write(audio_bytes)

Support