Configuration

Client options

Option	Environment variable	Default
`apiKey`	`FINESSE_API_KEY`	required, unless `accessToken`
`accessToken`		none (a short-lived `fin_tok_` token)
`timeout`		120 000 ms
`maxRetries`		2
`defaultHeaders`		none
`fetch`		the global `fetch`
`dangerouslyAllowBrowser`		`false`
`logLevel`	`FINESSE_LOG`	`"off"`
`logger`		`console`

Per-request options

Every request method accepts options for that call only, as its last argument: { signal, timeout, maxRetries, headers }.

await client.speech.create(
  { voice_id, text: "Hello!" },
  { timeout: 30_000, maxRetries: 0, headers: { "X-Request-Id": "abc-123" } },
);

Raw responses

withRawResponse has the same methods and returns the HTTP response along with the result:

const { data: audio, status, requestId, headers } = await client.withRawResponse.speech.create({
  voice_id,
  text: "Hello!",
});
console.log(status, requestId, headers.get("x-sample-rate"));

Logging

Set FINESSE_LOG=debug to log every request (method, URL, status, timing, request ID), or FINESSE_LOG=info to log only retries. The SDK never logs your API key, request bodies or audio. You can also set logLevel on the client, and pass logger to send the lines somewhere other than console.

Copy a client with other defaults

const quick = client.withOptions({ timeout: 10_000, maxRetries: 0 });
await quick.voices.get(voiceId);

The copy shares the original client’s connections.

Custom HTTP client

const client = new Finesse({ fetch: myFetch });

Identify your integration

Requests identify the SDK with an X-Finesse-Client header. If you build an integration on top of the SDK, name it so it shows up in your usage analytics:

const client = new Finesse({ defaultHeaders: { "X-Finesse-Client": "my-app/1.0.0" } });

TypeScript SDK

Reference

Client options

Per-request options

Raw responses

Logging

Copy a client with other defaults

Custom HTTP client

Identify your integration

​Client options

​Per-request options

​Raw responses

​Logging

​Copy a client with other defaults

​Custom HTTP client

​Identify your integration

Client options

Per-request options

Raw responses

Logging

Copy a client with other defaults

Custom HTTP client

Identify your integration