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

# Languages & Voice

> How an agent picks its language, mirrors the caller, and chooses a voice.

Every agent speaks a **primary language** and can **mirror the caller's language** mid-call.
Separately, it has a **voice** — the identity it speaks with. Language and voice are set
independently: one agent can answer in around 40 languages while keeping the same voice.

## Primary language and mirroring

An agent holds a `primaryLanguage` (a BCP-47 code like `en`, `es`, or `fr`) plus a list of
`languages` it supports. The greeting and default behavior use the primary language. When a
caller speaks a different supported language, the agent can switch to it for the rest of the
conversation — no separate flow required.

<Note>
  Set `primaryLanguage` and `languages` when you create the agent, or update them later with
  `PATCH /agents/{id}`. Mirroring works across the supported set; pick the languages you actually
  want to serve.
</Note>

## How a voice is chosen

A voice is a catalog entry with a normalized set of facets — `language`, `accent`, `gender`,
`age`, `category`, and mood `descriptorTags`. You find a voice three ways, then assign it.

<Steps>
  <Step title="Browse the catalog">
    `GET /voices` returns the catalog, narrowed by any combination of facets (all AND-combined):
    `language`, `accent`, `region`, `gender`, `age`, `category`, `tone`, `useCase`, or free-text `q`.
  </Step>

  <Step title="Count as you narrow">
    `GET /voices/facets` returns live counts per facet ("Female · 142") over the same filters,
    so a picker can show how each chip shrinks the result set.
  </Step>

  <Step title="Search in plain language">
    `POST /voices/search` turns a phrase like *"calm older british woman for support"* into
    facets and returns the resolved filters plus a short ranked shortlist to audition.
  </Step>

  <Step title="Assign it">
    `PUT /agents/{id}/voice` assigns a `voiceId` to the agent for a language (defaults to the
    primary language). This is the one-call way to set the voice.
  </Step>
</Steps>

A voice carries a `previewUrl` to audition it, `supportedLanguages` it can speak, `capabilities`
(which fine-tuning settings the voice supports and its safe speed band), and `verifiedLanguages`
— languages the voice is explicitly verified for, with a localized preview.

<Tip>
  Per-language voices are stored in the agent's `voiceMap`, and the primary-language voice is also
  its `defaultVoiceId`. Assigning a voice for one language never changes the others.
</Tip>

## In the API

| Action                                     | Endpoint                 | Scope          |
| ------------------------------------------ | ------------------------ | -------------- |
| Browse the voice catalog                   | `GET /voices`            | `agents:read`  |
| Live facet counts                          | `GET /voices/facets`     | `agents:read`  |
| Natural-language voice search              | `POST /voices/search`    | `agents:read`  |
| Assign a voice to an agent                 | `PUT /agents/{id}/voice` | `agents:write` |
| Set primary language / supported languages | `PATCH /agents/{id}`     | `agents:write` |

<CodeGroup>
  ```bash curl theme={null}
  curl https://builder.flowyte.com/api/v1/voices/search \
    -H "Authorization: Bearer flowyte_sk_..." \
    -H "Content-Type: application/json" \
    -d '{"query":"calm older british woman for support","limit":5}'
  ```

  ```js Node theme={null}
  const res = await fetch("https://builder.flowyte.com/api/v1/agents/AGENT_ID/voice", {
    method: "PUT",
    headers: {
      Authorization: "Bearer flowyte_sk_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ voiceId: "VOICE_ID", language: "en" }),
  });
  ```

  ```python Python theme={null}
  import requests

  requests.put(
      "https://builder.flowyte.com/api/v1/agents/AGENT_ID/voice",
      headers={"Authorization": "Bearer flowyte_sk_..."},
      json={"voiceId": "VOICE_ID", "language": "en"},
  )
  ```
</CodeGroup>

Voice and language are part of the agent's **draft**. [Publish](/concepts/agents) the agent so
phone and chat callers hear the change.