Quickstart

This guide will help you get started with the Murf API. You’ll learn how to get your API key, make your first text-to-speech request, and transcribe audio with speech-to-text.

Generate an API Key

To use the Murf API, you need an API key. If you don’t have one yet, you can create your API Key here. Store the key in a secure location, as you’ll need it to authenticate your requests. Then, save the key as an environment variable in your terminal.

# Export an environment variable on macOS or Linux systems
export MURF_API_KEY="your_api_key_here"

Make Your First API Request (Streaming) - Falcon 2.1 Model

To use Murf’s streaming API, you can either use the REST API using an HTTP client to receive audio data in real-time, or use one of our official SDKs.

Murf offers a variety of voice IDs for different languages and accents. You can choose a voice ID that best suits your application’s needs. You can see the full list of available voice IDs here, or fetch the list programmatically using the List Voices endpoint.

The following code snippets assume that you have exported the MURF_API_KEY system environment variable as shown above.

brew install portaudio

pip install murf pyaudio

import pyaudio
from murf import Murf, MurfRegion
client = Murf(
    api_key="YOUR_API_KEY", # Not required if you have set the MURF_API_KEY environment variable
    region=MurfRegion.GLOBAL
)
# For lower latency, specify a region closer to your users
# client = Murf(region=MurfRegion.IN)  # Example: India region
# Audio format settings (must match your API output)
SAMPLE_RATE = 24000  
CHANNELS = 1
FORMAT = pyaudio.paInt16
def play_streaming_audio():
    # Get the streaming audio generator
    audio_stream = client.text_to_speech.stream(
        text="Hi, How are you doing today?",
        voice_id="Gordon",
        model="falcon-2.1",
        locale="en-US",
        sample_rate=SAMPLE_RATE,
        format="PCM"
    )
    # Setup audio stream for playback
    pa = pyaudio.PyAudio()
    stream = pa.open(format=FORMAT, channels=CHANNELS, rate=SAMPLE_RATE, output=True)
    try:
        print("Starting audio playback...")
        for chunk in audio_stream:
            if chunk:  # Check if chunk has data
                stream.write(chunk)
    except Exception as e:
        print(f"Error during streaming: {e}")
    finally:
        stream.stop_stream()
        stream.close()
        pa.terminate()
        print("Audio streaming and playback complete!")
if __name__ == "__main__":
    play_streaming_audio()

Speech to Text (Beta): Streaming

Text to Speech streaming sends text and receives audio. Speech to Text streaming is the reverse: it sends audio over a WebSocket and returns partial transcripts while the caller speaks, then a final transcript when you end the turn. This example streams a WAV file and prints the transcripts.

pip install websockets

import asyncio
import json
import os
import wave
import websockets
API_KEY = os.environ["MURF_API_KEY"]
URL = f"wss://in.api.murf.ai/v1/transcription/stream-input?api_key={API_KEY}&language=hi"
CHUNK_MS = 100
async def send_audio(ws, path):
    with wave.open(path, "rb") as wav:
        await ws.send(json.dumps({
            "type": "AudioConfig",
            "codec": "pcm_s16le",
            "sample_rate": wav.getframerate(),
            "channels": wav.getnchannels(),
        }))
        frames_per_chunk = wav.getframerate() * CHUNK_MS // 1000
        while chunk := wav.readframes(frames_per_chunk):
            await ws.send(chunk)
            await asyncio.sleep(CHUNK_MS / 1000)
    await ws.send(json.dumps({"type": "CloseStream"}))
async def main(path):
    async with websockets.connect(URL) as ws:
        sender = asyncio.create_task(send_audio(ws, path))
        try:
            async for raw in ws:
                msg = json.loads(raw)
                if msg["type"] in ("partial", "final") and msg["transcript"]:
                    print(f'[{msg["type"]}] {msg["transcript"]}')
                elif msg["type"] == "Error":
                    print("Error:", msg["message"])
        except websockets.ConnectionClosedError:
            pass
        sender.cancel()
asyncio.run(main("sample.wav"))

To stream from a microphone or handle multi-turn conversations, see Streaming.

Next Steps

Explore the API Reference for text-to-speech, or the Speech to Text (Beta) guide for transcription.