> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nixflex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voices

> Choose how your Nixflex agent sounds.

# Voices

Every Nixflex agent speaks with a voice. You can set it at two levels: a **default voice on the agent**, and an optional **per-number voice** that overrides it for a specific phone number.

## Two ways to set a voice

**Agent default** — the voice used by every number on the agent unless a number overrides it. Set the `voice_id` field on the agent:

```json theme={null}
{
  "voice_id": "Olivia",
  "language": "en"
}
```

**Per-number override** — give one phone number its own voice, regardless of the agent default. This is essential when one agent serves many numbers (for example a reseller running 200 clinics on a single agent) and each number needs to sound different. Set `voice_id` on the number:

```bash theme={null}
curl -X PATCH https://api.nixflex.com/v1/phone-numbers/+447446466847 \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "voice_id": "Craig" }'
```

A number with its own `voice_id` uses that voice; a number without one falls back to the agent's voice. Changes take effect on the next call — no redeploy. See [Update phone number](/api-reference/phone-numbers/update) for the full endpoint.

Per-number voice applies to **both inbound and outbound** calls. The voice is resolved from the number the call uses: the dialled number for inbound, the from\_number for outbound, so a number sounds the same in both directions. Set it once; if it ever gets cleared, set it again before the next call.

<Note>
  `voice_id` must be an exact, valid voice ID (for example `Olivia`, `Craig`, `Ashley`). An unrecognised value falls back to the agent's voice rather than erroring, so if a voice isn't changing, check the value is exact.
</Note>

## Recommended voices

These voices work well for phone receptionists and business calls — warm, clear, and professional.

| Voice  | Gender | Style                          | Language     |
| ------ | ------ | ------------------------------ | ------------ |
| Olivia | Female | Friendly, confident British    | English (UK) |
| Ashley | Female | Warm, natural American         | English (US) |
| Edward | Male   | Clear, emphatic American       | English (US) |
| Annika | Female | Warm, engaging                 | German       |
| Kilian | Male   | Warm, natural                  | German       |
| Sofia  | Female | Clear, engaging Latin American | Spanish      |
| Diego  | Male   | Soothing, gentle               | Spanish      |
| Nour   | Female | Polished, friendly             | Arabic       |
| Omar   | Male   | Bright, confident              | Arabic       |

## Multilingual voices

Some voices speak several languages while keeping the same identity. For example, Olivia can speak English, German, Spanish, and Arabic. Set the `language` field to choose which language the voice speaks on a call.

## Speaking speed

How fast the agent talks. `1.0` is normal, `0.5` is half speed, and `1.5` is half again as fast. A value outside that range is clamped to the nearest limit rather than rejected.

Like the voice, speed can be set at two levels.

**Agent default** — set it in the dashboard, or send `speaking_rate` when you create or update the agent. Every number on that agent speaks at this speed unless the number overrides it.

```bash theme={null}
curl -X PUT https://api.nixflex.com/v1/agents/agent_125207e452f8714a \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "speaking_rate": 1.1 }'
```

<Note>
  `speaking_rate` is the field that controls speed. The older `voice_speed` field on
  the agent is still accepted and returned for backwards compatibility, but nothing
  reads it - setting it has no effect. See [Create agent](/api-reference/agents/create).
</Note>

**Per-number override** — set `speaking_rate` on the number:

```bash theme={null}
curl -X PATCH https://api.nixflex.com/v1/phone-numbers/+447446466847 \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "speaking_rate": 0.9 }'
```

A number with its own speed uses it. A number without one falls back to the agent. An agent without one speaks at normal speed.

So if you set the agent to `1.5`, **every number on that agent speaks at 1.5** - including numbers you have never touched. Only a number with its own `speaking_rate` is exempt.

<Warning>
  `null` and `1` are not the same thing.

  * `null` means **not set**. The number inherits the agent's speed, so a number set to `null` under a `1.5` agent still speaks at `1.5`.
  * `1` means **explicitly normal**. It overrides the agent, so a number set to `1` under a `1.5` agent speaks at normal speed.

  To bring one number back to normal while the rest of the agent stays fast, send `1` - not `null`.
</Warning>

Speed applies to **both inbound and outbound** calls and takes effect on the next call, like the voice itself.

<Note>
  Small steps go a long way on a phone line. `0.9` already sounds noticeably more measured and `1.1` noticeably brisker, so adjust a step at a time rather than jumping to the limits.
</Note>

## Preview before you go live

Always listen to a voice before using it on real calls. A dental clinic wants a calm, professional voice; a sales line might want something more energetic.