# Murf (/en/ai/platform/models/tts/murf)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-guides-v2.txt).


Murf provides enterprise-grade AI voice generation with text-to-speech (TTS) models.

## Sample configuration

The following example shows how to configure Murf as the agent's TTS when you create or update an agent. For a complete example, see [Create an agent and start a session](/en/ai/platform/get-started/start-stop-agent#create-an-agent).

Murf supports BYOK only. It isn't available in managed mode. Store your Murf API key in a secret set, and refer to it from the agent. For details, see [Use your own provider keys](/en/ai/platform/build/use-your-own-keys).

**Python SDK**

```python
from agora_agent import Agent, MurfTTS, secret_ref

# client is your configured Agora client
agent = (
    Agent(client=client)
    .with_stt(...)  # configure your ASR vendor
    .with_llm(...)  # configure your LLM vendor
    .with_tts(
        MurfTTS(
            key=secret_ref("support_prod", "murf"),
            base_url="wss://global.api.murf.ai/v1/speech/stream-input",
            voice_id="Matthew",
            locale="en-US",
            rate=0,
            pitch=0,
            model="FALCON",
            sample_rate=24000,
        )
    )
)
```

**TypeScript SDK**

```ts
import { Agent, MurfTTS, secretRef } from 'agora-agents';

// client is your configured Agora client
const agent = new Agent({ client })
  .withStt(/* configure your ASR vendor */)
  .withLlm(/* configure your LLM vendor */)
  .withTts(
    new MurfTTS({
      key: secretRef('support_prod', 'murf'),
      baseUrl: 'wss://global.api.murf.ai/v1/speech/stream-input',
      voiceId: 'Matthew',
      locale: 'en-US',
      rate: 0,
      pitch: 0,
      model: 'FALCON',
      sampleRate: 24000,
    }),
  );
```

**Go SDK**

```go
rate, pitch, sampleRate := 0.0, 0.0, 24000
// client is your configured Agora client
agent := agentkit.NewAgent(client).
	WithStt( /* configure your ASR vendor */ ).
	WithLlm( /* configure your LLM vendor */ ).
	WithTts(vendors.NewMurfTTS(vendors.MurfTTSOptions{
		Key:        agentkit.SecretRef("support_prod", "murf"),
		BaseURL:    "wss://global.api.murf.ai/v1/speech/stream-input",
		VoiceID:    "Matthew",
		Locale:     "en-US",
		Rate:       &rate,
		Pitch:      &pitch,
		Model:      "FALCON",
		SampleRate: &sampleRate,
	}))
```

**REST API**

Set `credential.mode` to `byok` and `credential.fields.api_key` to a reference to your Murf API key in a secret set. In the following example, the key is stored as `murf` in the `support_prod` set:

```json
"tts": {
  "credential": {
    "mode": "byok",
    "fields": {
      "api_key": "$secrets.support_prod.murf"
    }
  },
  "vendor": "murf",
  "url": "wss://global.api.murf.ai/v1/speech/stream-input",
  "params": {
    "voiceId": "Matthew",
    "locale": "en-US",
    "rate": 0,
    "pitch": 0,
    "model": "FALCON",
    "sample_rate": 24000
  }
}
```

## Key parameters

The `tts` block takes the following fields. In the SDKs, the Murf TTS class sets them from its options.

**tts**

**`vendor` (string) required**

Set to `murf`.

**`credential` (object) required**

Set `mode` to `byok` and `fields.api_key` to a `$secrets.<set>.<key>` reference to your Murf API key.

**`url` (string) optional**

The WebSocket endpoint for streaming TTS output, for example `wss://global.api.murf.ai/v1/speech/stream-input`.

**`params` (object) optional**

**`voiceId` (string) optional**

The voice identifier to use, for example `Matthew`.

**`locale` (string) optional**

The locale for the selected voice, for example `en-US`.

**`rate` (number) optional**

The speech rate adjustment. A value of `0` applies the default rate.

**`pitch` (number) optional**

The pitch adjustment. A value of `0` applies the default pitch.

**`model` (string) optional**

The TTS model to use, for example `FALCON`.

**`sample_rate` (number) optional**

The audio sample rate in Hz, for example `24000`.

> **Caution**
>
> The parameters listed on this page are validated for use with the Conversational AI Platform. Required parameters must be provided as documented. Any additional parameters in `params` are passed through directly to Murf without validation. For a full list of supported options, refer to the [Murf documentation](https://murf.ai/api/docs/api-reference/text-to-speech/stream-input).

This integration is fully supported for use with the Conversational AI Platform. While it has completed functional validation, it is newer to the platform, and additional provider-specific edge cases may be identified as usage scales across a broader range of applications and workloads.