> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://murf.ai/api/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://murf.ai/api/docs/_mcp/server. 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](/api/docs/text-to-speech-models/falcon-2-1) [streaming](/api/docs/api-reference/text-to-speech/stream) or [WebSocket](/api/docs/api-reference/text-to-speech/stream-input) API, and for teams running Falcon inside a voice agent platform such as [LiveKit](/api/docs/integrations/livekit), [Pipecat](/api/docs/integrations/pipecat) or [Agora](/api/docs/integrations/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 | Rule | Send | Avoid | | ------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------- | | End every input with terminal punctuation (. ? !) | Your order has shipped. | Your order has shipped | | Send whole sentences, including around numbers and codes | Your OTP is 482913. | 482913 | | Use sentence casing; keep all-caps for letter-by-letter initialisms | Please call the bank. The KYC is pending. | PLEASE CALL THE BANK. | | Emphasise with word choice or punctuation, not capitals | This step is important! | This step is IMPORTANT. | | Leave punctuation and casing as written | Hello, Priya. How are you? | hello priya how are you | | Avoid transliteration: send text in its original script | आपका EMI कल देय है। | Aapka EMI kal dey hai. | | Pick a voice that supports every language in the text | A voice listing Hindi and English for Hinglish calls | A voice without Tamil support for Tamil text | **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](https://murf.ai/api/products/text-to-speech/Falcon) 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. | Type | Send as | Listener should hear | | ------------------------------ | --------------------------------------------- | ----------------------------------------------- | | Amount, Indian grouping | ₹1,25,000 | one lakh twenty-five thousand rupees | | Amount, international grouping | \$1,250,000 | one million two hundred fifty thousand dollars | | Amount with paise or cents | ₹499.50 | four hundred ninety-nine rupees and fifty paise | | Percentage | 12.5% | twelve point five percent | | Date | 29 September 2026 | twenty-ninth September twenty twenty-six | | Time | 7:30 PM | seven thirty PM | | Indian mobile | +91 98450 12345 | digits in 2 groups of 5 | | US phone | (415) 555-0123 | digits in groups of 3, 3 and 4 | | Email | [priya@example.com](mailto:priya@example.com) | priya at example dot com | | Initialism | EMI, KYC, UPI | each letter | **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. | Method | Example | Pace | When to use | | ---------------------------------- | ----------------------------------------------- | ------------------- | ------------------------------ | | Spaces between characters | Your PNR is K 7 M 2 Q X. | Natural | Listener only needs to hear it | | Commas between characters | Your OTP is 4, 8, 2, 9, 1, 3. | Slow | Listener writes it down | | Groups of 4, commas between groups | Your loan account is 5 0 2 1, 8 8 4 3, 7 1 0 6. | Natural with breaks | 10+ characters | 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](/api/docs/text-to-speech/speech-customization#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](/api/docs/text-to-speech/speech-customization#volume-offset-falcon-2). **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`](/api/docs/text-to-speech/web-sockets/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](/api/docs/text-to-speech/streaming) and [WebSockets](/api/docs/text-to-speech/web-sockets) 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. #### LLM system prompt template ```text 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/" - 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. **`macOS / Linux`** ```bash title="macOS / Linux" # Export an environment variable on macOS or Linux systems export MURF_API_KEY="your_api_key_here" ``` **`Windows`** ```bash title="Windows" # Export an environment variable in PowerShell setx 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](https://murf.ai/api/usage). 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.