# Control variation with temperature

temperature sets how much a Paxa TTS Flash v2 reading varies from one request to the next, from 0 to 2. What it changes, designed voices, where it is read, and billing.

`temperature` is a field of [POST /v1/tts](https://paxalabs.com/docs/api/text-to-speech) that sets how much a reading varies from one request to the next: its pacing, pauses, breaths, and melody. It runs from 0 to 2 and defaults to 0.5. Paxa TTS Flash v2 reads it.

curl:

```bash
curl -X POST https://api.paxalabs.com/v1/tts \
  -H "Authorization: Bearer $PAXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs",
    "voice": "khanomkrok",
    "model": "paxa-tts-flash-v2",
    "temperature": 0
  }' \
  --output speech.mp3
```

TypeScript:

```typescript
import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.paxalabs.com/v1/tts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAXA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs",
    voice: "khanomkrok",
    model: "paxa-tts-flash-v2",
    temperature: 0,
  }),
});

if (!response.ok) throw new Error(`TTS failed: ${response.status}`);
await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));
```

Python:

```python
import os
import requests

response = requests.post(
    "https://api.paxalabs.com/v1/tts",
    headers={"Authorization": f"Bearer {os.environ['PAXA_API_KEY']}"},
    json={"text": "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs", "voice": "khanomkrok", "model": "paxa-tts-flash-v2", "temperature": 0},
)
response.raise_for_status()

with open("speech.mp3", "wb") as f:
    f.write(response.content)
```

## Values

- `0` varies least. The same text in the same voice comes back closest in timing and melody from one request to the next. Two requests are not guaranteed to match.
- `0.5` is the default. An omitted field and `0.5` are one request.
- `2` varies the reading most.
- Values round to the nearest 0.1. A value outside 0 to 2 answers [400 validation](https://paxalabs.com/docs/errors#validation).

## Designed voices

On a [designed voice](https://paxalabs.com/docs/designed-voices), as on any other, lower values hold the voice steadier and higher values vary it more.

## Models

Paxa TTS Flash v2 (`paxa-tts-flash-v2`) reads `temperature`. On Paxa TTS Flash (`paxa-tts-flash-v1`), a value that rounds to `0.5` is accepted, and any other answers [400 validation](https://paxalabs.com/docs/errors#validation) with `path` `body.temperature` and `reason` `not_allowed`, before any charge.

## Where it is read

- [POST /v1/tts](https://paxalabs.com/docs/api/text-to-speech).
- [POST /v1/audio/speech](https://paxalabs.com/docs/api/speech), as a Paxa extension to OpenAI's body. The OpenAI-compatible transcription endpoint ignores its own `temperature`.
- The `start` frame of [WS /v1/tts/live](https://paxalabs.com/docs/live-streaming), fixed for the connection. The `started` event echoes it when it is not `0.5`. A start frame whose model refuses it answers an `error` event with `validation`, and the connection stays open for a corrected start frame.

## Billing and idempotency

A request costs the same at every temperature. Under an `Idempotency-Key`, `temperature` is part of the request: a retry with a different value answers [422 idempotency_mismatch](https://paxalabs.com/docs/errors#idempotency_mismatch), and an omitted field matches `0.5`.