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.

You can also clone a voice from your own reference clip, in the dashboard or through the API - see Clone a voice and Enroll a voice. Cloning is free and counts against your plan’s max_voices limit.

List what’s available

Your API key can see every voice in its workspace. Fetch them with List voices:

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. Use its id with the synthesize endpoints.

Only ready voices can be used

A voice’s status tells you whether it’s usable:

ready

Trained and ready - you can synthesize with it.

processing

Still being created/cloned. Poll the clone job or check back shortly.

failed

Creation didn’t succeed. Recreate or re-enroll the voice.

Synthesizing with a voice that isn’t ready returns 400 - see 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.

Choosing a female English voice

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

List voices

The full endpoint reference.

Clone a voice

Create a voice from a reference clip via the API.

Synthesize speech

Use a voice id to generate audio.