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

# Working with voices

> Find the voices available to your API key and pick the right one.

A **voice** is a speaker you can synthesize speech with. You add voices to your workspace from the
**Finesse dashboard**, then **list and use** them here.

<Note>
  You can also clone a voice from your own reference clip, in the dashboard or through the API -
  see [Clone a voice](/voice-api/clone-voice) and [Enroll a voice](/voice-api/enroll-voice). Cloning
  is free and counts against your plan's `max_voices` limit.
</Note>

## List what's available

Your API key can see every voice in its workspace. Fetch them with
[List voices](/voice-api/list-voices):

```bash theme={null}
curl "https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices" \
  -H "X-API-Key: $FLAM_API_KEY"
```

Each item is a [Voice object](/voice-api/voice-object). Use its `id` with the synthesize endpoints.

## Only `ready` voices can be used

A voice's `status` tells you whether it's usable:

<ResponseField name="ready">
  Trained and ready - you can synthesize with it.
</ResponseField>

<ResponseField name="processing">
  Still being created/cloned. Poll the [clone job](/voice-api/get-job) or check back shortly.
</ResponseField>

<ResponseField name="failed">
  Creation didn't succeed. Recreate or re-enroll the voice.
</ResponseField>

Synthesizing with a voice that isn't `ready` returns `400` - see [Errors](/voice-api/errors).

## Pick the right voice

Beyond `name`, each voice carries attributes you can match on:

* **`primary_language`** - the default language (BCP-47, e.g. `en`, `hi`). A synthesis request can
  override it per call.
* **`labels`** - key/value tags like `accent`, `gender`, `age`, and `use_case`, e.g.
  `{ "key": "accent", "value": "american" }`. Filter client-side to choose a voice.
* **`sample_audio_url`** - a short preview clip, when available, so you can audition a voice before
  using it.

```javascript Choosing a female English voice theme={null}
const res = await fetch(
  `https://fi.production.flamapis.com/flam-voice-svc/api/v1/public/voices`,
  { headers: { "X-API-Key": process.env.FLAM_API_KEY } },
);
const { data } = await res.json();

const voice = data.voices.find(
  (v) =>
    v.status === "ready" &&
    v.primary_language === "en" &&
    v.labels?.some((l) => l.key === "gender" && l.value === "female"),
);
```

## Next

<CardGroup cols={2}>
  <Card title="List voices" icon="list" href="/voice-api/list-voices">
    The full endpoint reference.
  </Card>

  <Card title="Clone a voice" icon="clone" href="/voice-api/clone-voice">
    Create a voice from a reference clip via the API.
  </Card>

  <Card title="Synthesize speech" icon="waveform" href="/voice-api/synthesize-speech">
    Use a voice id to generate audio.
  </Card>
</CardGroup>


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