Installation - Finesse

Install

npm install @flamai/finesse ws

pnpm add @flamai/finesse ws

yarn add @flamai/finesse ws

bun add @flamai/finesse

ws is only needed for realtime in Node. Bun, Deno and browsers have a built-in WebSocket.

Get an API key

Sign in to the Finesse dashboard.
Open Settings → API keys and create a key. Copy it right away: it is shown only once, and it starts with flv_.
Put it in your environment, where the SDK finds it:

export FINESSE_API_KEY="flv_..."

The API Keys page in the Finesse dashboard: name a key, press Create key, and copy it once

Keep the key on your server. Anyone who has it can spend your workspace’s credits. For browsers and devices, use a short-lived token instead.

Make a first call

import { writeFile } from "node:fs/promises";
import { Finesse, isReady } from "@flamai/finesse";

const client = new Finesse(); // reads FINESSE_API_KEY

// Pick any voice you can use: your own, or one from the public catalog.
let voiceId = "";
for await (const voice of client.voices.list()) {
  if (isReady(voice)) {
    voiceId = voice.id;
    break;
  }
}

const audio = await client.speech.create({ voice_id: voiceId, text: "Hello from Finesse!" });
await writeFile("hello.wav", audio.data);

hello.wav is a 24 kHz WAV file.

Requirements

Node 18 or later, Bun, Deno, or a modern browser (with a token).
TypeScript 4.7 or later, if you use TypeScript. Types are included.
No runtime dependencies; ws for realtime in Node.

Runtimes

Runtime	HTTP	Realtime
Node 18+	built-in `fetch`	needs `ws`; the API key goes in a header
Bun	built-in	built-in `WebSocket`; the API key goes in a header
Deno	built-in	built-in `WebSocket`; from 2.5 the key goes in a header
Browsers	with `accessToken`	built-in `WebSocket`; the token is a subprotocol

Browsers can’t keep an API key secret, so a client holding a key refuses to run in one. Use a short-lived token instead.

Versioning

The SDK follows semantic versioning. Before 1.0, minor versions may include breaking changes; they are listed in the SDK changelog.

import { VERSION } from "@flamai/finesse";