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

# Voice

# Voices

Voices are how your agent sounds on calls. Search the library by name or feel, narrow it by
language, gender, accent, pitch, style and use case, play a sample, then put the voice `id` on an
agent as `voice_id`. The same search is on the [Brilo MCP server](https://docs.brilo.ai/api-reference/mcp/tools.md) as
`search_voices`.

Errors share one shape, `{ "status", "error_code", "message", "details" }`. Branch on `error_code`;
the `message` says in plain words what to change.

## List Voices

```http theme={null}
GET /voices?language=en&style=warm,calm&use_case=front_desk
```

| Parameter | Description |
| - | - |
| q | Words that must all appear in the name, description, accent, tags, style or use case, in any order. `calm british` finds the same voices as `british calm`. |
| language | Language codes, as in the `language` facet, for example `en` or `es`. |
| gender | `female`, `male` or `neutral`. |
| accent | Accents, as in the `accent` facet, for example `American`. |
| pitch | `low`, `medium` or `high`. |
| style | `warm`, `calm`, `confident`, `friendly`, `clear`, `upbeat`, `professional` or `empathetic`. |
| use\_case | `front_desk`, `customer_support`, `sales`, `reminders`, `assistant` or `general`. |
| limit | Voices per page, 1 to 200. Default 50. |
| cursor | `next_cursor` from the previous page. |

Each filter takes several values, comma separated or with the parameter repeated. A voice matches
a filter when it has any of the values, and it must match every filter you send.

The newest voices come first, then the rest of the library. Voices your plan can't use stay in the
list with `locked` set to `true`, so you can still hear them. Voices your workspace can't use at all,
because of its region or because it is a healthcare (HIPAA) workspace and the voice isn't covered
yet, are left out.

### Response

```json theme={null}
{
  "status": 200,
  "data": [
    {
      "id": "0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c",
      "name": "Kore",
      "description": "Warm and approachable",
      "language": "en",
      "language_label": "English",
      "accent": "American",
      "gender": "female",
      "age": null,
      "pitch": "medium",
      "styles": ["warm"],
      "use_cases": ["front_desk"],
      "tags": ["Warm", "Front desk", "Medium pitch"],
      "preview_url": null,
      "locked": false,
      "capabilities": { "speed": false, "expressive": false }
    }
  ],
  "facets": [
    {
      "key": "style",
      "label": "Style",
      "options": [
        { "value": "warm", "label": "Warm", "count": 12 },
        { "value": "calm", "label": "Calm", "count": 9 }
      ]
    }
  ],
  "total": 24,
  "next_cursor": null
}
```

`facets` lists every filter with each option and how many voices it would match, counted with
your search and every other filter applied. Options no voice has are left out, so call it with no
parameters to see what the library holds.

`capabilities.speed` says whether your agent's speaking speed setting changes the voice. When it is
`false`, the voice sets its own pace. `capabilities.expressive` says whether your agent's expressions,
such as speaking warmly or a short laugh, work with the voice. When it is `false`, the voice ignores them.

`preview_url` is a short sample clip, or `null` when nobody has played the voice yet. Use Preview
a Voice to make one.

| error\_code | Status | When |
| - | - | - |
| `validation_failed` | 400 | A gender, pitch, style or use case that isn't one of the choices, a `limit` outside 1 to 200, or a `cursor` this API didn't return. The message lists the choices |

## Get a Voice

```http theme={null}
GET /voices/{id}
```

Returns one voice in the same shape. A voice your workspace can't use returns `404`
`voice_not_found`, the same as an unknown id.

## Preview a Voice

```http theme={null}
POST /voices/{id}/preview
```

Returns a public link to a short sample of the voice. English voices read a front desk greeting;
Spanish and Hindi voices read it in their own language, and every other language reads it in
English. The first request for a voice makes the clip, which can take a few seconds. Every later
request returns it at once.

```json theme={null}
{
  "status": 200,
  "data": {
    "preview_url": "https://assets.brilo.ai/voice/v2/0b6f3c1a-2d4e-4f5a-8b9c-1d2e3f4a5b6c.wav",
    "cache": "MISS"
  }
}
```

`cache` is `HIT` when the clip already existed and `MISS` when this request made it.

| error\_code | Status | When |
| - | - | - |
| `voice_not_found` | 404 | No such voice, or your workspace can't use it |
| `preview_not_available` | 501 | This voice has no sample yet |
| `preview_rate_limited` | 503 | The voice provider is busy. Try again in a moment |
| `preview_timeout` | 504 | Making the clip took more than 10 seconds. Try again |
| `preview_provider_error` | 502 | The voice provider couldn't make the clip |
| `preview_storage_failed` | 502 | The clip was made but couldn't be stored. Try again |

## Healthcare workspaces

Some voices aren't covered for healthcare (HIPAA) workspaces yet. Those workspaces never see them in
the library, and an agent can't be saved with one: the request returns `400`
`voice_not_hipaa_compliant`. If an agent already uses one, its calls speak in a covered voice in the
same language instead.

## Related

* [Agent builder](https://docs.brilo.ai/api-reference/endpoint/agent-builder.md) to create an agent
* [MCP tools](https://docs.brilo.ai/api-reference/mcp/tools.md) for `search_voices`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.