Best Practices

This guide contains the best practices for using Murf API. These practices will help you get the most out of the API and ensure that your applications are performant, reliable, and secure.

Murf Falcon TTS: Prompting Best Practices

Falcon produces its best output when you send text the way a person would write it for another person to read. In most cases no preprocessing is needed: Falcon handles text normalisation, pacing and natural pauses on its own.

This guide is for developers calling the Falcon 2.1 streaming or WebSocket API, and for teams running Falcon inside a voice agent platform such as LiveKit, Pipecat or Agora, where an LLM writes the text Falcon speaks. Each section lists what to send, what to avoid, and an example.

Four rules cover most cases:

• Send full, punctuated sentences in normal casing.
• Send text in its original script. Falcon switches between languages inside a sentence; do not transliterate.
• Keep numbers, dates and currency in their standard written form.
• In a voice agent, stream LLM tokens straight to Falcon and let Falcon decide where to split.

Core text rules

Why casing matters. An all-caps word signals an initialism, so it may be read letter by letter. Keep EMI, KYC and UPI in capitals; write every other word in normal case.

Why original script matters. Romanised Hindi, Tamil or Kannada has no fixed spelling, so the model has to guess. Falcon first converts romanised Indic text back to native script, which costs accuracy and adds 5–10 ms to time-to-first-audio. Native script avoids both. For code-mixed speech such as Hinglish, write each word in the script it belongs to: Devanagari for Hindi words, Latin for English words, brand names and product names.

Choosing a voice, language and tone. Falcon offers 150+ voices across 35 languages. Pick and preview a voice in the Falcon voice library for your target language. Falcon voices are multinative: one voice can switch between languages mid-sentence. Set locale (for example hi-IN or en-US) to the caller’s main language; if you leave it out, it follows the voice. Falcon 2.1 voices have one style, Conversation, so set tone through word choice: an apology written as an apology sounds like one.

Numbers, dates and symbols

Write numbers, money, dates and contact details the way they appear on an invoice or a form. Falcon converts them to speech; do not spell them out in words by default. Before launch, play each format your agent uses through your chosen voice once.

Write the month as a word. 04/05/2026 means 4 May in India and 5 April in the US. Writing “4 May 2026” removes the ambiguity for every voice and locale.

Numbers inside Indic script. Keep digits as 0–9 inside Devanagari, Tamil or other Indic text, as most apps and statements display them: आपकी EMI ₹4,250 है।

Codes, IDs and spelled-out strings

OTPs, loan account numbers, PNRs and policy numbers need to be read one character at a time. Falcon has no spell or SSML tags, so you control this with spacing and punctuation in the text. Pick the method by how fast the listener must write it down.

Guidelines:

• Keep the code inside a sentence; never send the code alone.
• Use one delimiter style per string. Mixing periods and commas between characters produces uneven pauses.
• Group long numbers the way a person reads them aloud: card numbers in 4s, Indian mobiles in 5s.
• For letters that sound alike on a call (M/N, B/D, F/S), add a word: “B for Bangalore”. Falcon speaks only what is written, so the text has to include it.
• Letters in a Latin-script code are read with the voice’s own accent. Preview codes with each voice you ship.

Names, brands and hard words

Falcon 2.1 pronounces most names well from their spelling. When one comes out wrong, fix it one of two ways:

• A fixed list of names (your brand, products, common places): send a pronunciationDictionary with every Stream Speech request, or pronunciation_dictionary in WebSocket voice_config, for example {"Murf": {"type": "IPA", "pronunciation": "mɜːrf"}}. Your text stays readable, and the LLM doesn’t need to know any IPA.
• Names that change from call to call (a customer’s name, a medicine): write the IPA in the text, between slashes inside double quotes: Welcome to "/mɜːrf/". This also works over WebSockets.

Test each custom pronunciation with every voice you ship. See Pronunciations.

Pauses, speed and fillers

Pauses. Falcon adds natural pauses from the text itself. Shape pauses with punctuation: a comma gives a short beat, a full stop a longer one, and a new sentence or line break resets the rhythm. To pause after an amount, end the sentence there: “Your balance is ₹4,250. Your next EMI is due on 5 October.”

Speed. Set rate for speed and pitch for tone on the request or in voice_config. Both take an integer from -50 to 50; the default is 0. In the LiveKit plugin, speed is called speed. Start at 0 and move in steps of 5, listening after each change. Use one setting for the whole call rather than changing speed mid-conversation.

Loudness. Set volumeOffset when the agent sounds too quiet or too loud on the channel callers actually use—often 10–25 on phone calls and 15–30 on mobile voice paths. Default is 0. See Volume offset.

Fillers. Falcon speaks only what is written and does not insert fillers on its own. For a more human agent:

• Write fillers in standard spelling (um, uh, hmm; in Hindi, अच्छा), set off by commas.
• Use them before a looked-up value or after a hard question, and not in every turn.

Example: Let me check that for you. Your outstanding amount is, uh, ₹4,250.

Streaming and chunking

Turn off chunking in your voice agent platform. Stream LLM tokens straight to Falcon’s WebSocket and disable the sentence tokenizer or text aggregation in your framework, such as LiveKit or Pipecat. Falcon chunks automatically: it waits for a sentence to end, marked by punctuation, before generating audio. Splitting text twice adds a wait at each layer, so leaving the split to Falcon lowers latency.

More streaming habits:

