# Options

> The five settings that change how the model speaks, what it does when you leave them out, and the emotion tags it reads in the text.

## The options

Five, all optional. One you leave out isn't sent, and the model's own default applies.

- `normalize` (`boolean`, Optional; left out: on): Speak numbers, currency, dates, times, OTPs, phone numbers, URLs and emails as words in the request’s language. `false` turns it off: the text is spoken as written.
- `temperature` (`number`, Optional; left out: the model's default): Sampling temperature, 0.1 to 1.5: lower is steadier, higher is more varied.
- `top_k` (`integer`, Optional; left out: the model's default): Sample from the k likeliest codes, 1 to 2048.
- `top_p` (`number`, Optional; left out: the model's default): Nucleus sampling, above 0 and at most 1.
- `repetition_penalty` (`number`, Optional; left out: the model's default): Penalty on recently repeated codes, 0 to 5.

A value outside its range is refused with `bad_request`, naming the option. `GET /v1/models` lists the options with their ranges.

## Where they go

The same five names in every client.

| Client | Where |
| --- | --- |
| [LiveKit plugin](https://docs.vaakini.com/livekit.md#tts) | Keyword arguments of `vaakini.TTS(...)` and `update_options(...)` |
| [Pipecat service](https://docs.vaakini.com/pipecat.md#settings) | Fields of `VaakiniTTSService.Settings(...)` |
| [Python SDK](https://docs.vaakini.com/python.md#speech-arguments) | Keyword arguments of `speech.create()`, `speech.stream()` and `stream()` |
| [HTTP API](https://docs.vaakini.com/http.md#fields) | Top-level fields of the request body |
| [WebSocket API](https://docs.vaakini.com/websocket.md#start) | Inside `options` in `start` and `warm` |

**Python**

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

audio = client.speech.create(
    input="आपका बिल ₹1,250 है, जो 15 दिसंबर तक भरना है।",
    voice="Monika",
    language="hi",
    temperature=0.6,
    top_p=0.9,
)
with open("bill.mp3", "wb") as f:
    f.write(audio)
```

**cURL**

```shell
curl https://api.vaakini.com/v1/audio/speech \
  -H "Authorization: Bearer $VAAKINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vaakini-tts-1",
    "voice": "Monika",
    "language": "hi",
    "input": "नमस्ते, आपका ऑर्डर कल पहुँच जाएगा। डिलीवरी से पहले आपको कॉल आएगा।",
    "response_format": "pcm",
    "temperature": 0.6
  }' \
  --output speech.pcm
```

On the WebSocket:

```json
{
  "type": "start",
  "segment_id": "reply-1",
  "model": "vaakini-tts-1",
  "voice": "Monika",
  "language": "hi",
  "sample_rate": 24000,
  "format": "pcm",
  "options": {"temperature": 0.6}
}
```

## Numbers and symbols

With normalize on, which it is unless you turn it off, what isn't a word is spoken as words.

Numbers, currency, dates, times, OTPs, phone numbers, URLs and emails are read in the request’s language: `₹1,250` in a Hindi request is spoken as an amount in rupees, in Hindi. Name the [language](https://docs.vaakini.com/voices.md#languages) when your text has them.

Turn it off (`normalize: false`) when your own code already writes everything out as words and you want the text spoken exactly as written.

## Emotion tags

Five tags, written in the text where the effect should happen.

| Tag | What it asks for |
| --- | --- |
| \[laughs\] | A laugh |
| \[sighs\] | A sigh |
| \[whispers\] | A whisper |
| \[sad\] | A sad tone |
| \[excited\] | An excited tone |

A tag is part of the text, not a setting, so it works the same in every client: write it inline, in square brackets, at the point in the sentence where it should take effect.

```python
from vaakini import Vaakini

client = Vaakini()  # reads VAAKINI_API_KEY

lines = {
    "hi": "[excited] अरे वाह, आपका ऑर्डर आज ही पहुँच जाएगा!",
    "en": "I am so sorry to hear that. [sighs] Let me see what I can do.",
}
for language, text in lines.items():
    audio = client.speech.create(input=text, voice="Monika", language=language)
    with open(f"tags-{language}.mp3", "wb") as f:
        f.write(audio)
```

- **They are best effort.** The model usually follows a tag, not always, and how strongly varies from take to take.
- **They are counted.** A tag’s characters are part of its sentence, brackets included: `[excited]` adds 9 characters to the sentence’s count, and the space after it one more.
- **A tag belongs to the sentence it is written in.** One written after a sentence’s end mark opens the next sentence. One at the very end of a text, after the last end mark, is sent as a sentence of its own: put a closing tag before the end mark instead.

## What isn't an option

- **Speed.** There is no `speed`; a request that sends one is refused.
- **A seed.** The model samples, so the same text can sound slightly different each time, and there is no setting that makes two takes identical. A lower `temperature` makes them steadier.
- **Splitting.** Text is always spoken sentence by sentence.
- **The sample rate.** Audio is 24000 Hz. Resample it on your side if you need another rate (the Pipecat pipeline’s output transport does it for you).