• Keep one WebSocket open per call and send every turn on it. Reusing the connection saves 30–80 ms of handshake per request.
• Use a context_id per turn so pitch and pace carry across chunks, and send end: true when the turn is done.
• When the caller interrupts, send clear with that context_id to stop audio that is still queued.
• Use the global endpoint, or the region closest to where your agent runs, and measure time-to-first-audio from that server, not from a laptop.

See Streaming and WebSockets for endpoint setup and examples.

Voice agents: rules for the LLM system prompt

In a voice agent, an LLM writes every line Falcon speaks. Add the block below to your agent’s system prompt and adjust the examples to your use case.

OUTPUT FOR SPEECH (Murf Falcon)
Everything you write is spoken aloud by a text-to-speech voice. Write for the ear, the way a person would write a message for someone else to read out.
FORMAT
- Reply in plain, complete sentences. End every sentence with . ? or ! (use । for Hindi).
- Never use markdown, bullet points, numbered lists, headings, asterisks, emoji, URLs, HTML or SSML tags, code or JSON. Every symbol you write is read aloud.
- Keep replies short: 1 to 3 sentences unless the caller asks for more detail.
- Do not announce lists ("here are three options"). Say the items in one sentence, separated by commas.
LANGUAGE AND SCRIPT
- Reply in the caller's language. If the caller mixes languages, mix them the same way.
- Write every word in its own script: Hindi in Devanagari, Tamil in Tamil script, Kannada in Kannada script, and English words, brand names and product names in Latin script.
- Never write Hindi or any other Indian language in Roman letters.
  Correct: आपका EMI कल देय है।
  Wrong: Aapka EMI kal dey hai.
- Inside Indic text, keep digits as 0–9: आपकी EMI ₹4,250 है।
CASING AND EMPHASIS
- Use normal sentence case and keep the caller's names capitalised as names.
- Use capitals only for initialisms that are read letter by letter, such as EMI, KYC, UPI, OTP.
- Never use capitals for emphasis. Emphasise through word choice or an exclamation mark.
  Correct: This step is important!
  Wrong: This step is IMPORTANT.
NUMBERS, MONEY, DATES AND CONTACT DETAILS
- Write them as they would appear on an invoice or a form. Never spell numbers out in words.
- Money: ₹1,25,000 (Indian grouping), $1,250,000 (international grouping), ₹499.50.
- Percentages: 12.5%.
- Dates: always write the month as a word, for example 4 May 2026. Never use 04/05/2026.
- Times: 7:30 PM.
- Phone numbers: +91 98450 12345 for Indian mobiles, (415) 555-0123 for US numbers.
- Email addresses: write them normally, for example priya@example.com.
CODES AND IDS (OTPs, PNRs, account numbers, policy numbers)
- Always put the code inside a sentence. Never send a code on its own.
- If the caller only needs to hear it, separate characters with spaces: Your PNR is K 7 M 2 Q X.
- If the caller needs to write it down, separate characters with commas: Your OTP is 4, 8, 2, 9, 1, 3.
- For codes of 10 or more characters, put spaces between characters and group them in 4s with a comma between groups: Your loan account number is 5 0 2 1, 8 8 4 3, 7 1 0 6.
- Use one delimiter style per code. Never mix commas and full stops inside the same code.
- For letters that sound alike on a call (M and N, B and D, F and S), add a word after the letter, such as "B for Bangalore".
PRONUNCIATION
- When you say one of these words, write it exactly as shown, including the double quotes and the slashes:
  Murf -> "/mɜːrf/"
  <add your brand, product and people's names here>
- Use double quotes with slashes only for these words.
PAUSES AND FILLERS
- Create pauses with punctuation only: a comma for a short pause, a full stop for a longer one.
- To pause after a number, end the sentence right after it: Your balance is ₹4,250. Your next EMI is due on 5 October.
- You may occasionally use a filler such as um, uh or hmm (in Hindi, अच्छा), set off by commas, just before stating a looked-up value or after a difficult question. Do not use fillers in every reply.
  Example: Let me check that for you. Your outstanding amount is, uh, ₹4,250.
TONE
- Convey tone through wording. An apology should be written as a real apology; good news should be written warmly.
CONTENT
- State only facts given in this prompt or returned by tools. If a value is missing, say you will check. Never guess numbers, dates, amounts or codes.
- Do not repeat details the caller has already confirmed.

Before going live, run 10–20 test calls per language and listen for misread numbers, codes and names.

API Key Safety

API keys are used to authenticate requests to the Murf API. It is important to keep your API keys secure to prevent unauthorized access to your account and data. Here are some best practices for keeping your API keys safe:

Never deploy your key in client-side environments like browsers or mobile apps.

If API keys are stored on the client side, they may be exposed to malicious actors - who can use them to make unauthorized requests on your behalf. This will result in unexpected charges and potential data breaches. When writing Murf API logic in client-side code, you can use a server-side application that generates a token for the client to use. The requests from the client can then be authenticated using this token.

Store your API keys as environment variables

To keep your API keys secure, store them as environment variables in your application. This will prevent you from accidentally exposing your keys in your codebase.

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

Alternatively you can use a key management service to securely store and manage your API keys.

Monitor your API usage

Regularly monitor your API usage to detect any unusual activity from your usage dashboard. If you notice any unexpected spikes in usage, it may indicate that your API key has been compromised. In such cases, you should immediately revoke the key and generate a new one. Rotate your API keys regularly to minimize the risk of unauthorized access.